integrations

type Bundle struct{ Access, Refresh, Account string }

type Connection struct {
	Org      string
	Provider string
	// Owner is the provider-side account this connection is FOR — a GitHub org
	// login, empty for a provider with one account per org. Part of the key, so
	// one Hanzo org can hold several accounts of the same provider.
	Owner        string
	ExternalID   string
	AccountLabel string
	BotUserID    string
	Scopes       []string
	ConnectedAt  int64
	UpdatedAt    int64
}

type Connector struct {
	Org, User, Provider, Label string
	ExternalID, AccountLabel   string
	Scopes                     []string
	ExpiresAt                  int64 // access-token expiry, unix seconds; 0 = non-expiring
	ConnectedAt, UpdatedAt     int64
}

type Device struct {
	Start func(ctx context.Context) (*DeviceStart, error)
	Poll  func(ctx context.Context, g Grant) (*DevicePoll, error)
}

type DevicePoll struct {
	Status   string
	Interval int64           // seconds; pollSlow and throttled pending
	Result   *ExchangeResult // pollDone only
}

type DeviceStart struct {
	Code, UserCode, VerifyURL string
	Interval                  int64 // seconds between polls, raw from the provider
	ExpiresAt                 int64 // unix seconds
}

type ExchangeResult struct {
	Tokens       map[string]string // secret name -> value (sealed into KMS)
	ExternalID   string            // provider account id (Slack team.id / GitHub installation_id)
	AccountLabel string            // human label (Slack team.name / GitHub org login)
	BotUserID    string            // Slack bot_user_id (non-secret)
	Scopes       []string          // granted scopes
	ExpiresAt    int64             // access-token expiry, unix seconds; 0 = non-expiring/unknown. Set by user-plane device/refresh providers; the org plane ignores it.
}

type Grant struct {
	ID, Org, User, Provider, Label string
	Code, UserCode                 string
	Interval                       int64 // seconds between polls
	LastPollAt                     int64 // unix seconds of the last upstream poll; 0 = never
	CreatedAt, ExpiresAt           int64 // unix seconds
}

type Inbound struct {
	Provider   string // registry slug: "slack","teams","discord","telegram"
	ExternalID string // workspace/tenant/guild/chat id → OrgForExternalID (isolation root)
	User       string // platform-verified user id (billing/attribution subject via the link)
	Channel    string // reply target (channel/conversation/chat id)
	ThreadID   string // thread/message id to reply under (optional)
	Text       string // the user's prompt, mention stripped
	DedupeKey  string // event/update/interaction id ("" ⇒ non-dedupable)
}

type IngressEvent struct {
	Org       string
	In        Inbound
	ReplyRoot string
}

type OAuthConfig struct {
	ClientID     string
	ClientSecret string
	Extra        map[string]string
}

