Types

Every shape on this page is exported from the package root:

import type {
  AlterResponse,
  AlterLogger,
  ApprovalResult,
  ConnectSession,
  RateLimitSnapshot,
  IdentityContext,
  IdentityAssertion,
  MemoryScope,
  // …
} from "@alter-ai/alter-sdk";

Wire format from the backend is snake_case. Exported model classes accept their documented wire shape in constructors and expose camelCase properties. Most model classes provide toJSON() in snake_case; exceptions are called out below.

AlterLogger

Pluggable logger hook. Defaults to the global console.

interface AlterLogger {
  warn: (message: string, ...args: unknown[]) => void;
  info?: (message: string, ...args: unknown[]) => void;
  error?: (message: string, ...args: unknown[]) => void;
  debug?: (message: string, ...args: unknown[]) => void;
}

The SDK calls warn for non-fatal diagnostics and debug when optional token-refresh retry metadata is ignored or parsed. info and error are accepted for logger compatibility but are not currently called.

AlterResponse

The return type of request().

interface AlterResponse extends Response {
  readonly retryInfo: RetryInfo | null;
}

Standard Response plus retryInfo — populated when the backend retried a token refresh; null when the token was served from cache or refreshed on the first attempt.

TokenResponse

OAuth token metadata. The plaintext access token is never exposed on this object; the SDK injects it into outgoing requests at call time.

Field	Type	Description
tokenType	string	Usually "Bearer".
expiresIn	number | null	Seconds until expiry.
expiresAt	Date | null	Absolute instant this credential stops working — the binding value: the earlier of the provider token’s own expiry and the grant’s TTL. Caching past it produces an authorization failure, not a refresh.
tokenExpiresAt	Date | null	The provider token’s own expiry, independent of the grant’s TTL. The only clock a refresh can move.
grantExpiresAt	Date | null	The grant’s own TTL instant (the access duration chosen at consent); null when the grant has no TTL.
scopes	string[]	Scopes granted.
grantId	string	Grant the token resolves to.
providerId	string | null	Provider slug.
scopeMismatch	boolean	The grant’s scopes no longer cover the configured required set.
injectionHeader	string	HTTP header name used for credential injection.
injectionFormat	string	Format string with a {token} placeholder.
additionalCredentials	Record<string, string> | null	Non-secret metadata for multi-part authentication. Credential-bearing entries used internally are stripped before this property is exposed; null means no safe entries remain.
additionalInjections	ReadonlyArray<{ target: string; key: string; valueSource: string }> | null	Validated multi-header or query-parameter injection rules. Runtime target values are "header" or "query_param"; the wire value_source field is exposed as valueSource.

Helpers:

• isExpired(bufferSeconds?: number): boolean
• needsRefresh(bufferSeconds?: number): boolean

The two answer different questions and read different fields. isExpired() reads expiresAt — whether the credential still works. needsRefresh() reads tokenExpiresAt — whether refreshing would help.

They diverge whenever the grant’s TTL is the earlier of the two clocks: the credential is about to stop working, but a refresh cannot extend permission and the correct response is re-consent. Compare grantExpiresAt to tell which clock is binding.

RateLimitSnapshot

Frozen model exposed as lastRateLimit on App, Agent, and constrained clients.

Field	Type	Description
limit	number	Binding requests-per-minute ceiling for the response.
remaining	number	Requests remaining against that binding ceiling.
resetAt	Date	Instant when the reported window resets.

toJSON() emits { limit, remaining, reset_at } with an ISO-8601 timestamp. The value is null until a metered response supplies the standard RateLimit-Policy / RateLimit pair or the compatibility X-RateLimit-* triple. A later unmetered response does not erase the last reading. Provider response headers are not captured because they describe the provider’s budget, not Alter’s.

RetryInfo

Metadata about retry attempts during token refresh.

Field	Type
totalAttempts	number
successfulAttempt	number
errors	ReadonlyArray<RetryErrorInfo>

RetryErrorInfo

One failed attempt.

Field	Type
attempt	number
error	string
errorType	string
delayS	number
permanent	boolean

GrantInfo

A single-grant record.

