git-pkgs/forge

The forge APIs all support webhooks for real-time event delivery, but the library has no webhook support. Two possible scopes: Webhook management: Create/list/delete webhooks via the API (GitHub, GitLab, Gitea/Forgejo all have endpoints for this) Event parsing: Parse incoming webhook payloads into normalized event types, similar to how the library normalizes API responses across forges Event parsing would be particularly useful since each forge has its own webhook payload format and event names. A unified event type system would let consumers handle webhook events without forge-specific code. This could live alongside the existing polling-based NotificationService as an alternative real-time delivery mechanism.

The forge APIs support managing notification subscriptions (watch/unwatch repos, subscribe/unsubscribe/ignore threads) but the library doesn't expose this. GitHub: PUT /repos/{owner}/{repo}/subscription (watch repo), PUT /notifications/threads/{id}/subscription (subscribe/ignore thread) GitLab: subscription endpoints for projects and issues/MRs Gitea/Forgejo: PUT /repos/{owner}/{repo}/subscription (watch repo) This would allow consumers to programmatically mute/unmute notification threads and manage repo watch settings, syncing these preferences back to the forge rather than only tracking them locally.

The Notification struct doesn't include the subject's ID or number (e.g. issue number, PR number), even though the underlying forge APIs provide this information. GitHub: notification.Subject.URL contains /repos/owner/repo/issues/123 GitLab: todo.Target.IID is the issue/MR number directly Gitea/Forgejo: notification.Subject.HTMLURL contains the issue/PR number in the URL path Currently the conversion functions in github/notifications.go, gitlab/notifications.go, and gitea/notifications.go read the subject title and type but discard the subject URL and ID. Adding a SubjectID (or SubjectNumber) and SubjectURL field to the Notification struct would let consumers link notifications to their underlying issues/PRs without making additional API calls. The URL field is also inconsistent across forges: GitHub sets it to the repository HTML URL, while GitLab and Gitea set it to the subject URL. Having separate URL (subject web URL) and Repo fields would make this unambiguous.

The forge APIs all support fetching the authenticated user's profile but the library doesn't expose this. GitHub: GET /user GitLab: GET /api/v4/user Gitea/Forgejo: GET /api/v1/user A GetAuthenticatedUser() method on the Forge interface (or a new UserService) would allow consumers to get the current user's username, avatar URL, and email after authenticating. This is needed for applications that use OAuth to authenticate users via forges and need to display user profile information.

Record real API responses from forges and replay them in tests. This avoids hand-written mocks while keeping tests deterministic and fast. Record mode hits the real API and saves responses to fixture files. Replay mode serves those fixtures without network access. New tests or updated APIs just need a re-record.