httpapi

type APIKeyView struct {
	ID        string `json:"id"`
	Name      string `json:"name"`
	KeyPrefix string `json:"key_prefix" doc:"Non-secret visible prefix (e.g. e2a_acct_… / e2a_agt_…)."`
	// Scope is an OPEN set on this response view (evolving vocabulary); the
	// REQUEST-side CreateAPIKeyRequest.scope keeps its closed enum, which is
	// where validation belongs.
	Scope      string     `` /* 203-byte string literal not displayed */
	Agent      string     `json:"agent_email,omitempty" doc:"Bound inbox email for agent-scoped keys; omitted for account scope."`
	CreatedAt  time.Time  `json:"created_at"`
	LastUsedAt *time.Time `json:"last_used_at,omitempty"`
	ExpiresAt  *time.Time `json:"expires_at,omitempty"`
}

type AccountUserView struct {
	ID    string `json:"id"`
	Email string `json:"email"`
}

type AccountView struct {
	User AccountUserView `json:"user"`
	// Scope is an OPEN set on this response view (evolving vocabulary), not a
	// closed enum — see docs/api.md "Versioning & stability".
	Scope        string          `` /* 166-byte string literal not displayed */
	AgentAddress string          `json:"agent_email,omitempty"`
	PlanCode     string          `json:"plan_code"`
	Limits       LimitsCapsView  `json:"limits"`
	Usage        LimitsUsageView `json:"usage"`
	UpgradeURL   string          `json:"upgrade_url"`
}

type AddressParam struct {
	Address string `path:"email" doc:"The agent's full email address, e.g. support@acme.com."`
}

type AgentCreateEnforcer func(ctx context.Context, userID string) error

type AgentCreator func(ctx context.Context, email, domain, name, webhookURL, agentMode, userID string) (*identity.AgentIdentity, error)

type AgentDeleter func(ctx context.Context, agentID, userID string) (messagesDeleted int64, err error)

type AgentGetter func(ctx context.Context, address string) (*identity.AgentIdentity, error)

type AgentLister func(ctx context.Context, userID string, limit int, afterCreatedAt time.Time, afterID string) ([]identity.AgentIdentity, error)

type AgentSuppressionView struct {
	AgentEmail string    `json:"agent_email"`
	Address    string    `json:"address"`
	Reason     string    `json:"reason,omitempty"`
	Source     string    `json:"source" doc:"How the block was created. Known values: unsubscribe, manual."`
	CreatedAt  time.Time `json:"created_at"`
}

type AgentTrashOp func(ctx context.Context, agentID, userID string) error

type AgentView struct {
	Domain           string    `json:"domain" doc:"The exact domain in the agent email address."`
	RegisteredDomain string    `` /* 170-byte string literal not displayed */
	Email            string    `json:"email"`
	Name             string    `json:"name"`
	DomainVerified   bool      `json:"domain_verified"`
	CreatedAt        time.Time `json:"created_at"`
	// DeletedAt marks an agent in the trash (soft-deleted): set when the row
	// was moved there, omitted on live agents. Trashed agents appear only via
	// GET /v1/agents?deleted=true and restore/permanent-delete operations; they
	// are purged ~30 days after deletion (docs/design/trash-soft-delete.md).
	DeletedAt *time.Time `` /* 278-byte string literal not displayed */
}

type AttachmentMetaView = eventpayload.AttachmentMetaView

type AttachmentStore interface {
	// DownloadURL returns a short-lived URL the caller (or a sandboxed tool) can
	// GET for the bytes, plus its expiry.
	DownloadURL(agentEmail, messageID string, index int, ttl time.Duration) (downloadURL string, expiresAt time.Time, err error)
	// VerifyDownload reports whether `token` authorizes downloading attachment
	// `index` of `messageID` (and is unexpired). Identity is NOT in the token;
	// the download handler additionally binds the message to the path agent.
	VerifyDownload(token, messageID string, index int) bool
}

type AttachmentView struct {
	Index       int       `json:"index"`
	Filename    string    `json:"filename,omitempty"`
	ContentType string    `json:"content_type,omitempty"`
	ContentID   string    `` /* 182-byte string literal not displayed */
	SizeBytes   int       `` /* 229-byte string literal not displayed */
	DownloadURL string    `json:"download_url"`
	ExpiresAt   time.Time `json:"expires_at" format:"date-time"`
	// Data is the base64 bytes, present ONLY when inline=true and the attachment
	// is within the inline size cap.
	Data string `json:"data,omitempty"`
}

type Authenticator func(r *http.Request) (*identity.User, error)

type ConversationDetailView struct {
	ConversationSummaryView
	Participants []string             `json:"participants" nullable:"false"`
	Labels       []string             `json:"labels" nullable:"false"`
	Messages     []MessageSummaryView `json:"messages" nullable:"false"`
}

type ConversationGetter func(ctx context.Context, agentID, conversationID string) (*identity.ConversationDetail, error)

type ConversationIDParam struct {
	Address        string `path:"email"`
	ConversationID string `path:"id"`
}

type ConversationLister func(ctx context.Context, filter identity.ConversationListFilter) ([]identity.ConversationSummary, error)

type ConversationSummaryView struct {
	ID             string    `json:"id"`
	LastMessageAt  time.Time `json:"last_message_at" format:"date-time"`
	FirstMessageAt time.Time `json:"first_message_at" format:"date-time"`
	MessageCount   int       `json:"message_count"`
	InboundCount   int       `json:"inbound_count"`
	OutboundCount  int       `json:"outbound_count"`
	HasUnread      bool      `json:"has_unread"`
	LatestSubject  string    `json:"latest_subject"`
	LatestSender   string    `json:"latest_from"`
}

type CoveringDomainLookup func(ctx context.Context, sub, userID string) (*identity.Domain, error)

type CreateAPIKeyRequest struct {
	Name      string `json:"name,omitempty" maxLength:"200" doc:"Human label for the key. At most 200 characters (Unicode code points)."`
	ExpiresAt string `` /* 139-byte string literal not displayed */
	Scope     string `json:"scope,omitempty" enum:"account,agent" doc:"account = workspace admin (default); agent = bound to a single inbox."`
	Agent     string `json:"agent_email,omitempty" doc:"Inbox email to bind the key to; required when scope=agent."`
}

type CreateAPIKeyResponse struct {
	APIKeyView
	Key string `json:"key" doc:"The secret key. Shown once; store it now — it cannot be retrieved later."`
}

type CreateAgentRequest struct {
	Email string `` /* 129-byte string literal not displayed */
	Name  string `` /* 197-byte string literal not displayed */
}

type CreateAgentSuppressionRequest struct {
	Address string `` /* 137-byte string literal not displayed */
	Reason  string `` /* 135-byte string literal not displayed */
}

type CreateTemplateRequest struct {
	Name        string `json:"name,omitempty" doc:"Human-readable template name. Required unless from_starter supplies the default."`
	Alias       string `` /* 126-byte string literal not displayed */
	Subject     string `` /* 139-byte string literal not displayed */
	Body        string `json:"text,omitempty" doc:"Plain-text body template source (no HTML escaping). Required unless from_starter is set."`
	HTMLBody    string `json:"html,omitempty" doc:"Optional HTML body template source ({{x}} is HTML-escaped, {{{x}}} is raw)."`
	FromStarter string `` /* 392-byte string literal not displayed */
}

type CreateWebhookRequest struct {
	URL         string                 `json:"url" doc:"Required, non-empty webhook delivery URL."`
	Events      []string               `` /* 492-byte string literal not displayed */
	Filters     *WebhookFiltersRequest `json:"filters,omitempty"`
	Description string                 `json:"description,omitempty"`
}

type CreateWebhookResponse struct {
	WebhookView
	SigningSecret string `json:"signing_secret"`
}

type DNSRecord struct {
	Type     string `json:"type" doc:"DNS record type. MX or TXT."`
	Name     string `json:"name" doc:"Record name (host). The apex domain for ownership/inbound_mx; an FQDN for dkim/mail_from records."`
	Value    string `json:"value" doc:"Record value. For MX records this is the mail-server host only; the priority is in the priority field."`
	Priority *int   `json:"priority" doc:"MX priority. Null for non-MX records."`
	Purpose  string `` /* 402-byte string literal not displayed */
	Status   string `` /* 1431-byte string literal not displayed */
}