Field	Type
grantId	string
providerId	string
scopes	string[]
accountIdentifier	string | null
accountDisplayName	string | null
status	string
scopeMismatch	boolean
expiresAt	string | null
createdAt	string
lastUsedAt	string | null
principalType	"user" | "group" | "system" | "agent"
label	string | null
credentialId	string | null
grantPolicy	Record<string, unknown> | null

UnifiedGrantListResult

Returned by listGrants().

Field	Type
grants	GrantListItem[]
total	number
limit	number
offset	number
hasMore	boolean

GrantListItem

Discriminated union over grantKind.

type GrantListItem = OAuthGrantItem | ManagedSecretGrantItem;

OAuthGrantItem

Field	Type
grantKind	"oauth"
grantId	string
providerId	string
scopes	string[]
accountIdentifier	string | null
accountDisplayName	string | null
status	string
scopeMismatch	boolean
needsReconnect	boolean
expiresAt	string | null
grantExpiresAt	string | null
createdAt	string
lastUsedAt	string | null
principalType	"user" | "system" | "agent"
accessVia	"ownership" | "oauth_delegation"
delegatedAt	string | null
delegatedAgentIds	string[]
label	string | null
credentialId	string | null
grantPolicy	Record<string, unknown> | null
parentGrantId	string | null
depth	number
delegable	boolean
scopeConstraint	string[] | null

The "agent" value on principalType marks a delegation child surfaced as its own row. parentGrantId names the grant this one was minted under (null = a root), and depth is its hop distance from the root — together they reconstruct the delegation tree from the flat list. delegable is whether the grant may be re-delegated onward; scopeConstraint is the narrowed provider-scope subset (null = inherits the parent/credential scope).

grantExpiresAt and expiresAt are two different axes: grantExpiresAt is the grant’s own TTL-policy expiry (the access duration chosen at consent; null = perpetual), while expiresAt is the underlying provider token’s expiry (auto-refreshed, never a grant terminal). status reads "expired" once grantExpiresAt has passed, even before the record is lazily flipped — so filtering on status never caches access that has actually lapsed.

ManagedSecretGrantItem

Returned for any managed-secret grant the caller can reach — an operator (App) list surfaces every principal kind the app owns; an agent list surfaces its own and delegated grants.

Field	Type
grantKind	"managed_secret"
grantId	string
managedSecretId	string
managedSecretSlug	string
managedSecretName	string
agentId	string | null
label	string | null
status	string
accountIdentifier	string | null
grantPolicy	Record<string, unknown> | null
expiresAt	string | null
grantExpiresAt	string | null
createdAt	string
lastUsedAt	string | null
principalType	"user" | "group" | "system" | "agent"
accessVia	"ownership" | "ms_delegation"
delegatedAt	string | null
parentGrantId	string | null
depth	number
delegable	boolean
scopeConstraint	string[] | null

DelegationResult

Returned by agent.delegate() — the child grant minted onto another agent.

Field	Type	Description
grantId	string	The new child grant.
grantKind	"oauth" | "managed_secret"	Which credential family the child belongs to.
parentGrantId	string	The held grant the child was minted under (always set — a delegation result is always a child).
depth	number	The child’s hop distance from the root (always >= 1).
delegable	boolean	Whether the recipient may re-delegate this child onward.
status	string	Grant status (e.g. "active").
expiresAt	string | null	Child expiry, clamped to the parent’s lifetime.

Principal

Discriminated union passed to createManagedSecretGrant().

type Principal = UserPrincipal | GroupPrincipal | SystemPrincipal | AgentPrincipal;

PrincipalType is "user" | "group" | "system" | "agent". NonGroupPrincipalType is "user" | "system" | "agent" and is used by OAuth grant models, where group principals are not supported.

UserPrincipal

Field	Type
type	"user"
userToken	string
label	string

GroupPrincipal

Field	Type
type	"group"
externalGroupId	string
idpId	string
label	string

SystemPrincipal

Field	Type
type	"system"
label?	string | null

AgentPrincipal

Field	Type
type	"agent"
label?	string | null

CreateGrantResult

Returned by createManagedSecretGrant().

