Types

All types are available as named exports.

import AlterConnect, {
  type AlterConnectConfig,
  type OpenOptions,
  type Provider,
  type Grant,
  type GrantDelegation,
  type AlterError,
  type ConnectCompletion,
  type ConnectFailedGrant,
} from "@alter-ai/connect";

AlterConnect is the default value export. The package does not expose it as a named value export. The eight interfaces above are type-only named exports.

Warning

Every field on Grant is snake_case. Accessing grant.grantId or grant.providerName returns undefined.

Grant

One retained provider grant passed to onSuccess.

interface Grant {
  grant_id: string;
  provider: string;
  provider_name: string;
  account_identifier: string | null;
  timestamp: string;
  operation: "creation" | "reauth";
  scopes: string[];
  status: "active" | "pending" | "error";
  delegation?: GrantDelegation;
  metadata?: {
    account_display_name?: string | null;
    account_email?: string;
    [key: string]: unknown;
  };
}

Field	Type	Description
grant_id	string	The Alter Vault identifier for this grant. Server SDK methods accept it as grantId.
provider	string	Provider technical ID.
provider_name	string	Provider display name. Defaults to provider if the result omits it.
account_identifier	string | null	Verified identifier for the provider account, or null when unavailable. Missing fields normalize to null.
timestamp	string	ISO 8601 timestamp. The SDK supplies the current time if the result omits it.
operation	"creation" | "reauth"	Connect-flow mode. "creation" means a new grant was minted; "reauth" means an existing grant was returned with its grant_id preserved — a credential repair, or reuse of an already-connected grant.
scopes	string[]	OAuth scopes granted by the user. Defaults to an empty array.
status	"active" | "pending" | "error"	Grant status at the moment the flow completed. Defaults to "active".
delegation	GrantDelegation?	Present when the session delegated the grant to an agent (a session created with agent); absent otherwise. See GrantDelegation.
metadata	object?	Optional extras preserved when a success payload supplies them. The current hosted success message omits this field. Treat unknown keys as advisory.

metadata is optional, and the current hosted Connect callback does not supply it. Always null-check before reading nested keys.

GrantDelegation

The delegation a Connect session made of one grant to its agent, on Grant.delegation.

interface GrantDelegation {
  agent_id: string;
  delegable: boolean;
  policy_refused?: boolean;
}

Field	Type	Description
agent_id	string	The agent the grant was delegated to (a UUID).
delegable	boolean	The delegation’s stored onward-sharing setting after the user’s approval: whether the agent may share this access with other agents. It is a stored setting, not a capability: the provider’s agent sharing setting still decides each onward delegation.
policy_refused	boolean?	true when the user chose to let the agent share this access but the provider’s agent sharing setting refused that choice when the connection was confirmed (the setting changed while the consent screen was open); delegable then reports the setting that was kept. The SDK always sets it, false when the page did not say.

The SDK validates the known fields and ignores any other: an agent_id that is not a UUID, or a delegable / policy_refused that is not a boolean, is refused through onError with code: "invalid_response" rather than reported as a setting the server never stored.

AlterError

The object passed to onError (and emitted on the error event).

interface AlterError {
  code: string;
  message: string;
  details?: Record<string, unknown>;
  failedGrants?: ConnectFailedGrant[];
}

Field	Type	Description
code	string	Stable, machine-readable error code. See the table below for the codes emitted by the Connect SDK.
message	string	Human-readable summary. Treat it as display text rather than a control-flow key.
details	Record<string, unknown>?	Additional context when supplied by the failure payload.
failedGrants	ConnectFailedGrant[]?	Present on a total usage-limit application failure.

Browser SDK error codes

Code	Delivery	Cause
invalid_options	Rejected open() promise	token was not a non-empty string or onSuccess was not a function.
invalid_container	Rejected open() promise	container was supplied but is not an element attached to the document.
embed_unsupported_origin	Rejected open() promise	container was supplied on a page with no http(s) origin, or on a page that is itself inside an iframe. Neither can be named as the widget’s single allowed parent.
sdk_destroyed	Rejected open() promise, or thrown by another lifecycle method	open(), close(), on(), off(), or isOpen() was called after destroy().
popup_blocked	onError and error event	The browser blocked the desktop popup.
redirect_error	onError and error event	The mobile branch could not save redirect state to sessionStorage.
redirect_state_missing	error event	A full-page redirect came back carrying Alter Connect callback parameters, but no matching flow state exists on this origin. Almost always a return URL on a different origin than the page that called open() — browsers scope the flow’s session storage to one origin, so the callback cannot be completed where it landed.
invalid_oauth_url	onError and error event	The SDK could not derive a trusted origin from the launch URL. This is a defensive path because supported configuration uses the fixed Alter host.
invalid_response	onError and error event	A success message omitted the grants array, supplied an empty result, or carried malformed grant or failure data.
grant_policy_application_failed	onError and error event	No grant was kept, and at least one was rejected because the selected usage limits could not be applied. The error carries failedGrants.
grant_activation_failed	onError and error event	No grant was kept, and none for a usage-limit reason: every selected connection could not be completed when the user confirmed it (failedGrants reasons activation_failed, alongside any not_selected). Start the connection again. The error carries failedGrants.
connect_denied	onError and error event	The user denied provider authorization and the session had nothing left to try. Backend polling raises ConnectDeniedError for the same terminal result.
embed_load_timeout	onError and error event	The inline frame delivered no message within 15 seconds of mounting: the hosted page was refused by the browser, failed to load, or could not be reached.