type DeleteAgentResult struct {
	Deleted         bool   `` /* 126-byte string literal not displayed */
	Email           string `json:"email" doc:"Email address of the deleted agent."`
	MessagesDeleted int64  `json:"messages_deleted" doc:"Number of messages permanently removed by the cascade; zero when the agent is moved to trash."`

} // @name DeleteAgentResult

type DeleteApiKeyResult struct {
	Deleted bool   `json:"deleted" doc:"Always true — the key is revoked. A failed delete is an error envelope, never deleted:false."`
	ID      string `json:"id" doc:"ID of the revoked API key."`

} // @name DeleteApiKeyResult

type DeleteConfirm struct {
	Confirm string `query:"confirm" enum:"DELETE" required:"true" doc:"Must be the literal DELETE — this action is irreversible."`
}

type DeleteDomainResult struct {
	Deleted bool   `json:"deleted" doc:"Always true — the domain no longer exists. A failed delete is an error envelope, never deleted:false."`
	Domain  string `json:"domain" doc:"The deleted domain."`

} // @name DeleteDomainResult

type DeleteMessageResult struct {
	Deleted bool   `` /* 146-byte string literal not displayed */
	ID      string `json:"id" doc:"ID of the deleted message."`

} // @name DeleteMessageResult

type DeleteSuppressionResult struct {
	Deleted bool   `` /* 132-byte string literal not displayed */
	Address string `json:"address" doc:"The un-suppressed recipient address."`

} // @name DeleteSuppressionResult

type DeleteTemplateResult struct {
	Deleted bool   `` /* 126-byte string literal not displayed */
	ID      string `json:"id" doc:"ID of the deleted template."`

} // @name DeleteTemplateResult

type DeleteWebhookResult struct {
	Deleted bool   `json:"deleted" doc:"Always true — the webhook no longer exists. A failed delete is an error envelope, never deleted:false."`
	ID      string `json:"id" doc:"ID of the deleted webhook."`

} // @name DeleteWebhookResult

type DeploymentInfoView struct {
	Version                 string `json:"version"`
	SharedDomain            string `json:"shared_domain"`
	SlugRegistrationEnabled bool   `json:"slug_registration_enabled"`
	PublicURL               string `json:"public_url,omitempty"`
}