Field	Type
grantId	string
principalType	"user" | "group" | "system" | "agent"
label	string | null
createdAt	string

RevokeGrantResult

Returned by revokeGrant().

Field	Type
success	boolean
message	string
grantId	string
revokedAt	string

GrantPolicy

Per-grant policy.

Field	Type
expiresAt?	string | null
createdBy?	string | null
createdAt?	string | null

GrantPolicyInput

Camel-case policy input accepted by createConnectSession(), createConnectSessionForError(), connect(), and createManagedSecretGrant(). Unknown keys throw AlterValueError; null values are omitted from the snake-case wire body.

Field	Type	Description
expiresAt?	string | null	Non-empty ISO 8601 absolute expiry.
maxTtlSeconds?	number | null	Positive integer maximum TTL in seconds.
defaultTtlSeconds?	number | null	Positive integer pre-selected TTL in seconds. The backend enforces that it does not exceed maxTtlSeconds.

ConnectFailedGrant

One provider connection that was revoked after authorization because the selected usage limits could not be applied.

Field	Type
providerId	string
reason	string
message	string

ConnectSession

Returned by createConnectSession().

Field	Type
sessionToken	string
connectUrl	string
expiresIn	number
expiresAt	string
scopeConstraintWarnings	readonly string[]

scopeConstraintWarnings (default []) carries one diagnostic per provider whose required scopes the requested scopeConstraint admits nothing against — the session still succeeds, but a grant minted from it would deny every call until the constraint is widened.

ManagedSecretConnectSession

Returned by createManagedSecretConnectSession(). Same shape as ConnectSession minus scopeConstraintWarnings.

toString() redacts connectUrl — the URL fragment carries the session token, so logging would be a leak.

ConnectResult

Returned per provider by connect() and pollConnectSession().

Field	Type
grantId	string
providerId	string
accountIdentifier	string | null
scopes	string[]
grantPolicy	GrantPolicy | null
failedGrants	ConnectFailedGrant[]

failedGrants is empty on full success. Each successful result from a partially completed multi-provider session carries the same failure list.

AuthResult

Returned by authenticate() and pollAuthSession().

Field	Type
userToken	string
userInfo	Record<string, unknown>

AuthSession

Returned by createAuthSession(). toString() redacts authUrl (it carries the session token as the OIDC state parameter).

Field	Type	Description
sessionToken	string	Handle to poll with pollAuthSession(). Persistable.
authUrl	string	IDP sign-in URL to hand to the end user. Never log it.
expiresIn	number	Seconds until the session expires.
expiresAt	string	ISO 8601 expiry timestamp.

OAuthProviderCatalog

Returned by oauthProviders.list().

Member	Type	Description
providers	Readonly<Record<string, OAuthProviderCatalogItem>>	Connectable providers, keyed by id ("<providerId>", …).
getDefaultScopes(provider)	readonly string[]	Default scopes for a provider, or [] if unknown.
getRequiredScopes(provider)	readonly string[]	Required scopes for a provider, or [] if unknown.

OAuthProviderCatalogListOptions

Options accepted by oauthProviders.list().

interface OAuthProviderCatalogListOptions {
  readonly forceRefresh?: boolean;
}

forceRefresh defaults to false. When true, the call bypasses the five-minute in-process cache.

OAuthProviderCatalogItem

Field	Type	Description
id	string	Provider id.
name	string	Internal provider name.
displayName	string	Human-readable name.
category	string | null	Provider category.
description	string | null	Short description.
logoUrl	string | null	Logo URL.
supportsRefresh	boolean	Provider issues refresh tokens.
supportsPkce	boolean	Provider supports PKCE.
availableScopes	Readonly<Record<string, OAuthProviderScopeInfo>>	All requestable scopes, keyed by scope string.
defaultScopes	readonly string[]	Scopes pre-selected in a Connect flow.
requiredScopes	readonly string[]	Scopes that are always requested.
status	string	Always "active" (only connectable providers are returned).

OAuthProviderScopeInfo

Field	Type	Description
description	string	What the scope grants.
required	boolean	Scope is always requested.
isDefault	boolean	Scope is pre-selected by default.

ApprovalGate

