@alter-ai/alter-sdk 0.2.2 → 0.4.0

package/dist/index.d.cts

@@ -9,6 +9,14 @@
  * - TokenResponse: Object.freeze(this) prevents mutation after creation
  * - toJSON() and toString() exclude access token from serialization
  */
+/**
+ * Actor types for tracking SDK callers.
+ */
+declare enum ActorType {
+    BACKEND_SERVICE = "backend_service",
+    AI_AGENT = "ai_agent",
+    MCP_SERVER = "mcp_server"
+}
 /**
  * OAuth token response from Alter Vault.
  *
@@ -34,6 +42,14 @@ declare class TokenResponse {
     readonly scopes: string[];
     /** Connection ID that provided this token */
     readonly connectionId: string;
+    /** Provider ID (google, github, etc.) */
+    readonly providerId: string;
+    /** HTTP header name for credential injection (e.g., "Authorization", "X-API-Key") */
+    readonly injectionHeader: string;
+    /** Header value format with {token} placeholder (e.g., "Bearer {token}", "{token}") */
+    readonly injectionFormat: string;
+    /** Extra credentials for multi-part auth (e.g. AWS SigV4 secret_key, region) */
+    readonly additionalCredentials: Record<string, string> | null;
     constructor(data: {
         access_token: string;
         token_type?: string;
@@ -41,6 +57,10 @@ declare class TokenResponse {
         expires_at?: string | null;
         scopes?: string[];
         connection_id: string;
+        provider_id?: string;
+        injection_header?: string;
+        injection_format?: string;
+        additional_credentials?: Record<string, string> | null;
     });
     /**
      * Parse expires_at from ISO string.
@@ -80,7 +100,6 @@ declare class TokenResponse {
 declare class ConnectionInfo {
     readonly id: string;
     readonly providerId: string;
-    readonly attributes: Record<string, unknown>;
     readonly scopes: string[];
     readonly accountIdentifier: string | null;
     readonly accountDisplayName: string | null;
@@ -91,7 +110,6 @@ declare class ConnectionInfo {
     constructor(data: {
         id: string;
         provider_id: string;
-        attributes?: Record<string, unknown>;
         scopes?: string[];
         account_identifier?: string | null;
         account_display_name?: string | null;
@@ -142,6 +160,27 @@ declare class ConnectionListResult {
         has_more: boolean;
     });
 }
+/**
+ * Result of a headless connect() flow.
+ *
+ * Returned by connect() after the user completes OAuth in the browser.
+ * Contains the connection metadata (no tokens — use request() with
+ * the connectionId to make authenticated API calls).
+ */
+declare class ConnectResult {
+    readonly connectionId: string;
+    readonly providerId: string;
+    readonly accountIdentifier: string | null;
+    readonly scopes: string[];
+    constructor(data: {
+        connection_id: string;
+        provider_id: string;
+        account_identifier?: string | null;
+        scopes?: string[];
+    });
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+}
 /**
  * Audit log entry for an API call to a provider.
  *
@@ -231,8 +270,6 @@ declare enum Provider {
     GOOGLE = "google",
     GITHUB = "github",
     SLACK = "slack",
-    MICROSOFT = "microsoft",
-    SALESFORCE = "salesforce",
     SENTRY = "sentry"
 }
 /**
@@ -265,14 +302,12 @@ declare enum HttpMethod {
 interface AlterVaultOptions {
     /** Alter Vault API key (must start with "alter_key_") */
     apiKey: string;
-    /** Base URL for Alter Vault API */
-    baseUrl?: string;
     /** HTTP request timeout in milliseconds (default: 30000) */
     timeout?: number;
-    /** Actor type ("ai_agent" or "mcp_server") for tracking */
-    actorType?: string;
+    /** Actor type (use ActorType enum: AI_AGENT, MCP_SERVER, BACKEND_SERVICE) */
+    actorType: ActorType | string;
     /** Unique identifier for the actor (e.g., "email-assistant-v2") */
-    actorIdentifier?: string;
+    actorIdentifier: string;
     /** Human-readable name for the actor */
     actorName?: string;
     /** Actor version string (e.g., "1.0.0") */
@@ -286,8 +321,6 @@ interface AlterVaultOptions {
  * Options for the request() method.
  */
 interface RequestOptions {
-    /** User attributes to match connection (e.g., { user_id: "alice" }) */
-    user: Record<string, unknown>;
     /** Optional JSON request body */
     json?: Record<string, unknown>;
     /** Optional additional headers */
@@ -316,6 +349,25 @@ interface ListConnectionsOptions {
     /** Offset for pagination (default 0) */
     offset?: number;
 }
+/**
+ * Options for the connect() method.
+ */
+interface ConnectOptions {
+    /** End user to create session for (requires at least id) */
+    endUser: {
+        id: string;
+        email?: string;
+        name?: string;
+    };
+    /** Restrict to specific providers (e.g., ["google"]) */
+    providers?: string[];
+    /** Max seconds to wait for completion (default 300 = 5 min) */
+    timeout?: number;
+    /** Seconds between poll requests (default 2) */
+    pollInterval?: number;
+    /** If true, opens browser automatically. If false, prints URL. (default true) */
+    openBrowser?: boolean;
+}
 /**
  * Options for the createConnectSession() method.
  */
@@ -326,8 +378,6 @@ interface CreateConnectSessionOptions {
         email?: string;
         name?: string;
     };
-    /** User attributes for connection matching */
-    attributes?: Record<string, unknown>;
     /** Restrict to specific providers (e.g., ["google", "github"]) */
     allowedProviders?: string[];
     /** URL to redirect after OAuth completion */
@@ -358,9 +408,8 @@ interface CreateConnectSessionOptions {
  *
  * // Make API request (token injected automatically)
  * const response = await vault.request(
- *   Provider.GOOGLE, HttpMethod.GET,
+ *   "connection-uuid-here", HttpMethod.GET,
  *   "https://www.googleapis.com/calendar/v3/calendars/primary/events",
- *   { user: { user_id: "alice" } },
  * );
  * const events = await response.json();
  *
@@ -382,7 +431,7 @@ declare class AlterVault {
      * 4. Logs the call for audit (fire-and-forget)
      * 5. Returns the raw response
      */
-    request(provider: Provider | string, method: HttpMethod | string, url: string, options: RequestOptions): Promise<Response>;
+    request(connectionId: string, method: HttpMethod | string, url: string, options?: RequestOptions): Promise<Response>;
     /**
      * List OAuth connections for this app.
      *
@@ -396,6 +445,20 @@ declare class AlterVault {
      * Returns a URL the user can open in their browser to authorize access.
      */
     createConnectSession(options: CreateConnectSessionOptions): Promise<ConnectSession>;
+    /**
+     * Open OAuth in the user's browser and wait for completion.
+     *
+     * This is the headless connect flow for CLI tools, scripts, and
+     * server-side applications. It creates a Connect session, opens the
+     * browser, and polls until the user completes OAuth.
+     *
+     * @param options - Connect options (endUser is required)
+     * @returns Array of ConnectResult objects (one per connected provider)
+     * @throws ConnectTimeoutError if the user doesn't complete within timeout
+     * @throws ConnectFlowError if the user denies or provider returns error
+     * @throws AlterSDKError if SDK is closed or session creation fails
+     */
+    connect(options: ConnectOptions): Promise<ConnectResult[]>;
     /**
      * Close HTTP clients and release resources.
      * Waits for any pending audit tasks before closing.
@@ -440,7 +503,7 @@ declare class PolicyViolationError extends TokenRetrievalError {
 /**
  * Raised when OAuth connection not found.
  *
- * This indicates no connection exists for the given provider and attributes.
+ * This indicates no connection exists for the given connection_id.
  */
 declare class ConnectionNotFoundError extends TokenRetrievalError {
     constructor(message: string, details?: Record<string, unknown>);
@@ -455,6 +518,25 @@ declare class TokenExpiredError extends TokenRetrievalError {
     readonly connectionId: string | undefined;
     constructor(message: string, connectionId?: string, details?: Record<string, unknown>);
 }
+/**
+ * Raised when the headless connect() flow fails.
+ *
+ * This can happen when:
+ * - The user denies authorization
+ * - The provider returns an error
+ * - The session expires before completion
+ */
+declare class ConnectFlowError extends AlterSDKError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when the connect() flow times out.
+ *
+ * The user did not complete OAuth within the specified timeout period.
+ */
+declare class ConnectTimeoutError extends ConnectFlowError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
 /**
  * Raised when provider API call fails.
  *
@@ -487,4 +569,4 @@ declare class TimeoutError extends NetworkError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
-export { APICallAuditLog, AlterSDKError, AlterVault, type AlterVaultOptions, ConnectSession, ConnectionInfo, ConnectionListResult, ConnectionNotFoundError, type CreateConnectSessionOptions, HttpMethod, type ListConnectionsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, type RequestOptions, TimeoutError, TokenExpiredError, TokenResponse, TokenRetrievalError };
+export { APICallAuditLog, ActorType, AlterSDKError, AlterVault, type AlterVaultOptions, ConnectFlowError, type ConnectOptions, ConnectResult, ConnectSession, ConnectTimeoutError, ConnectionInfo, ConnectionListResult, ConnectionNotFoundError, type CreateConnectSessionOptions, HttpMethod, type ListConnectionsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, type RequestOptions, TimeoutError, TokenExpiredError, TokenResponse, TokenRetrievalError };

package/dist/index.d.ts

@@ -9,6 +9,14 @@
  * - TokenResponse: Object.freeze(this) prevents mutation after creation
  * - toJSON() and toString() exclude access token from serialization
  */
+/**
+ * Actor types for tracking SDK callers.
+ */
+declare enum ActorType {
+    BACKEND_SERVICE = "backend_service",
+    AI_AGENT = "ai_agent",
+    MCP_SERVER = "mcp_server"
+}
 /**
  * OAuth token response from Alter Vault.
  *
@@ -34,6 +42,14 @@ declare class TokenResponse {
     readonly scopes: string[];
     /** Connection ID that provided this token */
     readonly connectionId: string;
+    /** Provider ID (google, github, etc.) */
+    readonly providerId: string;
+    /** HTTP header name for credential injection (e.g., "Authorization", "X-API-Key") */
+    readonly injectionHeader: string;
+    /** Header value format with {token} placeholder (e.g., "Bearer {token}", "{token}") */
+    readonly injectionFormat: string;
+    /** Extra credentials for multi-part auth (e.g. AWS SigV4 secret_key, region) */
+    readonly additionalCredentials: Record<string, string> | null;
     constructor(data: {
         access_token: string;
         token_type?: string;
@@ -41,6 +57,10 @@ declare class TokenResponse {
         expires_at?: string | null;
         scopes?: string[];
         connection_id: string;
+        provider_id?: string;
+        injection_header?: string;
+        injection_format?: string;
+        additional_credentials?: Record<string, string> | null;
     });
     /**
      * Parse expires_at from ISO string.
@@ -80,7 +100,6 @@ declare class TokenResponse {
 declare class ConnectionInfo {
     readonly id: string;
     readonly providerId: string;
-    readonly attributes: Record<string, unknown>;
     readonly scopes: string[];
     readonly accountIdentifier: string | null;
     readonly accountDisplayName: string | null;
@@ -91,7 +110,6 @@ declare class ConnectionInfo {
     constructor(data: {
         id: string;
         provider_id: string;
-        attributes?: Record<string, unknown>;
         scopes?: string[];
         account_identifier?: string | null;
         account_display_name?: string | null;
@@ -142,6 +160,27 @@ declare class ConnectionListResult {
         has_more: boolean;
     });
 }
+/**
+ * Result of a headless connect() flow.
+ *
+ * Returned by connect() after the user completes OAuth in the browser.
+ * Contains the connection metadata (no tokens — use request() with
+ * the connectionId to make authenticated API calls).
+ */
+declare class ConnectResult {
+    readonly connectionId: string;
+    readonly providerId: string;
+    readonly accountIdentifier: string | null;
+    readonly scopes: string[];
+    constructor(data: {
+        connection_id: string;
+        provider_id: string;
+        account_identifier?: string | null;
+        scopes?: string[];
+    });
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+}
 /**
  * Audit log entry for an API call to a provider.
  *
@@ -231,8 +270,6 @@ declare enum Provider {
     GOOGLE = "google",
     GITHUB = "github",
     SLACK = "slack",
-    MICROSOFT = "microsoft",
-    SALESFORCE = "salesforce",
     SENTRY = "sentry"
 }
 /**
@@ -265,14 +302,12 @@ declare enum HttpMethod {
 interface AlterVaultOptions {
     /** Alter Vault API key (must start with "alter_key_") */
     apiKey: string;
-    /** Base URL for Alter Vault API */
-    baseUrl?: string;
     /** HTTP request timeout in milliseconds (default: 30000) */
     timeout?: number;
-    /** Actor type ("ai_agent" or "mcp_server") for tracking */
-    actorType?: string;
+    /** Actor type (use ActorType enum: AI_AGENT, MCP_SERVER, BACKEND_SERVICE) */
+    actorType: ActorType | string;
     /** Unique identifier for the actor (e.g., "email-assistant-v2") */
-    actorIdentifier?: string;
+    actorIdentifier: string;
     /** Human-readable name for the actor */
     actorName?: string;
     /** Actor version string (e.g., "1.0.0") */
@@ -286,8 +321,6 @@ interface AlterVaultOptions {
  * Options for the request() method.
  */
 interface RequestOptions {
-    /** User attributes to match connection (e.g., { user_id: "alice" }) */
-    user: Record<string, unknown>;
     /** Optional JSON request body */
     json?: Record<string, unknown>;
     /** Optional additional headers */
@@ -316,6 +349,25 @@ interface ListConnectionsOptions {
     /** Offset for pagination (default 0) */
     offset?: number;
 }
+/**
+ * Options for the connect() method.
+ */
+interface ConnectOptions {
+    /** End user to create session for (requires at least id) */
+    endUser: {
+        id: string;
+        email?: string;
+        name?: string;
+    };
+    /** Restrict to specific providers (e.g., ["google"]) */
+    providers?: string[];
+    /** Max seconds to wait for completion (default 300 = 5 min) */
+    timeout?: number;
+    /** Seconds between poll requests (default 2) */
+    pollInterval?: number;
+    /** If true, opens browser automatically. If false, prints URL. (default true) */
+    openBrowser?: boolean;
+}
 /**
  * Options for the createConnectSession() method.
  */
@@ -326,8 +378,6 @@ interface CreateConnectSessionOptions {
         email?: string;
         name?: string;
     };
-    /** User attributes for connection matching */
-    attributes?: Record<string, unknown>;
     /** Restrict to specific providers (e.g., ["google", "github"]) */
     allowedProviders?: string[];
     /** URL to redirect after OAuth completion */
@@ -358,9 +408,8 @@ interface CreateConnectSessionOptions {
  *
  * // Make API request (token injected automatically)
  * const response = await vault.request(
- *   Provider.GOOGLE, HttpMethod.GET,
+ *   "connection-uuid-here", HttpMethod.GET,
  *   "https://www.googleapis.com/calendar/v3/calendars/primary/events",
- *   { user: { user_id: "alice" } },
  * );
  * const events = await response.json();
  *
@@ -382,7 +431,7 @@ declare class AlterVault {
      * 4. Logs the call for audit (fire-and-forget)
      * 5. Returns the raw response
      */
-    request(provider: Provider | string, method: HttpMethod | string, url: string, options: RequestOptions): Promise<Response>;
+    request(connectionId: string, method: HttpMethod | string, url: string, options?: RequestOptions): Promise<Response>;
     /**
      * List OAuth connections for this app.
      *
@@ -396,6 +445,20 @@ declare class AlterVault {
      * Returns a URL the user can open in their browser to authorize access.
      */
     createConnectSession(options: CreateConnectSessionOptions): Promise<ConnectSession>;
+    /**
+     * Open OAuth in the user's browser and wait for completion.
+     *
+     * This is the headless connect flow for CLI tools, scripts, and
+     * server-side applications. It creates a Connect session, opens the
+     * browser, and polls until the user completes OAuth.
+     *
+     * @param options - Connect options (endUser is required)
+     * @returns Array of ConnectResult objects (one per connected provider)
+     * @throws ConnectTimeoutError if the user doesn't complete within timeout
+     * @throws ConnectFlowError if the user denies or provider returns error
+     * @throws AlterSDKError if SDK is closed or session creation fails
+     */
+    connect(options: ConnectOptions): Promise<ConnectResult[]>;
     /**
      * Close HTTP clients and release resources.
      * Waits for any pending audit tasks before closing.
@@ -440,7 +503,7 @@ declare class PolicyViolationError extends TokenRetrievalError {
 /**
  * Raised when OAuth connection not found.
  *
- * This indicates no connection exists for the given provider and attributes.
+ * This indicates no connection exists for the given connection_id.
  */
 declare class ConnectionNotFoundError extends TokenRetrievalError {
     constructor(message: string, details?: Record<string, unknown>);
@@ -455,6 +518,25 @@ declare class TokenExpiredError extends TokenRetrievalError {
     readonly connectionId: string | undefined;
     constructor(message: string, connectionId?: string, details?: Record<string, unknown>);
 }
+/**
+ * Raised when the headless connect() flow fails.
+ *
+ * This can happen when:
+ * - The user denies authorization
+ * - The provider returns an error
+ * - The session expires before completion
+ */
+declare class ConnectFlowError extends AlterSDKError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when the connect() flow times out.
+ *
+ * The user did not complete OAuth within the specified timeout period.
+ */
+declare class ConnectTimeoutError extends ConnectFlowError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
 /**
  * Raised when provider API call fails.
  *
@@ -487,4 +569,4 @@ declare class TimeoutError extends NetworkError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
-export { APICallAuditLog, AlterSDKError, AlterVault, type AlterVaultOptions, ConnectSession, ConnectionInfo, ConnectionListResult, ConnectionNotFoundError, type CreateConnectSessionOptions, HttpMethod, type ListConnectionsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, type RequestOptions, TimeoutError, TokenExpiredError, TokenResponse, TokenRetrievalError };
+export { APICallAuditLog, ActorType, AlterSDKError, AlterVault, type AlterVaultOptions, ConnectFlowError, type ConnectOptions, ConnectResult, ConnectSession, ConnectTimeoutError, ConnectionInfo, ConnectionListResult, ConnectionNotFoundError, type CreateConnectSessionOptions, HttpMethod, type ListConnectionsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, type RequestOptions, TimeoutError, TokenExpiredError, TokenResponse, TokenRetrievalError };