type Deps struct {
	Authenticator          Authenticator
	PrincipalAuthenticator PrincipalAuthenticator
	// AuthChallenge builds the RFC 6750 §3 WWW-Authenticate header value for a
	// request that failed authentication. Injected so the v1 surface advertises
	// the Bearer scheme (and OAuth error params) on every 401 exactly like the
	// legacy mux did, from the same definition (agent.API.WWWAuthenticateChallenge).
	// Optional — nil disables the challenge header.
	AuthChallenge func(r *http.Request) string
	ListAgents    AgentLister
	GetAgent      AgentGetter
	GetMessage    MessageGetter
	ListMessages  MessageLister
	// ModifyMessageLabels applies a labels delta to a message scoped to an
	// agent, returning the post-update set. Mirrors store.ModifyMessageLabels.
	ModifyMessageLabels func(ctx context.Context, messageID, agentID string, add, remove []string) ([]string, error)

	ListConversations ConversationLister
	GetConversation   ConversationGetter

	CreateAgent          AgentCreator
	LookupDomain         DomainLookup
	LookupCoveringDomain CoveringDomainLookup
	// ResolveMX backs the required create-time subdomain MX gate.
	ResolveMX          MXResolver
	EnforceAgentCreate AgentCreateEnforcer
	// UpdateAgentName updates an agent's display name (the only mutable field on
	// the agent PATCH after the screening config moved to /protection).
	UpdateAgentName func(ctx context.Context, agentID, userID, name string) error
	// UpdateAgentProtection writes the full per-agent protection posture (gate +
	// scan sensitivity + holds) for the /v1/agents/{email}/protection resource.
	// Returns a validation error for an invalid posture, which the handler maps
	// to 400 invalid_request.
	UpdateAgentProtection func(ctx context.Context, agentID, userID string, cfg identity.ProtectionConfig) error
	// DeleteAgent is the DEFAULT delete: soft (move to trash, restorable for
	// identity.TrashRetention, docs/design/trash-soft-delete.md).
	// PermanentDeleteAgent is the irreversible hard delete behind
	// ?permanent=true; RestoreAgent brings a trashed agent back.
	DeleteAgent          AgentTrashOp
	PermanentDeleteAgent AgentDeleter
	RestoreAgent         AgentTrashOp
	// GetAgentAnyState loads an agent regardless of trash state (DeletedAt set
	// when trashed) — the resolution path for restore / permanent delete, which
	// must find agents the live GetAgent treats as nonexistent.
	GetAgentAnyState AgentGetter
	// ListDeletedAgents is the account's agent trash (GET /v1/agents?deleted=true).
	ListDeletedAgents AgentLister

	// Message trash ops (DELETE / POST restore on
	// /v1/agents/{email}/messages/{id}): soft delete, restore, and the
	// trash-only permanent purge.
	DeleteMessage  MessageTrashOp
	RestoreMessage MessageTrashOp
	PurgeMessage   MessageTrashOp

	// domains. ListDomains is keyset-paginated on (created_at, domain): the
	// handler passes limit+1 to detect a further page (limit<=0 = all), and the
	// after-key from the previous page's last row (zero afterCreatedAt = first
	// page).
	ListDomains         func(ctx context.Context, userID string, limit int, afterCreatedAt time.Time, afterDomain string) ([]identity.Domain, error)
	SendingRampSnapshot func(ctx context.Context, userID, domain string, now time.Time) (sendramp.Snapshot, error)
	ClaimDomain         func(ctx context.Context, domain, userID string) (*identity.Domain, error)
	EnforceDomainCreate func(ctx context.Context, userID string) error
	DeleteDomain        func(ctx context.Context, domain, userID string) error
	HasAgentsOnDomain   func(ctx context.Context, domain, userID string) (bool, error)

	// SMTPDomain is the relay's MX host, surfaced in the DNS records a
	// domain must publish (config smtp.domain).
	SMTPDomain string

	// SESRegion is the AWS region of the SES sending identity
	// (config sender_identity.ses_region). Non-empty ⇒ the sending feature is
	// enabled: domainView emits the deterministic mail_from_* records. Empty ⇒
	// sending is off and those records are omitted.
	SESRegion string

	// CursorSecret is the deployment HMAC secret (config.Signing.HMACSecret)
	// used to sign/verify pagination cursors so they are tamper-evident
	// (issue #144 M2). The same deployment key used by approvaltoken — no new
	// key. Handlers pass it to EncodeCursor and wrap it
	// in a 1-element slice for DecodeCursor (whose verify loop supports N for
	// a future secret rotation). Empty in minimal test setups, which is fine:
	// encode and verify stay consistent under the same (empty) key.
	CursorSecret string

	// Idempotency is the retry-safety store for unsafe writes (send/reply/
	// forward/redeliver). Optional — nil disables the Idempotency-Key path.
	Idempotency IdemStore

	// outbound (the shared live delivery path extracted from agent.API)
	DeliverOutbound func(ctx context.Context, user *identity.User, ag *identity.AgentIdentity, req outbound.SendRequest, msgType, replyToEmailMessageID string, referenced *identity.Message, idemCompleteTx agent.AcceptIdemCompleter) (*agent.OutboundResult, *agent.OutboundError)
	SendTest        func(ctx context.Context, ag *identity.AgentIdentity) (*agent.OutboundResult, *agent.OutboundError)
	// PollSendOutcome reads an async send's current delivery_status for wait=sent.
	// Optional — nil disables the wait valve (accepted is returned immediately).
	PollSendOutcome func(ctx context.Context, messageID string) (identity.SendOutcome, error)
	// HITL approve/reject (the held-draft decision)
	ApprovePending     func(ctx context.Context, userID, messageID, expectedAgentEmail string, ovr agent.ApproveOverrides, idemCompleteTx agent.ApproveIdemCompleter) (*identity.Message, *agent.OutboundError)
	RejectPending      func(ctx context.Context, userID, messageID, expectedAgentEmail, reason string) (*identity.Message, *agent.OutboundError)
	EnforceMessageSend func(ctx context.Context, userID string) error
	// Inbound review release — the held-screening decision (design 2026-06-22 §5).
	// GetReviewMessage resolves a held message's direction so /approve+/reject can
	// branch (it intentionally sees held inbound statuses, scoped to the resolved
	// owned agent — account-scope only). ApproveInboundReview releases the message
	// to the agent's inbox; RejectInboundReview drops it. Both fire the unified
	// review_approved/review_rejected events. Optional — nil leaves the endpoints
	// outbound-only (pre-slice-3 behavior).
	GetReviewMessage     func(ctx context.Context, messageID, agentID string) (*identity.ReviewMessageMeta, error)
	ApproveInboundReview func(ctx context.Context, userID string, msg *identity.ReviewMessageMeta) *agent.OutboundError
	RejectInboundReview  func(ctx context.Context, userID, reason string, msg *identity.ReviewMessageMeta) *agent.OutboundError

	// Review queue (account-scoped /v1/reviews). ListReviews returns all holds
	// (both directions) across the user's agents; GetReviewWithContent loads one
	// held message (ownership-scoped) for the detail view + approve/reject
	// resolution. Both intentionally include held inbound — operator surface only.
	// ListReviews is keyset-paginated on (created_at, id): the handler passes
	// limit+1 to detect a further page and the after-key from the previous page's
	// last row (zero afterCreatedAt = first page).
	ListReviews          func(ctx context.Context, userID string, limit int, afterCreatedAt time.Time, afterID string) ([]identity.ReviewListItem, error)
	GetReviewWithContent func(ctx context.Context, userID, messageID string) (*identity.Message, error)
	// ListProtectionEventsByMessage returns the per-message screening audit
	// rows (gate + scan producers) behind a hold — the source of the detector
	// rationale/categories shown on the review detail. Optional; when nil the
	// detail omits the `protection` breakdown and clients fall back to the coded
	// review_reason. Callers must have already proven ownership of the message
	// (the review detail handler does, via GetReviewWithContent).
	ListProtectionEventsByMessage func(ctx context.Context, messageID string) ([]identity.ProtectionEvent, error)
	// SendLimit is the per-agent outbound rate limiter (mirrors
	// sendLimit.AllowWithRetryAfter; key = agent id). Optional.
	SendLimit func(key string) (ok bool, retryAfter time.Duration)
	// PollLimit is the per-user read limiter (key = user id) and RegLimit is
	// the per-IP agent-registration limiter (key = client ip). Both return
	// the IETF RateLimit snapshot so the middleware can set the headers.
	// Optional — nil disables that limiter on the /v1 surface.
	PollLimit RateSnapshot
	RegLimit  RateSnapshot
	// Raw capability routes sit outside Huma's authenticated middleware and use
	// separate per-IP budgets so traffic to one surface cannot starve another.
	// Optional — nil disables the corresponding limiter.
	DownloadLimit    RateSnapshot
	UnsubscribeLimit RateSnapshot
	// GetRepliableMessage loads a message that can be replied to or forwarded —
	// either an inbound the agent received or an outbound the agent sent — as
	// long as it is live (not expired) and not held/rejected in review. The
	// reply/forward handlers use this so an agent can continue a thread off its
	// own sent message (Gmail-style), which GetInboundMessage's direction filter
	// forbids.
	GetRepliableMessage func(ctx context.Context, messageID string) (*identity.Message, error)

	// AttachmentStore mints/verifies short-lived attachment downloads (§6a #5).
	// Native by default; when nil, the attachment endpoints are unavailable.
	AttachmentStore AttachmentStore

	// account
	GetLimits      func(ctx context.Context, userID string) (limits.Limits, error)
	GetUsage       func(ctx context.Context, userID string) LimitsUsageView
	ExportUserData func(ctx context.Context, userID string) (*identity.UserExport, error)

	// Suppression list (decision 9 / Slice 4b). Optional — nil deployments
	// return 501 from the /v1/account/suppressions endpoints.
	ListSuppressions  func(ctx context.Context, userID string, limit int, afterCreatedAt time.Time, afterAddress string) ([]identity.Suppression, error)
	RemoveSuppression func(ctx context.Context, userID, address string) (bool, error)
	// Agent suppressions are recipient consent blocks scoped to one exact
	// sending identity. Management is account-admin-only; the handler resolves
	// live ownership before calling these tenant-bound store methods.
	AddAgentSuppression    func(ctx context.Context, userID, agentID, address, reason, source string, onAdded identity.AgentSuppressionTxHook) (identity.AgentSuppression, bool, error)
	ListAgentSuppressions  func(ctx context.Context, userID, agentID string, limit int, afterCreatedAt time.Time, afterAddress string) ([]identity.AgentSuppression, error)
	RemoveAgentSuppression func(ctx context.Context, userID, agentID, address string) (bool, error)
	// Public managed-unsubscribe capabilities. Resolve accepts only a token hash;
	// the write capability accepts only the exact scope returned by that lookup,
	// so the unauthenticated route cannot choose an account, agent, or recipient.
	ResolveUnsubscribeToken           func(ctx context.Context, tokenHash []byte) (*identity.UnsubscribeScope, error)
	AddAgentSuppressionFromTokenScope func(ctx context.Context, scope identity.UnsubscribeScope, onAdded identity.AgentSuppressionTxHook) (identity.AgentSuppression, bool, error)
	// Shared transaction hook for both authenticated manual creation and the
	// public recipient flow; the store invokes it only for a newly inserted row.
	AgentSuppressionAddedHook identity.AgentSuppressionTxHook
	DeleteUserData            func(ctx context.Context, user *identity.User) (*identity.DeleteUserDataResult, error)

	// events (delivery log). EventQuery carries the filters + cursor
	// position; the closures bind the events pool in main.
	ListEvents func(ctx context.Context, q EventQuery) ([]agent.EventView, error)
	GetEvent2  func(ctx context.Context, userID, eventID string) (*agent.EventView, error)
	// redeliver
	LoadReplayEvent      func(ctx context.Context, userID, eventID string) (*agent.ReplayEvent, error)
	InsertReplayDelivery func(ctx context.Context, eventID, webhookID, eventType string, messageID *string, envelope []byte) (string, error)

	// EventsEnabled reflects whether the durable event log (the webhook_events
	// outbox) is populated on this deployment. Now unconditional in production;
	// the events handlers still gate on it so a deployment that ever disables the
	// outbox returns 501 events_log_disabled from list/get/redeliver instead of
	// masquerading as "no events". Webhook delivery is unaffected either way.
	EventsEnabled bool

	// webhooks
	// CreateWebhook mirrors identity.Store.CreateWebhookIdem: when the request
	// carries an Idempotency-Key the handler passes a completer that the store
	// runs INSIDE the insert transaction, committing the webhook row and the
	// cached replay response atomically (same-tx pattern as the send/approve
	// paths). idemCompleteTx is nil for unkeyed creates.
	CreateWebhook func(ctx context.Context, userID, url, description string, events []string, filters identity.WebhookFilters, idemCompleteTx identity.WebhookIdemCompleter) (*identity.Webhook, error)
	// ListWebhooks is keyset-paginated on (created_at, id): the handler passes
	// limit+1 to detect a further page (limit<=0 = all) and the after-key from the
	// previous page's last row (zero afterCreatedAt = first page).
	ListWebhooks  func(ctx context.Context, userID string, limit int, afterCreatedAt time.Time, afterID string) ([]identity.Webhook, error)
	GetWebhook    func(ctx context.Context, webhookID, userID string) (*identity.Webhook, error)
	UpdateWebhook func(ctx context.Context, webhookID, userID string, u identity.WebhookUpdate) (*identity.Webhook, error)
	DeleteWebhook func(ctx context.Context, webhookID, userID string) error
	RotateSecret  func(ctx context.Context, webhookID, userID string) (string, time.Time, error)
	// TestWebhookInsert schedules a synthetic delivery (subscriberStore.
	// InsertPendingForTest). ListDeliveries reads the per-webhook delivery
	// log (subscriberStore.ListDeliveriesByWebhook).
	TestWebhookInsert func(ctx context.Context, webhookID, eventType string, envelope []byte) (string, error)
	// ListDeliveries is keyset-paginated on (created_at, id): the handler passes
	// limit+1 to detect a further page and the after-key from the previous page's
	// last row (zero afterCreatedAt = first page). status optionally restricts to
	// pending|delivered|failed.
	ListDeliveries func(ctx context.Context, webhookID, status string, limit int, afterCreatedAt time.Time, afterID string) ([]webhook.SubscriberDelivery, error)
	// EnqueueDelivery enqueues a River webhook_deliver job for a
	// webhook_subscriber_deliveries row that was inserted directly — the /test
	// endpoint and the event-redelivery API. Those two surfaces bypass the outbox
	// drain (which enqueues in-tx), so without this call their rows carry no River
	// job and, now that River is the sole delivery engine, would never deliver.
	// Wired unconditionally in production. Optional — nil in minimal test setups
	// with no River client, where a test drains delivery rows by other means.
	EnqueueDelivery func(ctx context.Context, deliveryID string) error

	// templates (beta). Mirror the like-named identity.Store methods; every
	// lookup is scoped to the owning user (cross-user reads behave as
	// not-found). GetTemplate/GetTemplateByAlias also serve the send path's
	// template_id/template_alias resolution.
	CreateTemplate     func(ctx context.Context, userID string, in identity.TemplateCreate) (*identity.Template, error)
	ListTemplates      func(ctx context.Context, userID string, limit int, afterCreatedAt time.Time, afterID string) ([]identity.TemplateSummary, error)
	GetTemplate        func(ctx context.Context, templateID, userID string) (*identity.Template, error)
	GetTemplateByAlias func(ctx context.Context, alias, userID string) (*identity.Template, error)
	UpdateTemplate     func(ctx context.Context, templateID, userID string, u identity.TemplateUpdate) (*identity.Template, error)
	DeleteTemplate     func(ctx context.Context, templateID, userID string) error

	// API keys (account-scope management). CreateScopedAPIKey returns the
	// minted key including its one-time plaintext; agentID is "" for account
	// scope and a resolved agent id for agent scope.
	CreateScopedAPIKey func(ctx context.Context, userID, name, scope, agentID string, expiresAt *time.Time) (*identity.APIKey, error)
	ListAPIKeys        func(ctx context.Context, userID string, limit int, afterCreatedAt time.Time, afterID string) ([]identity.APIKey, error)
	DeleteAPIKey       func(ctx context.Context, keyID, userID string) error

	// domain verification
	TouchDomainChecked func(ctx context.Context, domain, userID string) error
	VerifyDomain       func(ctx context.Context, domain, userID string) error
	// EnqueueSenderProvision (decision 4 / Slice 4) schedules SES sending-
	// identity provisioning for a verified domain. Called on every successful
	// verify check (newly OR already verified), so POST /domains/{domain}/verify
	// doubles as the forced sending re-check. Optional — nil when SES is not
	// configured (dev/self-host), leaving sending_status at none (relay From).
	EnqueueSenderProvision func(ctx context.Context, domain string)
	// VerifyProbe runs the live DNS check for a domain's published records.
	// Injected so it is fakeable in tests (the real one wraps
	// agent.CheckDomainRecords).
	VerifyProbe func(domain, verificationToken, dkimSelector, dkimPublicKey string) DomainCheckResult

	// Deployment info surfaced by GET /v1/info.
	SharedDomain string
	PublicURL    string

	// WSHandle serves the WebSocket upgrade for an agent address (the real-
	// time inbound transport). Injected so httpapi need not depend on the ws
	// package; the real one is ws.Handler.ServeWithEmail.
	WSHandle func(w http.ResponseWriter, r *http.Request, address string)

	// Legacy is the existing gorilla/mux handler. The chi root falls back
	// to it for every route not yet ported onto Huma (the strangler), so
	// the service stays fully functional through the multi-sub-slice port.
	Legacy http.Handler
}