One approver gate in an N-of-N approval group.

Field	Type
approvalId	string
expiresAt	Date
expiresIn	number
approvalUrl	string

PendingApproval

Returned by proxyRequest() when an HITL grant requires approval.

Field	Type
approvalId	string
approvalGroupId	string
status	"pending"
expiresAt	Date
expiresIn	number
approvalUrl	string
gates	readonly ApprovalGate[]

Discriminate from ApprovalResult with result instanceof PendingApproval or result.status === "pending".

ApprovalGateStatus

Per-gate progress in an approval group.

Field	Type
approvalId	string
status	ApprovalStatusValue
expiresAt	Date
decidedAt	Date | null

ApprovalStatus

Snapshot returned by getApprovalStatus().

Field	Type
approvalId	string
approvalGroupId	string
status	ApprovalStatusValue
gates	readonly ApprovalGateStatus[]
expiresAt	Date
decidedAt	Date | null
decisionReason	string | null
executedAt	Date | null
hasResult	boolean
executionError	string | null

Helpers:

• isTerminal: boolean — true when status is denied, expired, executed, or failed.

ApprovalStatusValue

type ApprovalStatusValue =
  | "pending"
  | "approved"
  | "executing"
  | "denied"
  | "expired"
  | "executed"
  | "failed";

ApprovalResult

Returned by awaitApproval() and the synchronous branch of proxyRequest().

Field	Type
approvalId	string | null
statusCode	number
headers	Record<string, string>
bodyB64	string
bodyTruncated	boolean
durationMs	number | null
credentialHint	string | null

approvalId is null for the synchronous (non-HITL) branch of proxyRequest() — there was no approval row.

durationMs is the provider round-trip duration. It is null for responses produced by workers that predate this observation. ApprovalResult.toJSON() intentionally omits this observational field.

credentialHint addresses a specific dead end. Some providers run several APIs that accept the same credential but expect it in different headers, so a perfectly valid key is rejected with 401 purely because the request went to the other API. The provider’s own error blames the key, and the natural response — rotating it — changes nothing. When the rejection matches that pattern, credentialHint says so.

It is null on success and on any rejection that does not match. It never changes statusCode or the body: the provider’s response is passed through unchanged and the hint accompanies it. Unlike durationMs it is serialized by toJSON() — it is part of the result’s meaning rather than a measurement of one attempt. A blank hint is normalized to null, so if (result.credentialHint) is the correct test for “is there an explanation”. The SDK does not reject a hint that arrives on an unexpected status — the status rule is the backend’s to enforce, and re-checking it client-side would turn a future backend addition into a hard failure in already-installed SDKs.

Helpers:

• bodyBytes(): Uint8Array
• bodyText(encoding?: BufferEncoding | "utf-8"): string
• bodyJson(): unknown

AgentInfo

A managed agent record. Returned by app.agents.get, app.agents.update, agent.me, and others.

Field	Type
id	string
name	string
displayName	string | null
type	AgentType
status	AgentStatus
scopes	Record<string, unknown>
scopesPending	Record<string, unknown> | null
scopesAppliesAt	Date | null
policy	Record<string, unknown>
metadata	Record<string, unknown>
rateLimitPerMinute	number | null
version	number
createdAt	Date
lastUsedAt	Date | null
parentAgentId	string | null

AgentType

type AgentType = "agent" | "service";

AgentStatus

type AgentStatus = "active" | "inactive" | "revoked";

AgentCreateResult

Extends AgentInfo with the freshly-minted plaintext API key.

Field	Type
apiKey	string | null
keyId	string

apiKey is null on an idempotency-replay — the plaintext is not server-side recoverable. Branch on result.apiKey === null rather than treating any returned value as a usable key.

AgentListResult

Field	Type
agents	AgentInfo[]
total	number
limit	number
offset	number
hasMore	boolean

AgentKey

A single API key bound to a managed agent.

Field	Type
keyId	string
keyPrefix	string
name	string
createdAt	Date
deprecatedAt	Date | null
revokedAt	Date | null
lastUsedAt	Date | null

Computed property:

