App Webhook Delivery Toolkit

package appmanager

import (
    "context"
    "time"
)

// Client defines the app-scoped GitHub API surface the manager relies on.
type Client interface {
    CompleteManifest(ctx context.Context, code string) (AppSecrets, error)
    CreateInstallationToken(ctx context.Context, installationID int64) (InstallationTokenInfo, error)
    ListWebhookDeliveries(ctx context.Context, limit int, cursor string) (DeliveryPage, error)
    GetWebhookDelivery(ctx context.Context, deliveryID int64) (DeliverySummary, error)
    RedeliverWebhook(ctx context.Context, deliveryID int64) (DeliverySummary, error)
}

// AppManager orchestrates manifest onboarding, token refresh, and webhook delivery controls.
type AppManager struct {
    client        Client
    refreshWindow time.Duration
}

// NewAppManager builds a manager with the provided GitHub App client and refresh window for tokens.
func NewAppManager(client Client, refreshWindow time.Duration) *AppManager

// CompleteManifest exchanges a one-time manifest code for secrets and returns them together.
func (m *AppManager) CompleteManifest(ctx context.Context, code string) (AppSecrets, error)

// InstallationToken returns a cached token if it remains valid beyond the refresh window; otherwise it refreshes and returns a new token with updated expiry.
func (m *AppManager) InstallationToken(ctx context.Context, installationID int64) (InstallationTokenInfo, error)

// ListDeliveries returns a page of webhook deliveries for the app respecting the limit and cursor, plus the next cursor when present.
func (m *AppManager) ListDeliveries(ctx context.Context, limit int, cursor string) (DeliveryPage, error)

// RedeliverDelivery triggers a redelivery for the given webhook delivery ID and returns the latest delivery details after requeueing.
func (m *AppManager) RedeliverDelivery(ctx context.Context, deliveryID int64) (DeliverySummary, error)

// AppSecrets captures credentials returned after completing the manifest handshake.
type AppSecrets struct {
    Slug          string
    ClientID      string
    ClientSecret  string
    WebhookSecret string
    PrivateKeyPEM string
}

// InstallationTokenInfo captures the token value and expiry timestamp.
type InstallationTokenInfo struct {
    Token     string
    ExpiresAt time.Time
}

// DeliverySummary captures webhook delivery status data.
type DeliverySummary struct {
    ID           int64
    Status       string
    Redelivery   bool
    DeliveredAt  time.Time
    RequestID    string
}

// DeliveryPage bundles delivery entries and pagination cursor.
type DeliveryPage struct {
    Deliveries []DeliverySummary
    NextCursor string
}