@alter-ai/alter-sdk 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,392 @@
+/**
+ * Provider and HttpMethod enums for type-safe SDK usage.
+ *
+ * Static enum of supported OAuth providers. Strings are also accepted
+ * by the SDK for forward compatibility with new providers.
+ *
+ * When adding a new provider to the backend, add it here too.
+ */
+/**
+ * Supported OAuth provider identifiers.
+ *
+ * Use these for type safety and IDE autocomplete. The SDK also accepts
+ * plain strings for providers not yet in this enum.
+ *
+ * @example
+ * ```typescript
+ * import { AlterVault, Provider, HttpMethod } from "@alter-ai/alter-sdk";
+ *
+ * const vault = new AlterVault({ apiKey: "alter_key_..." });
+ *
+ * // Type-safe (recommended)
+ * const resp = await vault.request(
+ *   Provider.GOOGLE, HttpMethod.GET,
+ *   "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+ *   { user: { user_id: "alice" } },
+ * );
+ *
+ * // String also works (forward compatible with new providers)
+ * const resp2 = await vault.request(
+ *   "new-provider", "GET",
+ *   "https://api.new-provider.com/v1/data",
+ *   { user: { user_id: "alice" } },
+ * );
+ * ```
+ */
+declare enum Provider {
+    GOOGLE = "google",
+    GITHUB = "github",
+    SLACK = "slack",
+    MICROSOFT = "microsoft",
+    SALESFORCE = "salesforce",
+    SENTRY = "sentry"
+}
+/**
+ * HTTP methods for type-safe method selection.
+ *
+ * Use these for IDE autocomplete and type safety. Plain strings
+ * are also accepted for forward compatibility.
+ */
+declare enum HttpMethod {
+    GET = "GET",
+    POST = "POST",
+    PUT = "PUT",
+    PATCH = "PATCH",
+    DELETE = "DELETE",
+    HEAD = "HEAD",
+    OPTIONS = "OPTIONS"
+}
+
+/**
+ * Main Alter Vault SDK client.
+ *
+ * This module provides the primary AlterVault class for interacting with
+ * the Alter Vault OAuth token management system.
+ *
+ * Security Hardening (v0.4.0):
+ * - Layer 1: Prototype frozen to prevent subclass method override attacks
+ * - Layer 1b: HttpClient.prototype also frozen to prevent request interception
+ * - Layer 2: Instance frozen after construction (Object.freeze)
+ * - Layer 3: API key not stored as instance property
+ * - Layer 4: ES2022 private fields (#) for truly private internal state
+ * - Layer 5: (see models.ts) TokenResponse access_token in module-private WeakMap
+ * - Layer 6: Test accessors removed from production builds
+ */
+
+/**
+ * Configuration options for AlterVault constructor.
+ */
+interface AlterVaultOptions {
+    /** Alter Vault API key (must start with "alter_key_") */
+    apiKey: string;
+    /** Base URL for Alter Vault API */
+    baseUrl?: string;
+    /** Whether to send audit logs to backend (default: true) */
+    enableAuditLogging?: boolean;
+    /** HTTP request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Actor type ("ai_agent" or "mcp_server") for tracking */
+    actorType?: string;
+    /** Unique identifier for the actor (e.g., "email-assistant-v2") */
+    actorIdentifier?: string;
+    /** Human-readable name for the actor */
+    actorName?: string;
+    /** Actor version string (e.g., "1.0.0") */
+    actorVersion?: string;
+    /** MCP client type (e.g., "cursor", "claude-desktop") */
+    clientType?: string;
+    /** AI framework (e.g., "langchain", "langgraph", "crewai") */
+    framework?: string;
+}
+/**
+ * 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 */
+    extraHeaders?: Record<string, string>;
+    /** Optional URL query parameters (values are coerced to strings) */
+    queryParams?: Record<string, string | number | boolean>;
+    /** Optional URL path template substitutions */
+    pathParams?: Record<string, string>;
+    /** Optional reason for API call (for audit) */
+    reason?: string;
+    /** Run execution ID (UUID, for actor instance tracking) */
+    runId?: string;
+    /** Conversation thread ID */
+    threadId?: string;
+    /** Tool invocation ID */
+    toolCallId?: string;
+}
+/**
+ * Main SDK class for Alter Vault OAuth token management.
+ *
+ * This class handles:
+ * - Executing API requests to any OAuth provider with automatic token injection
+ * - Audit logging of API calls
+ * - Actor tracking for AI agents and MCP servers
+ *
+ * Zero Token Exposure:
+ * - Tokens are retrieved internally but NEVER exposed to developers
+ * - All API calls inject tokens automatically behind the scenes
+ * - Developers only see API results, never authentication credentials
+ *
+ * Security Hardening:
+ * - Cannot be effectively subclassed (prototype is frozen)
+ * - Instance is frozen after construction (Object.freeze)
+ * - API key is NOT stored as an instance property
+ * - Internal HTTP clients use ES2022 private fields (#)
+ * - Test accessors are removed (no production leak path)
+ *
+ * @example
+ * ```typescript
+ * import { AlterVault, Provider, HttpMethod } from "@alter-ai/alter-sdk";
+ *
+ * const vault = new AlterVault({ apiKey: "alter_key_..." });
+ *
+ * // Make API request (token injected automatically)
+ * const response = await vault.request(
+ *   Provider.GOOGLE, HttpMethod.GET,
+ *   "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+ *   { user: { user_id: "alice" } },
+ * );
+ * const events = await response.json();
+ *
+ * // Clean up
+ * await vault.close();
+ * ```
+ */
+declare class AlterVault {
+    #private;
+    readonly baseUrl: string;
+    readonly enableAuditLogging: boolean;
+    constructor(options: AlterVaultOptions);
+    /**
+     * Execute an HTTP request to a provider API with automatic token injection.
+     *
+     * This is the single entry point for all provider API calls. The SDK:
+     * 1. Fetches an OAuth token from Alter backend (never exposed)
+     * 2. Injects the token as a Bearer header
+     * 3. Calls the provider API
+     * 4. Logs the call for audit (if enabled, fire-and-forget)
+     * 5. Returns the raw response
+     */
+    request(provider: Provider | string, method: HttpMethod | string, url: string, options: RequestOptions): Promise<Response>;
+    /**
+     * Close HTTP clients and release resources.
+     * Waits for any pending audit tasks before closing.
+     */
+    close(): Promise<void>;
+    /**
+     * Async dispose support for `await using vault = new AlterVault(...)`.
+     * Requires TypeScript 5.2+ and Node.js 18+.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * Models for Alter SDK.
+ *
+ * These models provide type-safe data structures for SDK operations.
+ *
+ * Security Hardening (v0.4.0):
+ * - TokenResponse: accessToken stored in module-private WeakMap in client.ts
+ *   (not readable as property, not importable from this module)
+ * - TokenResponse: Object.freeze(this) prevents mutation after creation
+ * - toJSON() and toString() exclude access token from serialization
+ */
+/**
+ * OAuth token response from Alter Vault.
+ *
+ * This represents an access token retrieved from the backend.
+ * The access_token is NOT stored as a readable property — it lives in a
+ * module-private WeakMap in client.ts and is only accessible internally.
+ *
+ * SECURITY:
+ * - No accessToken property (stored in WeakMap inside client.ts)
+ * - Instance is frozen after construction to prevent mutation
+ * - toJSON() and toString() exclude access token
+ * - _extractAccessToken() lives in client.ts, NOT in this file,
+ *   so it cannot be imported by consumers even via deep imports
+ */
+declare class TokenResponse {
+    /** Token type (usually "Bearer") */
+    readonly tokenType: string;
+    /** Seconds until token expires */
+    readonly expiresIn: number | null;
+    /** Absolute expiration time */
+    readonly expiresAt: Date | null;
+    /** OAuth scopes granted */
+    readonly scopes: string[];
+    /** Connection ID that provided this token */
+    readonly connectionId: string;
+    constructor(data: {
+        access_token: string;
+        token_type?: string;
+        expires_in?: number | null;
+        expires_at?: string | null;
+        scopes?: string[];
+        connection_id: string;
+    });
+    /**
+     * Parse expires_at from ISO string.
+     */
+    private static parseExpiresAt;
+    /**
+     * Check if token is expired.
+     *
+     * @param bufferSeconds - Consider token expired N seconds before actual expiry.
+     *                        Useful for preventing race conditions.
+     * @returns True if token is expired or will expire within bufferSeconds.
+     */
+    isExpired(bufferSeconds?: number): boolean;
+    /**
+     * Check if token should be refreshed soon.
+     *
+     * @param bufferSeconds - Consider token needing refresh N seconds before expiry.
+     *                        Default 5 minutes (300 seconds).
+     * @returns True if token will expire within bufferSeconds.
+     */
+    needsRefresh(bufferSeconds?: number): boolean;
+    /**
+     * Custom JSON serialization — EXCLUDES access_token for security.
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Custom string representation — EXCLUDES access_token for security.
+     */
+    toString(): string;
+}
+/**
+ * Audit log entry for an API call to a provider.
+ *
+ * This is sent to the backend audit endpoint.
+ */
+declare class APICallAuditLog {
+    readonly connectionId: string;
+    readonly providerId: string;
+    readonly method: string;
+    readonly url: string;
+    readonly requestHeaders: Record<string, string> | null;
+    readonly requestBody: unknown | null;
+    readonly responseStatus: number;
+    readonly responseHeaders: Record<string, string> | null;
+    readonly responseBody: unknown | null;
+    readonly latencyMs: number;
+    /** Client-side timestamp (excluded from sanitize() output, like Python SDK) */
+    readonly timestamp: Date;
+    readonly reason: string | null;
+    /** Execution run ID for actor tracking */
+    readonly runId: string | null;
+    /** Conversation thread ID for actor tracking */
+    readonly threadId: string | null;
+    /** Tool invocation ID for actor tracking */
+    readonly toolCallId: string | null;
+    constructor(data: {
+        connectionId: string;
+        providerId: string;
+        method: string;
+        url: string;
+        requestHeaders?: Record<string, string> | null;
+        requestBody?: unknown | null;
+        responseStatus: number;
+        responseHeaders?: Record<string, string> | null;
+        responseBody?: unknown | null;
+        latencyMs: number;
+        reason?: string | null;
+        runId?: string | null;
+        threadId?: string | null;
+        toolCallId?: string | null;
+    });
+    /**
+     * Sanitize sensitive data before sending.
+     *
+     * Removes Authorization headers, cookies, etc.
+     */
+    sanitize(): Record<string, unknown>;
+    private filterSensitiveHeaders;
+}
+
+/**
+ * Exception hierarchy for Alter SDK.
+ *
+ * All exceptions inherit from AlterSDKError for easy catching.
+ */
+/**
+ * Base exception for all Alter SDK errors.
+ */
+declare class AlterSDKError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message: string, details?: Record<string, unknown>);
+    toString(): string;
+}
+/**
+ * Raised when token retrieval fails.
+ */
+declare class TokenRetrievalError extends AlterSDKError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when token access is denied by policy enforcement.
+ *
+ * This indicates the connection exists but access was denied by Cerbos policy
+ * (e.g., unauthorized scopes, outside business hours, rate limit exceeded).
+ */
+declare class PolicyViolationError extends TokenRetrievalError {
+    readonly policyError: string | undefined;
+    constructor(message: string, policyError?: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when OAuth connection not found.
+ *
+ * This indicates no connection exists for the given provider and attributes.
+ */
+declare class ConnectionNotFoundError extends TokenRetrievalError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when token refresh fails.
+ *
+ * This indicates the connection exists but token refresh failed (e.g., refresh
+ * token revoked, provider API error).
+ */
+declare class TokenExpiredError extends TokenRetrievalError {
+    readonly connectionId: string | undefined;
+    constructor(message: string, connectionId?: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when provider API call fails.
+ *
+ * This is raised when the actual provider API returns an error (4xx/5xx).
+ */
+declare class ProviderAPIError extends AlterSDKError {
+    readonly statusCode: number | undefined;
+    readonly responseBody: string | undefined;
+    constructor(message: string, statusCode?: number, responseBody?: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when network operations fail.
+ *
+ * This includes connection errors, DNS failures, and other network issues when
+ * communicating with Alter Vault backend or provider APIs.
+ *
+ * For timeout-specific errors, see {@link TimeoutError}.
+ */
+declare class NetworkError extends AlterSDKError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Raised when a request times out.
+ *
+ * Extends NetworkError so callers catching NetworkError will still catch timeouts,
+ * but callers can also catch TimeoutError specifically to implement retry strategies
+ * (e.g., retry on timeout but not on connection refused).
+ */
+declare class TimeoutError extends NetworkError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+
+export { APICallAuditLog, AlterSDKError, AlterVault, type AlterVaultOptions, ConnectionNotFoundError, HttpMethod, NetworkError, PolicyViolationError, Provider, ProviderAPIError, type RequestOptions, TimeoutError, TokenExpiredError, TokenResponse, TokenRetrievalError };