• status: AgentKeyStatus — "revoked" when revokedAt is set, "deprecated" when deprecatedAt is set, "active" otherwise.

AgentKeyStatus

type AgentKeyStatus = "active" | "deprecated" | "revoked";

AgentKeyMintResult

Extends AgentKey with the plaintext apiKey (returned exactly once).

Field	Type
apiKey	string | null

AgentKeyList

class AgentKeyList { readonly items: AgentKey[] }

APIKeyInfo

A scoped API key (not bound to a managed agent).

Field	Type
id	string
name	string
keyPrefix	string
keyType	"rk" | "ak" | "dk" | "pk"
scopes	readonly string[]
scopeVersion	number
cidrAllowlist	readonly string[] | null
rateLimitRpm	number | null
effectiveRateLimitRpm	number | null
rateLimitSource	"key" | "organization" | "platform_default" | null
expiresAt	string | null
deprecatedAt	string | null
revokedAt	string | null
parentKeyId	string | null
createdAt	string
lastUsedAt	string | null
status	"active" | "rotated" | "revoked"

rateLimitRpm is the per-key override chosen at mint time; null means no override, not unlimited. effectiveRateLimitRpm is the requests-per-minute ceiling actually enforced for the key once the organization ceiling and the platform default are applied, and rateLimitSource names which of those produced it. Throttling decisions should read effectiveRateLimitRpm. Both are optional on parse: a backend that does not report them leaves each null, which means not reported — never unlimited. A live backend always sends both.

MintedKey

Extends APIKeyInfo with the plaintext.

Field	Type
apiKey	string

ScopeCatalog

Returned by scopes.list().

Field	Type
scopeVersion	number
resources	Readonly<Record<string, ResourceScopes>>
actionVerbs	readonly string[]
deprecated	readonly string[]

ResourceScopes

interface ResourceScopes {
  readonly verbs: readonly string[];
}

RequestRule

A request rule passed to withConstraints({ rule }) — cryptographically bound to every request the constrained client makes and enforced on credential-using calls.

interface RequestRule {
  ruleType: string;
  ruleBody: Record<string, unknown>;
}

Content-match rule types

Inputs to contentMatchRule(options), which returns a RequestRule.

type ContentParamOp =
  | "equals"
  | "any_in"
  | "not_subset_of"
  | "gt"
  | "gte"
  | "lt"
  | "lte";

type ContentMatchEffect = "deny" | "redact" | "step_up";

type ContentMatchFamily =
  | "send"
  | "read"
  | "write"
  | "delete"
  | "admin"
  | "payment";

interface ContentParamCondition {
  name: string;
  op: ContentParamOp;
  value: string | number | readonly string[];
}

interface ContentMatchRuleOptions {
  operations?: readonly string[];
  families?: readonly ContentMatchFamily[];
  params?: readonly ContentParamCondition[];
  effect?: ContentMatchEffect;
  redactFields?: readonly string[];
  maxSessionAgeSeconds?: number;
}

At least one of operations or families is required. effect defaults to "deny". redactFields is required only for "redact"; maxSessionAgeSeconds is required only for "step_up" and must be an integer in [1, 86400].

UserSpan

Input to client.spans.emit().

Field	Type
traceId	string
name	string
startTime	Date | string
spanId?	string
parentSpanId?	string
endTime?	Date | string
attributes?	Readonly<Record<string, string>>

MAX_SPANS_PER_BATCH is the exported batch cap (50). spans.emit() accepts from 1 through MAX_SPANS_PER_BATCH items.

EmitSpansResult

Returned by client.spans.emit().

Field	Type
accepted	number

APICallAuditLog

Audit payload model used by retrieve-mode provider-call reporting.

Field	Type
grantId	string
providerId	string
method	string
url	string
requestHeaders	Record<string, string> | null
requestBody	unknown
responseStatus	number
responseHeaders	Record<string, string> | null
responseBody	unknown
latencyMs	number
timestamp	Date
reason	string | null
context	Record<string, string> | null

sanitize() returns the snake_case submission shape after filtering sensitive headers. This class exposes sanitize() rather than toJSON().

Identity

IdentityContext

