types

type AIClient ¶

type AIClient interface {
	ChatCompletion(ctx context.Context, req *ChatRequest) (*ChatResponse, error)
	// Embed returns one vector per input text, aligned by index, from the SAME
	// gateway + credential as ChatCompletion. Embeddings therefore authenticate,
	// meter, and observe through the ONE org/project-aligned path — never a static
	// side-channel key. The EmbedRequest carries the billing scope (Org/Project)
	// exactly like ChatRequest; an empty Inputs slice returns (nil, nil).
	Embed(ctx context.Context, req *EmbedRequest) ([][]float32, error)
}

AIClient is the inter-subsystem interface to AI.

type BaseClient ¶

type BaseClient interface {
	Open(ctx context.Context, orgID, serviceName string) (DBHandle, error)
}

BaseClient is the inter-subsystem interface to Base.

type ChatRequest ¶

type ChatRequest struct {
	Model  string
	Prompt string
	// Org is the EFFECTIVE org — the DATA scope the inner AI client reads (BYO
	// provider keys, RAG/knowledge). BillingOrg is the HOME org that PAYS (the caller's
	// X-User-Owner): for a normal caller they are equal, but a platform SuperAdmin
	// acting in another org has BillingOrg=="admin" while Org is the acted-on org, so
	// the debit lands on the admin ledger, never the org whose data is used. Empty
	// BillingOrg falls back to Org (a caller that has not split them).
	Org        string
	BillingOrg string
	Project    string
}

ChatRequest mirrors the AI subsystem's chat-completion request. Org and Project are the billing SCOPE — who this inference is metered against. The metering decorator wrapping deps.AI reads them to authorize the org's balance/budget before the call and debit its billing account after, so no inference runs unattributed. Empty Org denotes an internal/system call with no customer to bill (executed, recorded unattributed) — a customer path always sets it.

type ChatResponse ¶

type ChatResponse struct {
	Content          string
	PromptTokens     int
	CompletionTokens int
	TotalTokens      int
}

ChatResponse mirrors the AI subsystem's chat-completion response. The token counts are surfaced so the metering decorator debits the EXACT inference cost rather than an estimate; they are zero when the gateway omits usage.

type Claims ¶

type Claims struct {
	Sub            string
	Org            string
	Email          string
	IsAdmin        bool
	Project        string
	BillingAccount string
}