type DomainCheckResult struct {
	TXTFound bool
	MX       string
	SPF      string
	DKIM     string
}

type DomainLookup func(ctx context.Context, domain, userID string) (*identity.Domain, error)

type DomainParam struct {
	Domain string `path:"domain"`
}

type DomainView struct {
	Domain            string `json:"domain"`
	Verified          bool   `json:"verified"`
	VerificationToken string `json:"verification_token"`
	// DNSRecords is the unified, purpose-tagged set of records the customer must
	// publish. ALL applicable records are returned at register time (they are
	// deterministic), so onboarding is a single paste — sending records do not
	// wait for the domain to verify.
	DNSRecords    []DNSRecord `json:"dns_records" nullable:"false"`
	CreatedAt     time.Time   `json:"created_at"`
	VerifiedAt    *time.Time  `json:"verified_at,omitempty"`
	LastCheckedAt *time.Time  `json:"last_checked_at,omitempty"`
	AgentCount    int         `json:"agent_count"`
	// Sender identity (decision 4 / Slice 4). Independent of `verified`
	// (inbound ownership): the async SES sending identity that lets agents
	// on this domain send as their own address. This is the rollup over the
	// dkim + mail_from_* records' per-record status; poll GET /domains/{domain}
	// to watch it go pending → verified|failed.
	SendingStatus        string     `` /* 152-byte string literal not displayed */
	SendingError         string     `json:"sending_error,omitempty"`
	SendingLastCheckedAt *time.Time `json:"sending_last_checked_at,omitempty"`
	// SendingRamp is platform-managed and deliberately read-only. Customers can
	// observe why accepted mail is waiting but cannot weaken the reputation guard.
	SendingRamp SendingRampView `json:"sending_ramp"`
}

type ErrorBody struct {
	Code      string `` /* 3510-byte string literal not displayed */
	Message   string `json:"message" doc:"Human-readable explanation. Not for branching — use code."`
	Details   any    `` /* 167-byte string literal not displayed */
	RequestID string `json:"request_id" doc:"Echoes the X-Request-Id response header so a failing call is greppable in logs."`
}

type ErrorEnvelope struct {
	Err ErrorBody `json:"error"`
	// contains filtered or unexported fields
}

type EventEnvelope struct {
	Type          string         `json:"type" doc:"Open event type; clients must tolerate unknown values."`
	ID            string         `json:"id" doc:"Stable across retries and push channels; use it to deduplicate at-least-once delivery."`
	SchemaVersion string         `json:"schema_version" doc:"Open envelope-version string; the current server emits 1."`
	CreatedAt     time.Time      `json:"created_at" format:"date-time"`
	Data          map[string]any `` /* 142-byte string literal not displayed */
}

type EventQuery struct {
	UserID                        string
	Type, AgentID, ConversationID string
	MessageID                     string
	Since, Until                  *time.Time
	CursorCreatedAt               time.Time
	CursorID                      string
	Limit                         int
}

type FieldError struct {
	Location string `` /* 222-byte string literal not displayed */
	Message  string `json:"message" doc:"Human-readable reason this field is invalid."`
}

type ForwardRequest struct {
	To []string `` // required (MSG-3)
	/* 227-byte string literal not displayed */
	CC             []string              ``                                /* 232-byte string literal not displayed */
	BCC            []string              ``                                /* 234-byte string literal not displayed */
	Body           string                `json:"text" maxLength:"1048576"` // required (MSG-3); subject derived as "Fwd:"
	HTMLBody       string                `json:"html,omitempty" maxLength:"1048576"`
	ConversationID string                `` /* 361-byte string literal not displayed */
	ReplyTo        string                `` /* 282-byte string literal not displayed */
	Attachments    []outbound.Attachment `` /* 402-byte string literal not displayed */
	Unsubscribe    UnsubscribeOptions    `` /* 149-byte string literal not displayed */
}

type HoldReasonView struct {
	Type       string   `json:"type" doc:"Producer that caused the hold. Open set; tolerate unknown values. Known values: gate, scan, send, unknown."`
	Code       string   `json:"code" doc:"Stable machine-readable hold code. Open set; tolerate unknown values."`
	Summary    string   `json:"summary" doc:"Plain-language explanation suitable for showing directly to a reviewer."`
	Category   string   `json:"category,omitempty" doc:"Top screening category when a scan hold has detail enrichment."`
	Detail     string   `json:"detail,omitempty" doc:"Validated plain-language detector rationale when available."`
	Confidence *float64 `` /* 150-byte string literal not displayed */
}

type IdemStore interface {
	Claim(ctx context.Context, userID, key, path, bodyHash string) (idempotency.ClaimResult, error)
	Complete(ctx context.Context, userID, key string, resp idempotency.CachedResponse) error
	// CompleteTx records the completion inside the caller's transaction — used by
	// the async accept path to commit the idempotency key atomically with the
	// message insert + send-job enqueue. See idempotency.Store.CompleteTx.
	CompleteTx(ctx context.Context, tx pgx.Tx, userID, key string, resp idempotency.CachedResponse) error
	Release(ctx context.Context, userID, key string) error
}