type Provider struct {
	ID           string   // stable slug, the :provider path segment ("slack","github")
	Name         string   // display name
	Description  string   // one-line card copy
	Category     string   // grouping ("Communication","Developer",...)
	Scopes       []string // requested scopes (display + authorize URL)
	RedirectPath string   // OAuth redirect path; MUST equal /v1/integrations/{id}/callback
	Secrets      []string // KMS secret names this provider custodies (deleted on disconnect)

	// Kind selects credential acquisition. Empty/"oauth" (default) uses the
	// 3-legged Authorize/Exchange flow. "apikey" (apiKeyKind) takes a
	// customer-held credential submitted to /connect (from `hanzo connector add`,
	// read on STDIN — never argv/URL), VERIFIES it live, and seals it to KMS; such
	// providers use Verify, not Authorize/Exchange, and have no OAuth callback.
	Kind string
	// AdminOnly gates /connect and /disconnect on the caller being an admin of its
	// OWN org (principal.IsOrgAdmin — NOT SuperAdmin), parity with the platform
	// deploy-provider adminProcedure. OAuth social/chat providers leave it false.
	// MultiAccount marks a provider that can be connected once per PROVIDER-SIDE
	// account. A GitHub App is installed per account, so one org holding hanzoai,
	// hanzo-apps and hanzo-docs holds three connections; the account name is then
	// part of the key and each row carries its own installation. A provider with
	// one account per org leaves this false and keeps an empty owner, which is what
	// its callers look up.
	MultiAccount bool

	AdminOnly bool
	// Verify validates an apikey credential against the provider and returns the
	// token(s) to seal + non-secret account metadata. It MUST fail closed (a
	// bad/inactive credential returns an error and NOTHING is stored) and its error
	// MUST NOT contain the credential value (it is logged). nil for oauth providers.
	// On the user plane it doubles as the token/apikey intake method.
	Verify func(ctx context.Context, in VerifyInput) (*ExchangeResult, error)

	// Scope selects the custody plane: "" = org-scoped /v1/integrations (default);
	// userScope = per-user /v1/connectors (rows keyed (org,user,provider,label),
	// KMS under /orgs/{org}/users/{user}/connectors/...). The planes are disjoint:
	// a user-scoped provider 404s on the org surface and vice versa; Mount asserts
	// scope coherence at boot.
	Scope string
	// Device: device-code sign-in (user scope). nil = unsupported.
	Device *Device
	// Adopt verifies an externally obtained OAuth bundle (CLI local PKCE) before
	// custody. Implementations MUST live-verify (e.g. one refresh) and return the
	// rotated material — custody owns the canonical refresh token afterwards.
	// nil = unsupported.
	Adopt func(ctx context.Context, b Bundle) (*ExchangeResult, error)
	// Refresh trades a refresh token for rotated material. The result MUST carry
	// Secrets[0] and refreshSecret entries and an ExpiresAt. nil = static credential.
	Refresh func(ctx context.Context, refresh string) (*ExchangeResult, error)

	// Configured reports whether the provider's APP creds are present in ENV.
	// When false: available=false in the card, and connect/callback fail closed
	// with an honest 503 / failure redirect (never a dead-end, never a fake OK).
	// Org plane only — nil for Scope == userScope (nothing on the user plane
	// calls it; list() skips user providers before providerViewFor).
	Configured func() bool
	// Creds resolves the APP creds from ENV. Called only when Configured is true.
	// Org plane only — nil for Scope == userScope.
	Creds func() OAuthConfig
	// Authorize builds the provider's consent URL for (creds, redirectURI, state).
	Authorize func(creds OAuthConfig, redirectURI, state string) (string, error)
	// AuthorizeReady reports whether the Authorize leg has the credentials it
	// needs. OPTIONAL: when nil the leg is standard OAuth2 and readiness is
	// ClientID being set. A provider whose authorize leg is NOT OAuth sets this
	// so the gate asks the provider instead of assuming — a GitHub App install
	// URL is built from the app slug and has no client id at all, so without this
	// its connect flow is refused for a credential it never uses.
	AuthorizeReady func() bool
	// Exchange trades the OAuth code for tokens + account metadata.
	Exchange func(ctx context.Context, creds OAuthConfig, redirectURI, code string) (*ExchangeResult, error)
	// Revoke best-effort invalidates a token at the provider on disconnect. nil
	// when the provider has no revoke endpoint.
	Revoke func(ctx context.Context, creds OAuthConfig, token string) error

	// #51 seams — declared, nil today, not wired to a route (see SyncHook/WritebackHook).
	Sync      SyncHook
	Writeback WritebackHook
}

type Store struct {
	// contains filtered or unexported fields
}

type SyncHook func(ctx context.Context, conn Connection) error

type TriggerFunc func(ctx context.Context, org, source, name, dedupeKey string, depth int, payload map[string]any) (int, error)

type VerifyInput struct {
	Token     string
	AccountID string
}

type WritebackHook func(ctx context.Context, conn Connection, payload []byte) error