Claims is the JWT-validated identity surface gateway hands to downstream subsystems per HIP-0026. Sub = JWT `sub`, Org = JWT `owner`, Email = JWT `email`, IsAdmin = JWT `isAdmin`, Project = JWT `project` (the active org sub-scope), BillingAccount = JWT `billing_account` (the funding account for that scope — an ATTRIBUTION hint; the debit account is always resolved server-side by commerce from the org's ProjectBinding, never trusted from a claim/header).

type CommerceClient ¶

type CommerceClient interface {
	GetOrgConfig(ctx context.Context, orgID string) (*OrgConfig, error)
	// CheckEntitlement reports whether org `orgID` holds an active
	// entitlement for licensed product `productID`, and returns the plan's
	// flat license-features per the toLicenseFeatures vocab contract. Used
	// by the licensing subsystem to gate + scope token issuance. orgID is
	// the org the buyer acts as (X-Org-Id); when callers only have a
	// user subject they pass it through here and commerce resolves the
	// owning org.
	CheckEntitlement(ctx context.Context, orgID, productID string) (*LicenseEntitlement, error)
}

CommerceClient is the inter-subsystem interface to Commerce (entitlements + org config). Money is NOT here — a subject's prepaid balance/deposit/usage is the orthogonal BillingClient, so commerce (catalog/subscriptions/licensing) and billing (the money ledger) never braid. Every method is a DIRECT in-process call to the embedded commerce datastore (co-resident) or a ZAP RPC (split-deploy).

type Counter ¶

type Counter interface{ Inc(n int64) }

Counter / Timing / Span are the canonical o11y handles.

type DBHandle ¶

type DBHandle interface{ Close() error }

DBHandle is the per-org database handle Base hands out.

type DepositInput ¶ added in v1.799.2

type DepositInput struct {
	Org      string       // X-Org-Id namespace, resolved to the commerce Organization
	Subject  string       // billing subject / DestinationId (org slug or "owner/name")
	Amount   money.Amount // amount to credit, exact 18-decimal USD (> 0)
	Currency string       // default "usd"
	Notes    string
	Tags     string
	// Ref, when non-empty, is the deposit's idempotency key: two deposits carrying the SAME
	// Ref credit the wallet AT MOST ONCE (the replay is a no-op returning the first entry's
	// id), so a fixed Ref makes a backfill/settlement exactly-once. Empty keeps the additive
	// default — each grant takes a fresh ref and stacks. Mirrors UsageInput.RequestID.
	Ref  string
	Test bool // write to the sandbox (test-mode) ledger
}

DepositInput is a native credit write (grant / prefund / settlement) to a subject's prepaid ledger in an org's namespace — the typed twin of the /v1/billing/deposit body, no HTTP. Authorization is the CALLER's: only already-gated paths (the global-admin grant, the platform service float) invoke it; the native write marks the ledger sink authorized because the HTTP mint gate it bypasses is replaced by that caller gate.

type EmbedRequest ¶ added in v1.786.216

type EmbedRequest struct {
	Model  string
	Inputs []string
	// Org is the EFFECTIVE (data-scope) org; BillingOrg is the HOME org that PAYS —
	// see ChatRequest. Empty BillingOrg falls back to Org.
	Org        string
	BillingOrg string
	Project    string
}

EmbedRequest is the embeddings call. Inputs are embedded in order; the result is one vector per input, aligned by index. Org and Project are the billing SCOPE, identical in meaning to ChatRequest's, so embeddings meter and observe through the same org/project-aligned path.

type FinanceClient ¶ added in v1.799.2

type FinanceClient interface {
	// Balance returns subject's AVAILABLE prepaid balance as an exact 18-decimal USD money
	// value (settled ledger balance; transient holds are the caller's in-pod
	// reservation) within org's namespace. The ONE balance read the ai gate + the edge
	// meter share.
	Balance(ctx context.Context, org, subject, currency string, test bool) (money.Amount, error)
	// Deposit posts a credit (funding→wallet) to subject's ledger wallet and returns
	// the ledger entry id. Idempotent on in.RequestID when set.
	Deposit(ctx context.Context, in DepositInput) (entryID string, err error)
	// RecordUsage posts a usage debit (wallet→revenue) from subject's ledger wallet.
	// Idempotent on in.RequestID.
	RecordUsage(ctx context.Context, in UsageInput) error
	// SumUsageSince returns org's total metered usage in CENTS at/after the unix
	// cutoff `since` (deposits excluded; test selects the sandbox books). The rolling
	// AI-spend cap's trailing-window source — usage older than the cutoff drops out of
	// the sum, so a moving window needs no reset job.
	SumUsageSince(ctx context.Context, org string, test bool, since int64) (int64, error)
}

FinanceClient is the ONE money interface (package alias: finance.Client, mirroring commerce.Client): a subject's prepaid wallet on the double-entry finance ledger (hanzoai/ledger). Balance is a ledger account balance; a deposit and a usage debit are balanced ledger postings (funding→wallet, wallet→revenue) — so every customer debit IS a platform-revenue credit in one entry. IAM multi-tenancy is the account namespace (org/project), scoped by the authenticated caller. Orthogonal to CommerceClient: the ai prepaid gate, the admin grant, and the edge meter all bill through THIS, and it composes the same finance ledger the treasury posts to — one ledger, two account layers.

type IAMClient ¶

type IAMClient interface {
	VerifyJWT(ctx context.Context, bearer string) (Claims, error)
	GetUser(ctx context.Context, userID string) (*User, error)
	GetOrg(ctx context.Context, orgID string) (*Org, error)
}

IAMClient is the inter-subsystem interface to IAM. Co-resident: direct Go call. Split: ZAP-RPC.

type IntentRequest ¶

type IntentRequest struct {
	Token       string
	Currency    string
	AmountCents int64
}

IntentRequest creates a payments intent. Commerce never sees PAN; it only ever passes the vault token + amount + currency.

type IntentResponse ¶

type IntentResponse struct {
	ID     string
	Status string
}

IntentResponse acknowledges intent creation / state.

type IntentStatus ¶

type IntentStatus struct{ Status string }

IntentStatus is the status-poll response.

type KMSClient ¶

type KMSClient interface {
	GetSecret(ctx context.Context, ref string) ([]byte, error)
	PutSecret(ctx context.Context, ref string, value []byte) error
	// DeleteSecret forgets one secret. An app that custodies a credential on a
	// customer's behalf must be able to remove it when that customer disconnects;
	// without this, disconnecting drops the connection row and leaves the material.
	DeleteSecret(ctx context.Context, ref string) error
	Sign(ctx context.Context, keyRef string, payload []byte) ([]byte, error)
}

KMSClient is the inter-subsystem interface to KMS.

type LicenseEntitlement ¶

type LicenseEntitlement struct {
	// ProductID is the licensed product the entitlement was checked for
	// (e.g. "engine", "engine-rocm", a plugin id).
	ProductID string
	// Active reports whether the entitlement is currently valid (paid,
	// not lapsed/cancelled). Licensing refuses to mint when false.
	Active bool
	// Plan is the resolved plan/tier id (e.g. "developer", "pro", "max",
	// "enterprise"). Surfaced for logging/audit; not load-bearing for the
	// release gate.
	Plan string
	// Features is the flat license-feature list per the toLicenseFeatures
	// vocab contract — copied verbatim into License.Features at issue.
	Features []string
	// ExpiresUnix bounds the entitlement (unix seconds, 0 = no bound). The
	// issued token's exp is clamped to it so a token never outlives the
	// entitlement.
	ExpiresUnix int64
}

LicenseEntitlement is commerce's answer to "does this org/user hold an active entitlement for licensed product X, and what does its plan grant?".

It is the inter-subsystem transport for the entitlement-flow that gates licensing token issuance (commerce → licensing → engine). The licensing subsystem copies Features verbatim into the signed token's `features` list so the proprietary engine's offline release gate (hasFeatures) enforces exactly the plan the buyer paid for.

Features is the FLAT capability list produced from the canonical entitlement vocabulary by the data plane's toLicenseFeatures contract (@hanzo/plans entitlements.mjs): licensing.engine_features verbatim, plus derived capability tokens (e.g. "ai.premium", "training", "tools.<name>"), plus scoping tokens ("licensing.app:<id>", "licensing.product:<id>"). Numeric quotas (tokens_per_min, seats, max_vms, …) ride out of band and are NOT encoded here.

type MQClient ¶

type MQClient interface {
	Publish(ctx context.Context, subject string, payload []byte) error
	Subscribe(ctx context.Context, subject string, handler func([]byte) error) error
}

MQClient is the inter-subsystem interface to mq.

type ModelLister ¶ added in v1.786.92

type ModelLister interface {
	Models(ctx context.Context) ([]string, error)
}

ModelLister is an OPTIONAL capability an AIClient may ALSO implement: it enumerates the model ids the gateway currently serves (its standard /v1/models catalog). The agents subsystem uses it to reject a non-catalog model at agent create/update time with a clean 400, instead of letting the run surface a confusing gateway 502 for a model this gateway never served. An AIClient that cannot enumerate models (the disabled stub, the ZAP-RPC client) simply does not implement it, and callers fall back to skipping the check — so model validation is a best-effort UX guard, never a hard dependency.

type O11yClient ¶

type O11yClient interface {
	Counter(name string, tags ...string) Counter
	Timing(name string, tags ...string) Timing
	Span(ctx context.Context, name string) (context.Context, Span)
}

O11yClient is the inter-subsystem interface to o11y.

type Org ¶

type Org struct {
	ID   string
	Slug string
	Name string
}

Org is the IAM-served org object.

type OrgConfig ¶ added in v1.786.216

type OrgConfig struct {
	OrgID string
	Brand string
}

OrgConfig is the commerce-served org settings struct.

type PaymentsClient ¶

type PaymentsClient interface {
	CreateIntent(ctx context.Context, req *IntentRequest) (*IntentResponse, error)
	ConfirmIntent(ctx context.Context, intentID string) (*IntentResponse, error)
	GetIntentStatus(ctx context.Context, intentID string) (*IntentStatus, error)
}

PaymentsClient is the inter-subsystem interface to payments. Always ZAP-RPC; never co-resident (PCI scope isolation).

type Span ¶

type Span interface{ End() }

Counter / Timing / Span are the canonical o11y handles.

type StreamCompleter ¶ added in v1.801.256

type StreamCompleter interface {
	ChatStream(ctx context.Context, req *ChatRequest, emit func(delta string) error) (*ChatResponse, error)
}

StreamCompleter is an OPTIONAL capability an AIClient may ALSO implement, exactly like ModelLister: the SAME chat completion, delivered as the model produces it. emit is called once per content delta, in order; returning an error from emit stops the stream (a disconnected client), which is NOT a failure of the completion. The returned ChatResponse carries the FULL accumulated content plus usage, so a caller that only wants the answer gets the identical value ChatCompletion would have returned — streaming is a delivery property, never a different result.

An AIClient that cannot stream (the disabled stub, the ZAP-RPC client) simply does not implement it, and callers fall back to ChatCompletion — so token streaming is a progressive-delivery upgrade, never a hard dependency.

type Timing ¶

type Timing interface{ Observe(seconds float64) }

Counter / Timing / Span are the canonical o11y handles.

type UsageInput ¶ added in v1.799.2

type UsageInput struct {
	Org       string
	Subject   string       // billing subject / SourceId
	Amount    money.Amount // amount to debit, exact 18-decimal USD (> 0)
	Currency  string
	Model     string
	Provider  string
	Project   string
	Service   string
	RequestID string
	Test      bool
}

UsageInput is a native usage (withdraw/debit) write to a subject's prepaid ledger — the typed twin of the /v1/billing/usage body, no HTTP.

type User ¶

type User struct {
	ID    string
	Email string
	Name  string
}

User is the IAM-served user object.

type VFSClient ¶

type VFSClient interface {
	Put(ctx context.Context, key string, payload []byte) error
	Get(ctx context.Context, key string) ([]byte, error)
	Delete(ctx context.Context, key string) error
}

VFSClient is the inter-subsystem interface to vfs. Delete removes the blob at key (idempotent — a missing key is not an error at the seam; the underlying hanzoai/vfs forwards to backend.Delete(ctx,key)).

type VaultChargeRequest ¶

type VaultChargeRequest struct {
	Token       string
	ProcessorID string
	Currency    string
	AmountCents int64
}

VaultChargeRequest is the payments→vault charge request. Vault is the only system that sees PAN — it dereferences the token and makes the processor call.

type VaultChargeResponse ¶

type VaultChargeResponse struct {
	ProcessorRef string
	Status       string
}

VaultChargeResponse is the vault→payments charge response.

type VaultClient ¶

type VaultClient interface {
	Charge(ctx context.Context, req *VaultChargeRequest) (*VaultChargeResponse, error)
}

VaultClient is the inter-subsystem interface to vault. The ONLY system that touches PAN. Always ZAP-RPC; never co-resident.