type LimitExceededDetails struct {
	// Resource is an OPEN set (evolving response-side vocabulary): a new
	// capped resource means a new value here, and that must not break
	// spec-generated clients.
	Resource   string `` /* 297-byte string literal not displayed */
	Limit      int64  `json:"limit" doc:"The cap that was hit (matches limits.max_<resource>)."`
	Current    int64  `json:"current" doc:"The account's usage at the time the cap was hit (matches usage.<resource>)."`
	PlanCode   string `json:"plan_code,omitempty" doc:"The account's plan label."`
	UpgradeURL string `json:"upgrade_url,omitempty" doc:"An upgrade affordance URL, when the operator has configured one."`
}

type LimitExceededEnvelope struct {
	Err LimitExceededErrorBody `json:"error"`
}

type LimitExceededErrorBody struct {
	Code      string               `json:"code" enum:"limit_exceeded" doc:"Always limit_exceeded for this response."`
	Message   string               `json:"message"`
	Details   LimitExceededDetails `json:"details"`
	RequestID string               `json:"request_id"`
}

type LimitsCapsView struct {
	MaxAgents        int   `json:"max_agents"`
	MaxDomains       int   `json:"max_domains"`
	MaxMessagesMonth int   `json:"max_messages_month"`
	MaxStorageBytes  int64 `` /* 129-byte string literal not displayed */
}

type LimitsUsageView struct {
	Agents        int   `json:"agents"`
	Domains       int   `json:"domains"`
	MessagesMonth int   `json:"messages_month"`
	StorageBytes  int64 `` /* 228-byte string literal not displayed */
}

type ListConversationsInput struct {
	Address string `path:"email"`
	Since   string `query:"since" doc:"RFC3339."`
	Until   string `query:"until" doc:"RFC3339."`
	Cursor  string `` /* 136-byte string literal not displayed */
	Limit   int    `query:"limit" minimum:"1" maximum:"100" default:"100"`
}

type ListDeliveriesInput struct {
	ID     string `path:"id"`
	Status string `query:"status" enum:"pending,delivered,failed"`
	Cursor string `` /* 142-byte string literal not displayed */
	Limit  int    `query:"limit" minimum:"1" maximum:"100" default:"100"`
}

type ListEventsInput struct {
	Type           string `query:"type"`
	AgentID        string `query:"agent_email"`
	ConversationID string `query:"conversation_id"`
	MessageID      string `query:"message_id"`
	Since          string `query:"since" doc:"RFC3339."`
	Until          string `query:"until" doc:"RFC3339."`
	Cursor         string `query:"cursor"`
	Limit          int    `query:"limit" minimum:"1" maximum:"100" default:"100"`
}

type ListMessagesInput struct {
	Address         string   `path:"email"`
	Direction       string   `query:"direction" enum:"inbound,outbound,all" doc:"Defaults to inbound."`
	Status          string   `` /* 146-byte string literal not displayed */
	Sort            string   `query:"sort" enum:"asc,desc" doc:"Defaults to desc (newest first)."`
	From            string   `query:"from" doc:"Case-insensitive substring match on sender."`
	SubjectContains string   `query:"subject_contains" doc:"Case-insensitive substring match on subject."`
	ConversationID  string   `query:"conversation_id"`
	Labels          []string `query:"labels" doc:"Repeatable; AND-matched."`
	Since           string   `query:"since" doc:"RFC3339; created_at >= since."`
	Until           string   `query:"until" doc:"RFC3339; created_at < until."`
	Cursor          string   `query:"cursor"`
	Limit           int      `query:"limit" minimum:"1" maximum:"100" default:"100"`
	Deleted         bool     `` /* 211-byte string literal not displayed */
}

type MXResolver func(ctx context.Context, name string) ([]string, error)

type MessageBodyView struct {
	Text string `json:"text,omitempty"`
	HTML string `json:"html,omitempty"`
}

type MessageGetter func(ctx context.Context, messageID, agentID string) (*identity.Message, error)

type MessageIDParam struct {
	Address   string `path:"email" doc:"The agent's full email address."`
	MessageID string `path:"id" doc:"The message id, e.g. msg_abc123."`
}

type MessageLister func(ctx context.Context, filter identity.MessageListFilter) ([]identity.Message, error)

type MessageParsedView struct {
	// Text is the injection-reduced plain body: text/plain preferred (else
	// HTML→text), quoted reply/forward chains stripped, length-capped. This is
	// what an agent feeds a model by default.
	Text string `json:"text"`
	// Truncated is true when the length cap cut `text`.
	Truncated bool `json:"truncated"`
	// HTML is the decoded text/html part for display, present only when the
	// message carries an HTML part. Full fidelity (NOT quote-stripped, unlike
	// `text`) — render it sanitized/sandboxed; it is untrusted sender content.
	// Omitted for text-only messages; `raw_message` stays the canonical copy.
	HTML string `json:"html,omitempty"`
}

type MessageSummaryView struct {
	ID string `json:"id"`
	// Deliberately a CLOSED enum despite being response-side: direction is a
	// binary invariant of the model, not an evolving vocabulary.
	Direction      string   `json:"direction" enum:"inbound,outbound"`
	HeaderFrom     *string  `` /* 182-byte string literal not displayed */
	EnvelopeFrom   *string  `` /* 167-byte string literal not displayed */
	VerifiedDomain *string  `` /* 483-byte string literal not displayed */
	To             []string `json:"to" nullable:"false"`
	CC             []string `json:"cc,omitempty" nullable:"false"`
	ReplyTo        []string `` /* 236-byte string literal not displayed */
	Recipient      string   `` /* 187-byte string literal not displayed */
	Subject        string   `json:"subject"`
	ConversationID string   `json:"conversation_id,omitempty"`
	// Status is the inbox read-state, exposed as `read_status` (MSG-1).
	Status        string `json:"read_status"`
	HITLStatus    string `` /* 541-byte string literal not displayed */
	WebhookStatus string `json:"webhook_status,omitempty"`
	WebhookError  string `json:"webhook_error,omitempty"`
	// DeliveryStatus / DeliveryDetail / SentAs are the outbound delivery
	// rollup (migration 031). Outbound-only; omitted on inbound rows.
	DeliveryStatus string `` /* 388-byte string literal not displayed */
	DeliveryDetail string `json:"delivery_detail,omitempty"`
	SentAs         string `` /* 156-byte string literal not displayed */
	// Flagged + FlagReason are the beta inbound ingestion verdict. They remain in
	// list projections so polling agents can identify delivered flag outcomes
	// without a per-message drill-down.
	Flagged    bool   `json:"flagged,omitempty"`
	FlagReason string `json:"flag_reason,omitempty"`
	// SizeBytes is the RAW MIME byte length of the whole stored message —
	// same semantics as MessageView.SizeBytes (see there for the full note,
	// including its role as the dominant term of storage-quota accounting).
	SizeBytes int      `` /* 313-byte string literal not displayed */
	Labels    []string `json:"labels" nullable:"false"`
	// CreatedAt is the keyset pagination ordering key, emitted at full RFC3339Nano
	// precision (time.Time) so sub-second ordering is visible on the wire.
	CreatedAt time.Time `json:"created_at" format:"date-time"`
	// DeletedAt marks a message in the trash — set on rows of the deleted=true
	// list view, omitted on live messages. See MessageView.DeletedAt.
	DeletedAt *time.Time `` /* 284-byte string literal not displayed */
}

type MessageTrashOp func(ctx context.Context, messageID, agentID string) error

