Types

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

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

Wire format from the backend is snake_case. The SDK accepts the wire shape in constructors and exposes camelCase properties; toJSON() round-trips back to snake_case for serialization.

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;
}

Only warn is currently called by the SDK. The other methods are part of the contract for future use.

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 expiry.
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 extras (region, service).
additionalInjections	ReadonlyArray<{ target, key, valueSource }> | null	Multi-header or query-param injection rules.

Helpers:

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

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"

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
expiresAt	string | null
createdAt	string
lastUsedAt	string | null
principalType	"user" | "system"
accessVia	"ownership" | "oauth_delegation"
delegatedAt	string | null
delegatedAgentIds	string[]

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
createdAt	string
lastUsedAt	string | null
principalType	"user" | "group" | "system" | "agent"
accessVia	"ownership" | "ms_delegation"
delegatedAt	string | null

Principal

Discriminated union passed to createManagedSecretGrant().

type Principal = UserPrincipal | GroupPrincipal | SystemPrincipal | AgentPrincipal;

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

ConnectSession

Returned by createConnectSession().

Field	Type
sessionToken	string
connectUrl	string
expiresIn	number
expiresAt	string

ManagedSecretConnectSession

Returned by createManagedSecretConnectSession(). Same shape as ConnectSession.

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

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.

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.

PendingApproval

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

Field	Type
approvalId	string
status	"pending"
expiresAt	Date
expiresIn	number
approvalUrl	string

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

ApprovalStatus

Snapshot returned by getApprovalStatus().

Field	Type
approvalId	string
status	ApprovalStatusValue
expiresAt	Date
decidedAt	Date | null
decisionReason	string | null
executedAt	Date | null
hasResult	boolean

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

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

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
expiresAt	string | null
deprecatedAt	string | null
revokedAt	string | null
parentKeyId	string | null
createdAt	string
lastUsedAt	string | null
status	"active" | "rotated" | "revoked"

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 one-off deny 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>;
}

APICallAuditLog

Reserved — represents an audit row that the SDK schedules in the background. Application code does not construct or read this directly; the type is exported for callers that want to mock the audit submission pipeline in tests.

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.

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. Use the string slug ("google", "github", etc.) directly in request() and createConnectSession() — the enum is provided for IDE autocomplete.