Returned by app.resolveIdentity() and agent.resolveIdentity(). The canonical identity set the platform resolved for the request — key external data (memory partitions, channel sessions, authorization tuples) on these IDs, never on email or a raw IDP sub.

Field	Type	Description
appId	string	The calling application (tenant).
appUserId	string | null	Canonical end-user key. null for headless calls.
externalSubjectId	string | null	Stable external join key — the IDP subject identifier.
idpId	string | null	Identity provider the subject belongs to.
userStatus	string | null	"active" | "suspended". Deprovisioned users are rejected at resolution, never returned.
groupIds	readonly string[]	Stable external group IDs of the user’s unrevoked memberships.
agentId	string | null	Canonical agent key. null for plain app callers.
actorId	string | null	Audit correlation label only — NOT a partition key.
trace	IdentityTrace | null	Echo of the ambient run/thread trace context.
email	string | null	Only with includeProfile: true.
displayName	string | null	Only with includeProfile: true.

Method memoryScope(): MemoryScope derives the deterministic memory partition keys. See Propagate identity into memory layers.

IdentityTrace

Field	Type
runId	string | null
threadId	string | null

MemoryScope

Deterministic, prefixed partition keys derived from an IdentityContext.

Field	Type	Description
userKey	string | null	"alter:user:<app_user_id>"; null for headless contexts.
agentKey	string | null	"alter:agent:<agent_id>"; null for app callers.
appKey	string	"alter:app:<app_id>".
runKey	string | null	"alter:run:<run_id>" from the trace context.
namespace	readonly string[]	["alter", <app_id>, <app_user_id>]; ["alter", <app_id>] headless.

IdentityAssertion

Returned by app.assertIdentity() and agent.assertIdentity().

Field	Type	Description
token	string	Compact ES256 JWS — verify against the published Alter identity JWKS. Redacted from toString() / inspect output.
expiresAt	Date	Absolute expiry (short TTL by design — default 120s, bounds 10–300s).
identity	IdentityContext	The identity the assertion encodes.

The assertion is identity-only: it carries no provider tokens, no credentials, no raw IDP claims, and grants nothing by itself — downstream systems map it to their own authorization.

Provider specification models

ProviderSpecKind

type ProviderSpecKind = "oauth" | "managed";

This union validates and types the kind argument on providerSpecs methods. ProviderSpec.providerKind remains a broader string to match the Python SDK’s wire model, so a newly introduced backend value does not fail in TypeScript while the Python model accepts it.

ProviderSpec

Field	Type
providerKind	string
providerId	string
version	number
provenance	string
sourceUrl	string | null
contentHash	string
operationCount	number
fetchedAt	Date
changedAt	Date
title	string | null
specVersion	string | null

SpecOperationsListOptions

Options accepted by providerSpecs.listOperations().

Field	Type	Default	Description
search?	string	—	Case-insensitive substring filter over operation id, path, and summary. Non-empty and at most 200 characters when supplied.
limit?	number	100	Page size from 1 through 500.
offset?	number	0	Non-negative page offset.

SpecOperation

Field	Type
operationId	string
method	string
pathTemplate	string
summary	string | null

SpecOperationsPage

Field	Type
items	readonly SpecOperation[]
total	number
limit	number
offset	number
hasMore	boolean
spec	ProviderSpec

SpecOperationDetail

Field	Type
operationId	string
method	string
pathTemplate	string
summary	string | null
paramsSchema	Record<string, unknown>[] | null
requestSchema	Record<string, unknown> | null
responseSchema	Record<string, unknown> | null
spec	ProviderSpec

Enums

HttpMethod

enum HttpMethod {
  GET = "GET",
  POST = "POST",
  PUT = "PUT",
  PATCH = "PATCH",
  DELETE = "DELETE",
  HEAD = "HEAD",
  OPTIONS = "OPTIONS",
}

CallerType

enum CallerType {
  SERVICE = "service",
  AGENT = "agent",
}

Distinguishes backend services from AI agents at the audit layer. Set via the callerType constructor option.

Provider

Slug enum for the OAuth provider catalog. Plain provider-ID strings are also accepted by request() and createConnectSession(); the enum provides IDE autocomplete.