Types

All types are available as named exports.

import AlterConnect, {
  type AlterConnectConfig,
  type OpenOptions,
  type Provider,
  type Grant,
  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 seven 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;
  timestamp: string;
  operation: "creation" | "reauth";
  scopes: string[];
  status: "active" | "pending" | "error";
  metadata?: {
    account_display_name?: string;
    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	Identifier for the provider account. Defaults to an empty string if the result omits it.
timestamp	string	ISO 8601 timestamp. The SDK supplies the current time if the result omits it.
operation	"creation" | "reauth"	How the grant was established. "creation" is a brand-new grant; "reauth" is a re-authorization of an existing grant (e.g. after an expired refresh token).
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".
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.

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.
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	Every resulting grant was rejected because the selected usage limits could not be applied. The error carries failedGrants.

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 and are not reliable onError callbacks. Use backend session polling when every terminal state must be recovered.

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 result that was not retained because the selected usage limits could not be applied.

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

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;
  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).
onSuccess	(grants: Grant[], completion: ConnectCompletion) => void	yes	Fires when a popup flow retains at least one grant.
onExit	() => void	no	Fires when the user closes the popup without finishing. 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. Hosted-page-only failures require backend polling.
onEvent	(eventName: string, metadata: Record<string, unknown>) => void	no	Analytics hook. The SDK emits exactly one event today — 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;
}