The identity-provider sign-in a delegating session asks for before the user approves on an already-connected account never reaches onError: a failed sign-in keeps the session open, the hosted page offers to sign in again or cancel, and the widget reports only the session’s outcome.

An error posted by the hosted callback keeps its server-supplied code; do not assume the list of those codes is closed. Invalid or expired sessions detected while the hosted page binds or loads are rendered in that page; in the popup flow they are not onError callbacks, while the inline widget also posts them to onError with the server’s code (embed_origin_mismatch, embed_not_allowed, session_expired, embed_verify_failed, cookies_required). A provider denial is recoverable instead of terminal when the session can still continue — an allowed provider the user has not yet declined, a grant already authorized during it, or an account the user has already connected and can still approve; declining every offered provider leaves nothing to try, so the last refusal is terminal. Connect then returns to the picker and leaves polling pending; on the popup flow it also reports the refusal through onEvent as a non-terminal provider_declined. A session minted with exactly one provider goes straight to that provider (and confirms automatically only when it was also minted with direct); refusing it is terminal unless the user already has a connection for that provider and can still approve it (the approvable-account route), in which case the picker-less retry screen is shown and the refusal is reported as a non-terminal provider_declined.

The browser package does not export exception classes. Server SDK classes include ReAuthRequiredError, NoDelegatedGrantError, GrantNotFoundError, CredentialRevokedError, and the headless-flow ConnectFlowError family (ConnectDeniedError, ConnectConfigError, ConnectTimeoutError). See the Errors reference.

ConnectFailedGrant

One provider the session connected but did not keep: the user did not select it on the Confirm screen, the connection could not be completed when the user confirmed it, or its selected usage limits could not be applied.

interface ConnectFailedGrant {
  providerId: string;
  reason: string;
  message: string;
}

reason	Meaning
not_selected	The user connected the provider but did not select it on the Confirm screen, so the connection was dropped and never became usable.
activation_failed	The user confirmed the provider, but the connection could not be completed (for example, the same account was connected again in a newer Connect session, or the account connection was removed), so it never became usable. Connect it again.
any other value	The selected usage limits could not be applied (for example invalid_rule, rule_limit, storage_error), so the connection was not kept.

Branch on reason, never on message. Unknown reason strings are preserved.

ConnectCompletion

The second argument passed to onSuccess.

interface ConnectCompletion {
  grants: Grant[];
  failedGrants: ConnectFailedGrant[];
}

grants is the same retained-grants result represented by the first callback argument. failedGrants is empty for a full success and populated for a partial completion. A total failure is delivered to onError instead.

OpenOptions

The argument to alterConnect.open().

interface OpenOptions {
  token: string;
  container?: HTMLElement;
  singleProvider?: boolean;
  onSuccess: (grants: Grant[], completion: ConnectCompletion) => void;
  onExit?: () => void;
  onError?: (error: AlterError) => void;
  onEvent?: (
    eventName: string,
    metadata: Record<string, unknown>,
  ) => void;
}

Field	Type	Required	Description
token	string	yes	Session token minted on the application backend via app.createConnectSession(). Short-lived (10-minute default).
container	HTMLElement	no	Render the Connect UI inline inside this attached element instead of a popup window. The host page’s origin must equal the session’s allowed origin. See the inline flow.
singleProvider	boolean	no	Inline mode only: the session’s single_provider flag. When open() runs inside the user’s click, the provider’s sign-in window opens immediately (no tile) and the container shows a plain status line; a blocked window falls back to the tile. Ignored without container. This is the session’s PICKER decision, not its consent decision — a session that also opted out of the end-user consent screens carries a separate direct flag, which the widget does not consume.
onSuccess	(grants: Grant[], completion: ConnectCompletion) => void	yes	Fires when a popup or inline flow retains at least one grant.
onExit	() => void	no	Fires when the user closes the popup without finishing, or presses Cancel inside the inline widget. Does not fire on the mobile redirect flow or mark the backend session denied.
onError	(error: AlterError) => void	no	Fires for failures delivered to the browser SDK, including a terminal provider denial (connect_denied).
onEvent	(eventName: string, metadata: Record<string, unknown>) => void	no	Analytics hook, and the channel for non-terminal transitions (connect_opened, provider_declined, provider_error, embed_unsupported) — see Events & callbacks.

See the full open() reference for launch-time rejection semantics and the mobile redirect limitation.

AlterConnectConfig

The optional argument to AlterConnect.create().

interface AlterConnectConfig {
  debug?: boolean;
  baseURL?: string;
}

Field	Type	Required	Description
debug	boolean	no	When true, the SDK logs lifecycle events to console.log. Default false.
baseURL	string	no	Reserved and unsupported — passing any value throws at construction. Omit the field.

See the create() reference for the reserved-field error and the instance lifecycle methods (close, destroy, isOpen, getVersion).

Provider

Exported for typing convenience when the application surfaces a provider list obtained separately. The Connect SDK itself does not return Provider objects.

interface Provider {
  id: string;
  name: string;
  description: string;
  category: string;
  logo_url: string;
}