type MessageView struct {
	ID             string                    `json:"id"`
	HeaderFrom     *string                   `` /* 182-byte string literal not displayed */
	EnvelopeFrom   *string                   `` /* 167-byte string literal not displayed */
	VerifiedDomain *string                   `` /* 554-byte string literal not displayed */
	Authentication *emailauth.Authentication `` /* 326-byte string literal not displayed */
	To             []string                  `json:"to" nullable:"false"`
	CC             []string                  `json:"cc" nullable:"false"`
	ReplyTo        []string                  `` /* 257-byte string literal not displayed */
	Recipient      string                    `` /* 187-byte string literal not displayed */
	Subject        string                    `json:"subject"`
	ConversationID string                    `json:"conversation_id"`
	// Direction (inbound|outbound) — mirrors MessageSummaryView so a client
	// fetching a single message keeps the full trust-axis context (review F1).
	// Deliberately a CLOSED enum despite being response-side: direction is a
	// binary invariant of the model, not an evolving vocabulary.
	Direction string `json:"direction" enum:"inbound,outbound"`
	// Status is the inbox read-state (unread|read; "" for outbound). Exposed as
	// `read_status` (MSG-1) to disambiguate from hitl_status/delivery_status/
	// webhook_status — the conflation that caused bug B2. Left open (not an enum)
	// because outbound rows carry "".
	Status string `json:"read_status"`
	// HITLStatus is the review-hold lifecycle (e.g. pending_review) — outbound
	// only, mirroring MessageSummaryView. Exposed as `review_status` (the holds
	// vocabulary unified on `review` in migration 044). Distinct from read_status,
	// delivery_status, and webhook_status (each a separate axis).
	HITLStatus string `` /* 541-byte string literal not displayed */
	// WebhookStatus / WebhookError mirror MessageSummaryView so the detail view
	// is a strict superset of the list item (a client fetching one message keeps
	// the webhook delivery context). Apply to both directions; omitempty hides
	// the empty case.
	WebhookStatus string `json:"webhook_status,omitempty"`
	WebhookError  string `json:"webhook_error,omitempty"`
	// SizeBytes is the RAW MIME byte length of the whole stored message
	// (octet length of raw_message) — headers + bodies + encoded attachments as
	// transported. Mirrors MessageSummaryView. Distinct from the per-attachment
	// size_bytes in attachments[], which is the DECODED payload size of one
	// attachment. This raw length is also the dominant term of storage-quota
	// accounting: usage.storage_bytes sums raw_message plus any retained
	// held-draft body columns per message (see AccountView).
	SizeBytes int `` /* 324-byte string literal not displayed */
	// DeliveryStatus is the outbound delivery rollup (migration 031:
	// 'sent', 'delivered', 'bounced', …) — the worst recipient status by
	// precedence. Outbound-only; omitted on inbound messages.
	DeliveryStatus string `` /* 388-byte string literal not displayed */
	// DeliveryDetail is the human-readable diagnostic for the delivery
	// rollup (e.g. bounce sub-type / SMTP response). Outbound-only.
	DeliveryDetail string `json:"delivery_detail,omitempty"`
	// SentAs is the From identity actually used at relay accept time.
	// Outbound-only; omitted on inbound messages.
	SentAs string `` /* 156-byte string literal not displayed */
	// Flagged + FlagReason carry the beta inbound ingestion verdict: true when
	// the agent's inbound-policy gate flagged this message on arrival while still
	// delivering it. Polling agents need this signal because no review item is
	// created for the flag action.
	Flagged    bool   `json:"flagged,omitempty"`
	FlagReason string `json:"flag_reason,omitempty"`
	// HoldReason is populated only by GET /v1/reviews/{id}. The shared
	// messageViewFromIdentity constructor deliberately leaves it nil so review
	// context never leaks onto agent-facing message APIs.
	HoldReason *HoldReasonView `json:"hold_reason,omitempty"`
	// Protection is the per-producer screening breakdown behind the hold (the
	// detector categories + rationale that explain hold_reason). Review surface
	// only; populated by the review-detail handler, never on the agent /messages
	// path. Beta.
	Protection []ProtectionFindingView `` /* 134-byte string literal not displayed */
	Labels     []string                `json:"labels" nullable:"false"`
	// CreatedAt is emitted as a full-precision RFC3339Nano date-time (time.Time),
	// consistent with every other timestamp in the surface. This is the keyset
	// pagination ORDERING key, so it must NOT be truncated to whole seconds —
	// two messages in the same second would otherwise be indistinguishable on the
	// wire even though the cursor orders them at finer granularity.
	CreatedAt time.Time `json:"created_at" format:"date-time"`
	// DeletedAt marks a message in the trash (soft-deleted): set when it was
	// moved there, omitted on live messages. Trashed messages appear only in
	// the deleted=true list view and this single-message get; they are purged
	// ~30 days after deletion (docs/design/trash-soft-delete.md).
	DeletedAt  *time.Time `` /* 284-byte string literal not displayed */
	RawMessage []byte     `` /* 278-byte string literal not displayed */
	// Parsed is the derived view (decision 9 / Slice 4b-3): the raw message
	// rendered to text (`text`, quoted chains stripped + length-capped, for the
	// agent to feed a model by default) plus the decoded HTML part (`html`, for
	// display). Present on any message carrying raw MIME — inbound and sent
	// outbound. A CONVENIENCE — when raw_message is non-null, it is canonical;
	// the security decision is made on `auth` + provenance, never on this derived
	// body. Held outbound drafts have raw_message=null and use Body below.
	Parsed *MessageParsedView `json:"parsed,omitempty"`
	// Body is the mutable draft body for a held outbound message
	// (status=pending_review), which has no raw_message yet. This is the
	// second representation the unified read exposes (decision 9): held drafts
	// carry body_text/body_html, sent/inbound carry raw_message. Omitted when
	// empty (sent/inbound rows).
	Body *MessageBodyView `json:"body,omitempty"`
	// Attachments is per-attachment METADATA (never bytes) parsed server-side
	// from raw_message — the authoritative, stable attachment index (§6a #5).
	// Fetch the bytes via GET …/messages/{id}/attachments/{index}. Always
	// present (empty when none); held drafts (no raw_message) carry [].
	Attachments []AttachmentMetaView `json:"attachments" nullable:"false"`
}

type Page[T any] struct {
	Items      []T     `json:"items" nullable:"false"`
	NextCursor *string `json:"next_cursor"`
}

type PageParams struct {
	Cursor string `` /* 142-byte string literal not displayed */
	Limit  int    `query:"limit" minimum:"1" maximum:"100" default:"100" doc:"Maximum number of items to return (1-100)."`
}

type PayloadTooLargeDetails struct {
	// Scope is an OPEN set (evolving response-side vocabulary): a new byte
	// budget (e.g. a future batch or template cap) means a new value here,
	// and that must not break spec-generated clients.
	Scope       string `` /* 227-byte string literal not displayed */
	ActualBytes int64  `` /* 195-byte string literal not displayed */
	MaxBytes    int64  `json:"max_bytes" minimum:"1" doc:"Maximum bytes accepted for this scope."`
	Filename    string `json:"filename,omitempty" doc:"Attachment filename when scope is attachment."`
}

type PrincipalAuthenticator func(r *http.Request) (*identity.Principal, error)

type ProtectionConfigRequest struct {
	Inbound  ProtectionDirectionRequest `json:"inbound"`
	Outbound ProtectionDirectionRequest `json:"outbound"`
	Holds    ProtectionHoldsRequest     `json:"holds"`
}

type ProtectionConfigView struct {
	Inbound  ProtectionDirectionView `json:"inbound"`
	Outbound ProtectionDirectionView `json:"outbound"`
	Holds    ProtectionHoldsView     `json:"holds"`
}

type ProtectionDirectionRequest struct {
	Gate ProtectionGateRequest `json:"gate"`
	Scan ProtectionScanRequest `json:"scan"`
}

type ProtectionDirectionView struct {
	Gate ProtectionGateView `json:"gate"`
	Scan ProtectionScanView `json:"scan"`
}

type ProtectionFindingView struct {
	Source     string               `json:"source" doc:"Which producer flagged the message. Open set; tolerate unknown values. Known values: gate, scan."`
	Action     string               `json:"action,omitempty" doc:"Applied action for this finding. Open set. Known values: flag, review, block."`
	Detector   string               `json:"detector,omitempty" doc:"Content-scan detector(s) that contributed (scan findings only), e.g. \"gemini\"."`
	Score      *float64             `json:"score,omitempty" doc:"Aggregate content-scan score 0..1 (scan findings only)."`
	Categories []ThreatCategoryView `json:"categories,omitempty" doc:"Detected threat categories, highest-confidence first (scan findings only)."`
	// Summary is the detector's short natural-language rationale (e.g. "instructs
	// the agent to wire funds"). Curated from the per-detector verdict — the raw
	// provider payload is never exposed.
	Summary string `json:"summary,omitempty" doc:"Short natural-language rationale for a scan finding (curated; never the raw provider payload)."`
}

type ProtectionGateRequest struct {
	Policy    string   `` /* 403-byte string literal not displayed */
	Allowlist []string `` /* 349-byte string literal not displayed */
	Action    string   `` /* 146-byte string literal not displayed */
}

