@alter-ai/alter-sdk 0.3.1 → 0.4.0

package/dist/index.d.cts

@@ -48,6 +48,8 @@ declare class TokenResponse {
     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;
@@ -58,6 +60,7 @@ declare class TokenResponse {
         provider_id?: string;
         injection_header?: string;
         injection_format?: string;
+        additional_credentials?: Record<string, string> | null;
     });
     /**
      * Parse expires_at from ISO string.
@@ -157,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.
  *
@@ -325,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.
  */
@@ -402,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.
@@ -461,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.
  *
@@ -493,4 +569,4 @@ declare class TimeoutError extends NetworkError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
-export { APICallAuditLog, ActorType, 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

@@ -48,6 +48,8 @@ declare class TokenResponse {
     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;
@@ -58,6 +60,7 @@ declare class TokenResponse {
         provider_id?: string;
         injection_header?: string;
         injection_format?: string;
+        additional_credentials?: Record<string, string> | null;
     });
     /**
      * Parse expires_at from ISO string.
@@ -157,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.
  *
@@ -325,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.
  */
@@ -402,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.
@@ -461,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.
  *
@@ -493,4 +569,4 @@ declare class TimeoutError extends NetworkError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
-export { APICallAuditLog, ActorType, 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 };