type ProtectionGateView struct {
	// Policy and Action are OPEN sets on this response view (evolving config
	// vocabularies — a new gate posture or disposition must not break
	// spec-generated clients); the mirroring ProtectionGateRequest keeps the
	// closed enums, which is where validation belongs.
	Policy    string   `` /* 513-byte string literal not displayed */
	Allowlist []string `` /* 349-byte string literal not displayed */
	Action    string   `` /* 256-byte string literal not displayed */
}

type ProtectionHoldsRequest struct {
	TTLSeconds            int    `json:"ttl_seconds,omitempty" minimum:"0" default:"604800" doc:"How long a held item waits before its on_expiry action fires."`
	OnExpiry              string `json:"on_expiry,omitempty" enum:"approve,reject" default:"reject" doc:"What happens to a held item when its TTL expires."`
	SuppressNotifications bool   `` /* 135-byte string literal not displayed */
}

type ProtectionHoldsView struct {
	TTLSeconds int `json:"ttl_seconds,omitempty" minimum:"0" default:"604800" doc:"How long a held item waits before its on_expiry action fires."`
	// OnExpiry is an OPEN set on this response view: today's values happen to
	// be two, but expiry disposition is an evolving config vocabulary (e.g. a
	// future extend/escalate), not a binary invariant of the model like
	// message direction. ProtectionHoldsRequest keeps the closed enum.
	OnExpiry              string `` /* 230-byte string literal not displayed */
	SuppressNotifications bool   `` /* 135-byte string literal not displayed */
}

type ProtectionScanRequest struct {
	Sensitivity string `` /* 156-byte string literal not displayed */
}

type ProtectionScanView struct {
	// Sensitivity is an OPEN set on this response view (evolving vocabulary —
	// a new level must not break clients); ProtectionScanRequest keeps the
	// closed enum for validation.
	Sensitivity string `` /* 267-byte string literal not displayed */
}

type RateLimitedDetails struct {
	RetryAfterSeconds int `json:"retry_after_seconds" doc:"Seconds to wait before retrying; mirrors the Retry-After response header. Always ≥ 1."`
}

type RateLimitedEnvelope struct {
	Err RateLimitedErrorBody `json:"error"`
}

type RateLimitedErrorBody struct {
	Code      string             `json:"code" enum:"rate_limited" doc:"Always rate_limited for this response."`
	Message   string             `json:"message"`
	Details   RateLimitedDetails `json:"details"`
	RequestID string             `json:"request_id"`
}

type RateSnapshot func(key string) (ok bool, retryAfter time.Duration, limit, remaining, resetSeconds int)

type RedeliverDelivery struct {
	WebhookID  string `json:"webhook_id"`
	DeliveryID string `json:"delivery_id,omitempty"`
	// Status is "pending" when the replay was scheduled, or "skipped" when this
	// subscriber's delivery could not be enqueued (see Reason).
	Status string `` /* 140-byte string literal not displayed */
	Reason string `json:"reason,omitempty"`
}

type RedeliverEventInput struct {
	ID   string `path:"id"`
	Body RedeliverEventRequest
}

type RedeliverEventRequest struct {
	WebhookID string `json:"webhook_id,omitempty"`
}

type RedeliverView struct {
	DeliveryID string `json:"delivery_id,omitempty"`
	EventID    string `json:"event_id"`
	WebhookID  string `json:"webhook_id,omitempty"`
	// Status is "pending" for a single-webhook replay (one scheduled delivery)
	// or "scheduled" for a bulk fan-out (see Deliveries for per-subscriber state).
	Status     string              `` /* 127-byte string literal not displayed */
	Deliveries []RedeliverDelivery `json:"deliveries,omitempty" nullable:"false"`
}

type RegisterDomainRequest struct {
	Domain string `json:"domain"`
}

type RejectRequest struct {
	Reason string `` /* 197-byte string literal not displayed */
}

type RejectResultView struct {
	Status          string `json:"status"`
	MessageID       string `json:"message_id"`
	RejectionReason string `json:"rejection_reason,omitempty"`
}

type RenderedTemplateView struct {
	Subject  string `json:"subject"`
	Body     string `json:"text"`
	HTMLBody string `json:"html,omitempty"`
}

type ReplyRequest struct {
	Body           string                `json:"text" maxLength:"1048576"` // required (MSG-3); to/subject derived from the original
	HTMLBody       string                `json:"html,omitempty" maxLength:"1048576"`
	ReplyAll       bool                  `json:"reply_all,omitempty"`
	CC             []string              `` /* 249-byte string literal not displayed */
	BCC            []string              `` /* 251-byte string literal not displayed */
	ConversationID string                `` /* 361-byte string literal not displayed */
	ReplyTo        string                `` /* 282-byte string literal not displayed */
	Attachments    []outbound.Attachment `` /* 275-byte string literal not displayed */
	Unsubscribe    UnsubscribeOptions    `` /* 149-byte string literal not displayed */
}

type RetryAfterDetails struct {
	RetryAfterSeconds int `json:"retry_after_seconds" minimum:"1" doc:"Seconds to wait before retrying; mirrors the Retry-After response header."`
}

type ReviewView struct {
	ID    string `` /* 229-byte string literal not displayed */
	Agent string `json:"agent_email" doc:"The inbox (agent address) the held message belongs to."`
	// Direction: outbound = a draft awaiting send approval; inbound = a screened
	// incoming message awaiting release. Deliberately a CLOSED enum despite
	// being response-side: direction is a binary invariant of the model, not
	// an evolving vocabulary.
	Direction      string          `json:"direction" enum:"inbound,outbound"`
	HeaderFrom     *string         `` /* 182-byte string literal not displayed */
	EnvelopeFrom   *string         `` /* 167-byte string literal not displayed */
	VerifiedDomain *string         `` /* 483-byte string literal not displayed */
	To             []string        `json:"to" nullable:"false"`
	Subject        string          `json:"subject"`
	ConversationID string          `json:"conversation_id,omitempty"`
	ReviewStatus   string          `` /* 154-byte string literal not displayed */
	Flagged        bool            `json:"flagged,omitempty"`
	FlagReason     string          `json:"flag_reason,omitempty"`
	HoldReason     *HoldReasonView `` /* 168-byte string literal not displayed */
	CreatedAt      time.Time       `json:"created_at"`
}

type SendEmailRequest struct {
	To             []string              `` /* 227-byte string literal not displayed */
	CC             []string              `` /* 232-byte string literal not displayed */
	BCC            []string              `` /* 234-byte string literal not displayed */
	Subject        string                `` /* 163-byte string literal not displayed */
	Body           string                `` /* 171-byte string literal not displayed */
	HTMLBody       string                `json:"html,omitempty" maxLength:"1048576" doc:"Literal HTML body. Mutually exclusive with template_id/template_alias."`
	TemplateID     string                `` /* 280-byte string literal not displayed */
	TemplateAlias  string                `` /* 264-byte string literal not displayed */
	TemplateData   TemplateData          `` /* 249-byte string literal not displayed */
	ConversationID string                `` /* 352-byte string literal not displayed */
	ReplyTo        string                `` /* 320-byte string literal not displayed */
	Attachments    []outbound.Attachment `` /* 275-byte string literal not displayed */
	Unsubscribe    UnsubscribeOptions    `` /* 149-byte string literal not displayed */
}

type SendResultView struct {
	// review_approved is the inbound-release outcome of POST .../approve (an
	// inbound hold released to the agent's inbox — no send). sent/pending_review
	// are the send/outbound-approve outcomes.
	Status            string     `` /* 391-byte string literal not displayed */
	MessageID         string     `json:"message_id"`
	ProviderMessageID string     `` /* 182-byte string literal not displayed */
	SentAs            string     `json:"sent_as,omitempty" doc:"From identity used. Open set; tolerate unknown values. Known values: own_address, relay."`
	Method            string     `json:"method,omitempty" doc:"Send transport. Open set; tolerate unknown values. Known values: smtp, loopback."`
	ApprovalExpiresAt *time.Time `json:"approval_expires_at,omitempty"`
	// Edited is set only by approve (true/false = did the reviewer edit the
	// draft before sending); omitted on the plain send path.
	Edited *bool `json:"edited,omitempty"`
}

type SendingRampView struct {
	Status                string     `json:"status" doc:"Platform-managed sending-ramp state. Open set; known values: inactive, ramping, complete, exempt."`
	DailyRecipientLimit   int        `json:"daily_recipient_limit" doc:"Current UTC-day recipient allowance. Zero means no ramp cap applies."`
	RecipientsUsedToday   int        `` /* 150-byte string literal not displayed */
	ResetsAt              *time.Time `json:"resets_at,omitempty"`
	ActiveDays            int        `json:"active_days" doc:"UTC days that reached the provider-accepted volume threshold."`
	RampDays              int        `json:"ramp_days"`
	EstimatedCompletionAt *time.Time `` /* 157-byte string literal not displayed */
}

type Server struct {
	Router chi.Router
	API    huma.API
	// contains filtered or unexported fields
}

type StarterTemplateAliasParam struct {
	Alias string `path:"alias" doc:"The starter template's alias, e.g. welcome."`
}

type StarterTemplateDetailView struct {
	StarterTemplateView
	Body     string `json:"text" doc:"The plain-text part's template source."`
	HTMLBody string `json:"html" doc:"The HTML part's template source."`
}

type StarterTemplateVariableView struct {
	Name        string `json:"name"`
	Required    bool   `json:"required" doc:"Required variables should always be supplied; optional ones render as empty strings when absent."`
	Raw         bool   `` /* 141-byte string literal not displayed */
	Description string `json:"description"`
	Example     string `json:"example" doc:"A realistic sample value, usable as template_data for previews."`
}

type StarterTemplateView struct {
	Alias       string                        `json:"alias"`
	Name        string                        `json:"name"`
	Description string                        `json:"description"`
	Version     string                        `json:"version"`
	Subject     string                        `json:"subject" doc:"Subject template source ({{variable}} interpolation)."`
	Variables   []StarterTemplateVariableView `json:"variables" nullable:"false"`
}

type SuppressionView struct {
	Address         string    `json:"address"`
	Reason          string    `json:"reason,omitempty"`
	Source          string    `json:"source"` // bounce | complaint | manual
	SourceMessageID string    `json:"source_message_id,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
}

type TemplateData map[string]any

type TemplateIDParam struct {
	ID string `path:"id"`
}

type TemplatePartError struct {
	Part    string `json:"part" doc:"Which part failed. Known values: subject, text, html."`
	Message string `json:"message"`
}

type TemplateSummaryView struct {
	ID        string    `json:"id"`
	Name      string    `json:"name"`
	Alias     string    `json:"alias,omitempty" doc:"Optional per-user unique handle usable as template_alias on send."`
	Subject   string    `json:"subject"`
	CreatedAt time.Time `json:"created_at" format:"date-time"`
	UpdatedAt time.Time `json:"updated_at" format:"date-time"`
}

type TemplateView struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Alias    string `json:"alias,omitempty" doc:"Optional per-user unique handle usable as template_alias on send."`
	Subject  string `json:"subject"`
	Body     string `json:"text" doc:"The plain-text part's template source."`
	HTMLBody string `json:"html,omitempty" doc:"The optional HTML part's template source."`
	// Read-only starter provenance, set only on from_starter creates.
	FromStarterAlias   string    `` /* 214-byte string literal not displayed */
	FromStarterVersion string    `` /* 215-byte string literal not displayed */
	CreatedAt          time.Time `json:"created_at" format:"date-time"`
	UpdatedAt          time.Time `json:"updated_at" format:"date-time"`
}

type TestWebhookRequest struct {
	Event string         `` /* 304-byte string literal not displayed */
	Data  map[string]any `json:"data,omitempty"`
}

type TestWebhookResponse struct {
	DeliveryID string `json:"delivery_id"`
}

type ThreatCategoryView struct {
	Name  string  `json:"name"`
	Score float64 `json:"score,omitempty"`
}

type TooManyRecipientsDetails struct {
	MaxRecipients int `json:"max_recipients" minimum:"1" doc:"Maximum recipients allowed across to, cc, and bcc."`
	Provided      int `json:"provided" minimum:"1" doc:"Combined recipient count supplied by the caller."`
}

type UnsubscribeOptions struct {
	Mode    string `` /* 141-byte string literal not displayed */
	Present bool   `json:"-"`
}

type UpdateAgentRequest struct {
	Name *string `` /* 201-byte string literal not displayed */
}

type UpdateMessageRequest struct {
	AddLabels    []string `json:"add_labels,omitempty" nullable:"false"`
	RemoveLabels []string `json:"remove_labels,omitempty" nullable:"false"`
}

type UpdateMessageResultView struct {
	MessageID string   `json:"message_id"`
	Labels    []string `json:"labels" nullable:"false"`
}

type UpdateTemplateRequest struct {
	Name     *string `json:"name,omitempty"`
	Alias    *string `json:"alias,omitempty" doc:"Set to \"\" to clear the alias."`
	Subject  *string `json:"subject,omitempty"`
	Body     *string `json:"text,omitempty"`
	HTMLBody *string `json:"html,omitempty" doc:"Set to \"\" to remove the HTML part."`
}

type UpdateWebhookRequest struct {
	URL         *string                `json:"url,omitempty" doc:"When present, must be a non-empty webhook delivery URL; omit to leave the URL unchanged."`
	Events      *[]string              `` /* 485-byte string literal not displayed */
	Filters     *WebhookFiltersRequest `json:"filters,omitempty"`
	Description *string                `json:"description,omitempty"`
	Enabled     *bool                  `json:"enabled,omitempty"`
}

type ValidateTemplateRequest struct {
	Subject  string       `json:"subject,omitempty"`
	Body     string       `json:"text,omitempty"`
	HTMLBody string       `json:"html,omitempty"`
	TestData TemplateData `json:"test_data,omitempty" doc:"Sample template_data to render the preview with. Missing variables render as empty strings."`
}

type ValidateTemplateResponse struct {
	Valid         bool                  `json:"valid"`
	Errors        []TemplatePartError   `json:"errors" nullable:"false"`
	Rendered      *RenderedTemplateView `json:"rendered,omitempty" doc:"Rendered preview against test_data (or empty data). Present only when valid."`
	SuggestedData map[string]any        `` /* 235-byte string literal not displayed */
}

type ValidationErrorDetails struct {
	Fields []FieldError `` /* 145-byte string literal not displayed */
}

type VerifyDomainView struct {
	Domain     string     `json:"domain"`
	Verified   bool       `json:"verified"`
	VerifiedAt *time.Time `json:"verified_at,omitempty"`
	MX         string     `` /* 591-byte string literal not displayed */
	SPF        string     `` /* 719-byte string literal not displayed */
	DKIM       string     `` /* 1071-byte string literal not displayed */
}

type WebhookDeliveryView struct {
	ID             string     `json:"id"`
	EventType      string     `` /* 271-byte string literal not displayed */
	Status         string     `json:"status" doc:"Delivery state. Open set; tolerate unknown values. Known values: pending, delivered, failed."`
	Attempts       int        `json:"attempts"`
	LastError      string     `json:"last_error,omitempty"`
	LastStatusCode *int       `json:"last_status_code,omitempty"`
	LastAttemptAt  *time.Time `json:"last_attempt_at,omitempty" format:"date-time"`
	NextRetryAt    time.Time  `json:"next_retry_at" format:"date-time"`
	CreatedAt      time.Time  `json:"created_at" format:"date-time"`
}

type WebhookFiltersRequest struct {
	AgentIDs        []string `json:"agent_emails,omitempty" nullable:"false"`
	ConversationIDs []string `json:"conversation_ids,omitempty" nullable:"false"`
	Labels          []string `json:"labels,omitempty" nullable:"false"`
}

type WebhookFiltersView struct {
	AgentIDs        []string `json:"agent_emails,omitempty" nullable:"false"`
	ConversationIDs []string `json:"conversation_ids,omitempty" nullable:"false"`
	Labels          []string `json:"labels,omitempty" nullable:"false"`
}

type WebhookIDParam struct {
	ID string `path:"id"`
}

type WebhookView struct {
	ID              string             `json:"id"`
	URL             string             `json:"url"`
	Description     string             `json:"description"`
	Events          []string           `` /* 628-byte string literal not displayed */
	Filters         WebhookFiltersView `json:"filters"`
	Enabled         bool               `json:"enabled"`
	AutoDisabledAt  *time.Time         `json:"auto_disabled_at,omitempty" format:"date-time"`
	CreatedAt       time.Time          `json:"created_at" format:"date-time"`
	LastDeliveredAt *time.Time         `json:"last_delivered_at,omitempty" format:"date-time"`
}