@alter-ai/alter-sdk 0.2.0

package/dist/index.js

@@ -0,0 +1,923 @@
+// src/exceptions.ts
+var AlterSDKError = class extends Error {
+  details;
+  constructor(message, details) {
+    super(message);
+    this.name = "AlterSDKError";
+    this.details = details ?? {};
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+  toString() {
+    if (Object.keys(this.details).length > 0) {
+      return `${this.message} (details: ${JSON.stringify(this.details)})`;
+    }
+    return this.message;
+  }
+};
+var TokenRetrievalError = class extends AlterSDKError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "TokenRetrievalError";
+  }
+};
+var PolicyViolationError = class extends TokenRetrievalError {
+  policyError;
+  constructor(message, policyError, details) {
+    super(message, details);
+    this.name = "PolicyViolationError";
+    this.policyError = policyError;
+  }
+};
+var ConnectionNotFoundError = class extends TokenRetrievalError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "ConnectionNotFoundError";
+  }
+};
+var TokenExpiredError = class extends TokenRetrievalError {
+  connectionId;
+  constructor(message, connectionId, details) {
+    super(message, details);
+    this.name = "TokenExpiredError";
+    this.connectionId = connectionId;
+  }
+};
+var ProviderAPIError = class extends AlterSDKError {
+  statusCode;
+  responseBody;
+  constructor(message, statusCode, responseBody, details) {
+    super(message, details);
+    this.name = "ProviderAPIError";
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+  }
+};
+var NetworkError = class extends AlterSDKError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "NetworkError";
+  }
+};
+var TimeoutError = class extends NetworkError {
+  constructor(message, details) {
+    super(message, details);
+    this.name = "TimeoutError";
+  }
+};
+
+// src/models.ts
+var TokenResponse = class _TokenResponse {
+  /** Token type (usually "Bearer") */
+  tokenType;
+  /** Seconds until token expires */
+  expiresIn;
+  /** Absolute expiration time */
+  expiresAt;
+  /** OAuth scopes granted */
+  scopes;
+  /** Connection ID that provided this token */
+  connectionId;
+  constructor(data) {
+    this.tokenType = data.token_type ?? "Bearer";
+    this.expiresIn = data.expires_in ?? null;
+    this.expiresAt = data.expires_at ? _TokenResponse.parseExpiresAt(data.expires_at) : null;
+    this.scopes = data.scopes ?? [];
+    this.connectionId = data.connection_id;
+    Object.freeze(this);
+  }
+  /**
+   * Parse expires_at from ISO string.
+   */
+  static parseExpiresAt(value) {
+    const dt = new Date(value);
+    if (isNaN(dt.getTime())) {
+      throw new Error(`Invalid expires_at value: ${value}`);
+    }
+    return dt;
+  }
+  /**
+   * 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 = 0) {
+    if (this.expiresAt === null) {
+      return false;
+    }
+    const now = Date.now();
+    return this.expiresAt.getTime() <= now + bufferSeconds * 1e3;
+  }
+  /**
+   * 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 = 300) {
+    return this.isExpired(bufferSeconds);
+  }
+  /**
+   * Custom JSON serialization — EXCLUDES access_token for security.
+   */
+  toJSON() {
+    return {
+      token_type: this.tokenType,
+      expires_in: this.expiresIn,
+      expires_at: this.expiresAt?.toISOString() ?? null,
+      scopes: this.scopes,
+      connection_id: this.connectionId
+    };
+  }
+  /**
+   * Custom string representation — EXCLUDES access_token for security.
+   */
+  toString() {
+    return `TokenResponse(connection_id=${this.connectionId}, token_type=${this.tokenType}, scopes=[${this.scopes.join(", ")}])`;
+  }
+  /**
+   * Custom Node.js inspect output — EXCLUDES access_token for security.
+   */
+  [/* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toString();
+  }
+};
+var SENSITIVE_HEADERS = /* @__PURE__ */ new Set([
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "x-auth-token"
+]);
+var APICallAuditLog = class {
+  connectionId;
+  providerId;
+  method;
+  url;
+  requestHeaders;
+  requestBody;
+  responseStatus;
+  responseHeaders;
+  responseBody;
+  latencyMs;
+  /** Client-side timestamp (excluded from sanitize() output, like Python SDK) */
+  timestamp;
+  reason;
+  /** Execution run ID for actor tracking */
+  runId;
+  /** Conversation thread ID for actor tracking */
+  threadId;
+  /** Tool invocation ID for actor tracking */
+  toolCallId;
+  constructor(data) {
+    this.connectionId = data.connectionId;
+    this.providerId = data.providerId;
+    this.method = data.method;
+    this.url = data.url;
+    this.requestHeaders = data.requestHeaders ?? null;
+    this.requestBody = data.requestBody ?? null;
+    this.responseStatus = data.responseStatus;
+    this.responseHeaders = data.responseHeaders ?? null;
+    this.responseBody = data.responseBody ?? null;
+    this.latencyMs = data.latencyMs;
+    this.timestamp = /* @__PURE__ */ new Date();
+    this.reason = data.reason ?? null;
+    this.runId = data.runId ?? null;
+    this.threadId = data.threadId ?? null;
+    this.toolCallId = data.toolCallId ?? null;
+  }
+  /**
+   * Sanitize sensitive data before sending.
+   *
+   * Removes Authorization headers, cookies, etc.
+   */
+  sanitize() {
+    const sanitized = {
+      connection_id: this.connectionId,
+      provider_id: this.providerId,
+      method: this.method,
+      url: this.url,
+      request_headers: this.requestHeaders ? this.filterSensitiveHeaders(this.requestHeaders) : null,
+      request_body: this.requestBody,
+      response_status: this.responseStatus,
+      response_headers: this.responseHeaders ? this.filterSensitiveHeaders(this.responseHeaders) : null,
+      response_body: this.responseBody,
+      latency_ms: this.latencyMs,
+      reason: this.reason,
+      run_id: this.runId,
+      thread_id: this.threadId,
+      tool_call_id: this.toolCallId
+    };
+    return sanitized;
+  }
+  filterSensitiveHeaders(headers) {
+    const filtered = {};
+    for (const [key, value] of Object.entries(headers)) {
+      if (!SENSITIVE_HEADERS.has(key.toLowerCase())) {
+        filtered[key] = value;
+      }
+    }
+    return filtered;
+  }
+};
+
+// src/client.ts
+var _tokenStore = /* @__PURE__ */ new WeakMap();
+function _storeAccessToken(token, accessToken) {
+  _tokenStore.set(token, accessToken);
+}
+function _extractAccessToken(token) {
+  const value = _tokenStore.get(token);
+  if (value === void 0) {
+    throw new Error(
+      "Token data unavailable \u2014 TokenResponse may have been garbage collected"
+    );
+  }
+  return value;
+}
+var _fetch;
+var SDK_VERSION = "0.2.0";
+var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
+var VALID_ACTOR_TYPES = ["ai_agent", "mcp_server"];
+var HTTP_FORBIDDEN = 403;
+var HTTP_NOT_FOUND = 404;
+var HTTP_BAD_REQUEST = 400;
+var HTTP_UNAUTHORIZED = 401;
+var HTTP_BAD_GATEWAY = 502;
+var HTTP_INTERNAL_SERVER_ERROR = 500;
+var HTTP_SERVICE_UNAVAILABLE = 503;
+var MAX_BODY_SIZE_BYTES = 1e4;
+var HTTP_CLIENT_ERROR_START = 400;
+var MAX_ACTOR_STRING_LENGTH = 255;
+var MAX_TRACKING_ID_LENGTH = 255;
+var SAFE_HEADER_PATTERN = /^[\x20-\x7E]+$/;
+var ALLOWED_URL_SCHEMES = ["https://", "http://"];
+var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var HttpClient = class {
+  #baseUrl;
+  #defaultHeaders;
+  #timeoutMs;
+  constructor(options) {
+    this.#baseUrl = options.baseUrl ?? "";
+    this.#defaultHeaders = { ...options.headers };
+    this.#timeoutMs = options.timeout;
+    Object.freeze(this);
+  }
+  /** Get default headers (returns a copy). */
+  get headers() {
+    return { ...this.#defaultHeaders };
+  }
+  /**
+   * Execute an HTTP request.
+   */
+  async request(method, url, options) {
+    let fullUrl = this.#baseUrl ? `${this.#baseUrl}${url}` : url;
+    if (options?.params && Object.keys(options.params).length > 0) {
+      const stringParams = {};
+      for (const [key, value] of Object.entries(options.params)) {
+        stringParams[key] = String(value);
+      }
+      const searchParams = new URLSearchParams(stringParams);
+      const separator = fullUrl.includes("?") ? "&" : "?";
+      fullUrl = `${fullUrl}${separator}${searchParams.toString()}`;
+    }
+    const mergedHeaders = {
+      ...this.#defaultHeaders,
+      ...options?.headers
+    };
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort(new DOMException("The operation timed out.", "TimeoutError"));
+    }, this.#timeoutMs);
+    const init = {
+      method,
+      headers: mergedHeaders,
+      signal: controller.signal
+    };
+    if (options?.json !== void 0) {
+      init.body = JSON.stringify(options.json);
+      mergedHeaders["Content-Type"] = "application/json";
+    }
+    const fetchFn = _fetch ?? globalThis.fetch;
+    try {
+      return await fetchFn(fullUrl, init);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Execute a POST request.
+   */
+  async post(url, options) {
+    return this.request("POST", url, options);
+  }
+};
+Object.freeze(HttpClient.prototype);
+var AlterVault = class _AlterVault {
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // SECURITY LAYER 4: ES2022 private fields — truly private at runtime.
+  // These are NOT accessible via (obj as any), Object.keys(), or prototype.
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  /** HTTP Client for Alter Backend (has x-api-key) */
+  #alterClient;
+  /** HTTP Client for External Provider APIs (NO x-api-key) */
+  #providerClient;
+  /** Cached actor_id from backend response (avoids DB lookup) */
+  #cachedActorId = null;
+  /** Whether close() has been called */
+  #closed = false;
+  /** Pending audit log promises (fire-and-forget) */
+  #auditPromises = /* @__PURE__ */ new Set();
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  // Public readonly properties (frozen by Object.freeze)
+  // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  baseUrl;
+  enableAuditLogging;
+  /** Actor tracking configuration (readonly, not secret) */
+  #actorType;
+  #actorIdentifier;
+  #actorName;
+  #actorVersion;
+  #clientType;
+  #framework;
+  constructor(options) {
+    _AlterVault.#validateInitParams(
+      options.apiKey,
+      options.actorType,
+      options.actorIdentifier
+    );
+    const actorStrings = [
+      ["actorIdentifier", options.actorIdentifier],
+      ["actorName", options.actorName],
+      ["actorVersion", options.actorVersion],
+      ["clientType", options.clientType],
+      ["framework", options.framework]
+    ];
+    for (const [name, value] of actorStrings) {
+      _AlterVault.#validateActorString(value, name);
+    }
+    this.baseUrl = (options.baseUrl ?? "https://api.alter.com").replace(
+      /\/+$/,
+      ""
+    );
+    this.enableAuditLogging = options.enableAuditLogging ?? true;
+    const timeoutMs = options.timeout ?? 3e4;
+    this.#actorType = options.actorType;
+    this.#actorIdentifier = options.actorIdentifier;
+    this.#actorName = options.actorName;
+    this.#actorVersion = options.actorVersion;
+    this.#clientType = options.clientType;
+    this.#framework = options.framework;
+    if (!_fetch) {
+      _fetch = globalThis.fetch;
+    }
+    const alterHeaders = this.#buildAlterClientHeaders(options.apiKey);
+    this.#alterClient = new HttpClient({
+      baseUrl: this.baseUrl,
+      headers: alterHeaders,
+      timeout: timeoutMs
+    });
+    this.#providerClient = new HttpClient({
+      headers: {
+        "User-Agent": SDK_USER_AGENT
+      },
+      timeout: timeoutMs
+    });
+    Object.freeze(this);
+  }
+  /**
+   * Validate an actor string parameter for length and safe characters.
+   */
+  static #validateActorString(value, name, maxLength = MAX_ACTOR_STRING_LENGTH) {
+    if (value === void 0) {
+      return;
+    }
+    if (value.length > maxLength) {
+      throw new AlterSDKError(
+        `${name} exceeds max length (${maxLength}): ${value.length}`
+      );
+    }
+    if (!SAFE_HEADER_PATTERN.test(value)) {
+      throw new AlterSDKError(
+        `${name} contains invalid characters (only printable ASCII allowed)`
+      );
+    }
+  }
+  /**
+   * Validate constructor parameters. Throws Error on invalid input.
+   */
+  static #validateInitParams(apiKey, actorType, actorIdentifier) {
+    if (!apiKey) {
+      throw new AlterSDKError("api_key is required");
+    }
+    if (!apiKey.startsWith("alter_key_")) {
+      throw new AlterSDKError("api_key must start with 'alter_key_'");
+    }
+    if (actorType && !VALID_ACTOR_TYPES.includes(actorType)) {
+      throw new AlterSDKError("actor_type must be 'ai_agent' or 'mcp_server'");
+    }
+    if (actorType && !actorIdentifier) {
+      throw new AlterSDKError(
+        "actor_identifier is required when actor_type is set"
+      );
+    }
+  }
+  /**
+   * Build default headers for the Alter backend HTTP client.
+   *
+   * SECURITY: apiKey is passed as parameter, NOT read from this.
+   */
+  #buildAlterClientHeaders(apiKey) {
+    const headers = {
+      "x-api-key": apiKey,
+      "User-Agent": SDK_USER_AGENT
+    };
+    const actorHeaders = {
+      "X-Alter-Actor-Type": this.#actorType,
+      "X-Alter-Actor-Identifier": this.#actorIdentifier,
+      "X-Alter-Actor-Name": this.#actorName,
+      "X-Alter-Actor-Version": this.#actorVersion,
+      "X-Alter-Client-Type": this.#clientType,
+      "X-Alter-Framework": this.#framework
+    };
+    for (const [key, value] of Object.entries(actorHeaders)) {
+      if (value) {
+        headers[key] = value;
+      }
+    }
+    return headers;
+  }
+  /**
+   * Build per-request actor headers for instance tracking.
+   */
+  #getActorRequestHeaders(runId, threadId, toolCallId) {
+    const headers = {};
+    if (this.#cachedActorId) {
+      headers["X-Alter-Actor-ID"] = this.#cachedActorId;
+    }
+    if (runId) {
+      if (UUID_PATTERN.test(runId)) {
+        headers["X-Alter-Run-ID"] = runId;
+      } else {
+        console.warn(`Invalid run_id (must be UUID), skipping: ${runId}`);
+      }
+    }
+    if (threadId) {
+      if (threadId.length <= MAX_TRACKING_ID_LENGTH && SAFE_HEADER_PATTERN.test(threadId)) {
+        headers["X-Alter-Thread-ID"] = threadId;
+      } else {
+        console.warn(
+          "Invalid thread_id (too long or invalid chars), skipping"
+        );
+      }
+    }
+    if (toolCallId) {
+      if (toolCallId.length <= MAX_TRACKING_ID_LENGTH && SAFE_HEADER_PATTERN.test(toolCallId)) {
+        headers["X-Alter-Tool-Call-ID"] = toolCallId;
+      } else {
+        console.warn(
+          "Invalid tool_call_id (too long or invalid chars), skipping"
+        );
+      }
+    }
+    return headers;
+  }
+  /**
+   * Cache actor_id from response header for subsequent requests.
+   */
+  #cacheActorIdFromResponse(response) {
+    const actorId = response.headers.get("X-Alter-Actor-ID");
+    if (actorId && !this.#cachedActorId) {
+      if (!UUID_PATTERN.test(actorId)) {
+        console.warn(
+          `Invalid actor_id in response header (not a UUID), ignoring: ${actorId}`
+        );
+        return;
+      }
+      this.#cachedActorId = actorId;
+    } else if (actorId && this.#cachedActorId && actorId !== this.#cachedActorId) {
+      console.warn(
+        `Backend returned different actor_id (${actorId}) than cached (${this.#cachedActorId}), ignoring`
+      );
+    }
+  }
+  /**
+   * Check if an error is a timeout or abort error.
+   */
+  static #isTimeoutOrAbortError(error) {
+    if (error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError")) {
+      return true;
+    }
+    if (typeof DOMException !== "undefined" && error instanceof DOMException && (error.name === "TimeoutError" || error.name === "AbortError")) {
+      return true;
+    }
+    return false;
+  }
+  static async #safeParseJson(response) {
+    try {
+      return await response.clone().json();
+    } catch {
+      try {
+        const text = await response.clone().text();
+        return { message: text.slice(0, 500) || "Unknown error" };
+      } catch {
+        return { message: "Unknown error" };
+      }
+    }
+  }
+  /**
+   * Handle HTTP error responses from backend.
+   */
+  async #handleErrorResponse(response) {
+    if (response.ok) {
+      return;
+    }
+    if (response.status === HTTP_FORBIDDEN) {
+      const errorData = await _AlterVault.#safeParseJson(response);
+      throw new PolicyViolationError(
+        errorData.message ?? "Access denied by policy",
+        errorData.error,
+        errorData.details
+      );
+    }
+    if (response.status === HTTP_NOT_FOUND) {
+      const errorData = await _AlterVault.#safeParseJson(response);
+      throw new ConnectionNotFoundError(
+        errorData.message ?? "OAuth connection not found for these attributes",
+        errorData
+      );
+    }
+    if (response.status === HTTP_BAD_REQUEST || response.status === HTTP_BAD_GATEWAY) {
+      const errorData = await _AlterVault.#safeParseJson(response);
+      if (JSON.stringify(errorData).toLowerCase().includes("token_expired")) {
+        throw new TokenExpiredError(
+          errorData.message ?? "Token expired and refresh failed",
+          errorData.connection_id,
+          errorData
+        );
+      }
+      throw new TokenRetrievalError(
+        errorData.message ?? `Backend error ${response.status}`,
+        errorData
+      );
+    }
+    if (response.status === HTTP_UNAUTHORIZED) {
+      const errorData = await _AlterVault.#safeParseJson(response);
+      throw new TokenRetrievalError(
+        errorData.message ?? "Unauthorized \u2014 check your API key",
+        errorData
+      );
+    }
+    if (response.status === HTTP_INTERNAL_SERVER_ERROR || response.status === HTTP_SERVICE_UNAVAILABLE) {
+      const errorData = await _AlterVault.#safeParseJson(response);
+      throw new TokenRetrievalError(
+        errorData.message ?? `Backend unavailable (HTTP ${response.status})`,
+        errorData
+      );
+    }
+    if (response.status >= HTTP_CLIENT_ERROR_START) {
+      const errorData = await _AlterVault.#safeParseJson(response);
+      throw new TokenRetrievalError(
+        errorData.message ?? `Unexpected backend error (HTTP ${response.status})`,
+        errorData
+      );
+    }
+  }
+  /**
+   * Retrieve OAuth access token for a provider and user (INTERNAL USE ONLY).
+   *
+   * This is a private method. Tokens are NEVER exposed to developers.
+   * Use request() instead, which handles tokens internally.
+   */
+  async #getToken(providerId, attributes, reason, runId, threadId, toolCallId) {
+    const actorHeaders = this.#getActorRequestHeaders(
+      runId,
+      threadId,
+      toolCallId
+    );
+    let response;
+    try {
+      response = await this.#alterClient.post("/oauth/token", {
+        json: {
+          provider_id: providerId,
+          attributes,
+          reason: reason ?? null
+        },
+        headers: actorHeaders
+      });
+    } catch (error) {
+      if (_AlterVault.#isTimeoutOrAbortError(error)) {
+        throw new TimeoutError(
+          `Request to Alter Vault backend timed out: ${error instanceof Error ? error.message : String(error)}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      if (error instanceof TypeError) {
+        throw new NetworkError(
+          `Failed to connect to Alter Vault backend: ${error.message}`,
+          { base_url: this.baseUrl }
+        );
+      }
+      throw new TokenRetrievalError(
+        `Failed to retrieve token: ${error instanceof Error ? error.message : String(error)}`,
+        { provider_id: providerId, error: String(error) }
+      );
+    }
+    this.#cacheActorIdFromResponse(response);
+    await this.#handleErrorResponse(response);
+    const tokenData = await response.json();
+    const typedData = tokenData;
+    const tokenResponse = new TokenResponse(typedData);
+    _storeAccessToken(tokenResponse, typedData.access_token);
+    return tokenResponse;
+  }
+  /**
+   * Log an API call to the backend audit endpoint (INTERNAL).
+   *
+   * This method NEVER throws exceptions to avoid crashing the application
+   * if audit logging fails.
+   */
+  async #logApiCall(params) {
+    if (!this.enableAuditLogging) {
+      return;
+    }
+    try {
+      const auditLog = new APICallAuditLog({
+        connectionId: params.connectionId,
+        providerId: params.providerId,
+        method: params.method,
+        url: params.url,
+        requestHeaders: params.requestHeaders,
+        requestBody: params.requestBody,
+        responseStatus: params.responseStatus,
+        responseHeaders: params.responseHeaders,
+        responseBody: params.responseBody,
+        latencyMs: params.latencyMs,
+        reason: params.reason,
+        runId: params.runId,
+        threadId: params.threadId,
+        toolCallId: params.toolCallId
+      });
+      const sanitized = auditLog.sanitize();
+      const actorHeaders = this.#getActorRequestHeaders();
+      const response = await this.#alterClient.post("/oauth/audit/api-call", {
+        json: sanitized,
+        headers: actorHeaders
+      });
+      this.#cacheActorIdFromResponse(response);
+      if (!response.ok) {
+        console.warn(
+          `Audit log failed with status ${response.status} (non-fatal)`
+        );
+      }
+    } catch (error) {
+      console.warn(
+        `Failed to log API call (non-fatal): ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  /**
+   * Extract response body for audit logging without decoding large/binary payloads.
+   */
+  static async #safeResponseBody(response, maxBytes = MAX_BODY_SIZE_BYTES) {
+    try {
+      const cloned = response.clone();
+      const buffer = await cloned.arrayBuffer();
+      const contentLength = buffer.byteLength;
+      if (contentLength === 0) {
+        return "";
+      }
+      if (contentLength > maxBytes) {
+        return `<response too large: ${contentLength} bytes>`;
+      }
+      try {
+        const decoder = new TextDecoder("utf-8", { fatal: true });
+        const text = decoder.decode(buffer);
+        if (text.length > maxBytes) {
+          return text.slice(0, maxBytes) + "...";
+        }
+        return text;
+      } catch {
+        return `<binary response: ${contentLength} bytes>`;
+      }
+    } catch {
+      return "";
+    }
+  }
+  /**
+   * Schedule audit logging as a fire-and-forget background task.
+   */
+  #scheduleAuditLog(params) {
+    try {
+      const promise = this.#logApiCall(params).catch(() => {
+      });
+      this.#auditPromises.add(promise);
+      promise.finally(() => {
+        this.#auditPromises.delete(promise);
+      });
+    } catch {
+    }
+  }
+  /**
+   * 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
+   */
+  async request(provider, method, url, options) {
+    if (this.#closed) {
+      throw new AlterSDKError(
+        "SDK instance has been closed. Create a new AlterVault instance to make requests."
+      );
+    }
+    const providerStr = String(provider);
+    const methodStr = String(method).toUpperCase();
+    const urlLower = url.toLowerCase();
+    if (!ALLOWED_URL_SCHEMES.some((scheme) => urlLower.startsWith(scheme))) {
+      throw new AlterSDKError(
+        `URL must start with https:// or http://, got: ${url.slice(0, 50)}`
+      );
+    }
+    if (options.pathParams && Object.keys(options.pathParams).length > 0) {
+      const encodedParams = {};
+      for (const [key, value] of Object.entries(options.pathParams)) {
+        encodedParams[key] = encodeURIComponent(String(value));
+      }
+      try {
+        let resolvedUrl = url;
+        for (const [key, value] of Object.entries(encodedParams)) {
+          const placeholder = `{${key}}`;
+          if (!resolvedUrl.includes(placeholder)) {
+            continue;
+          }
+          resolvedUrl = resolvedUrl.replaceAll(placeholder, value);
+        }
+        const remaining = resolvedUrl.match(/\{(\w+)\}/);
+        if (remaining) {
+          throw new AlterSDKError(
+            `Invalid URL template or missing path_params: '${remaining[1]}'. URL: ${url}, path_params: ${JSON.stringify(options.pathParams)}`
+          );
+        }
+        url = resolvedUrl;
+      } catch (error) {
+        if (error instanceof AlterSDKError) {
+          throw error;
+        }
+        throw new AlterSDKError(
+          `Invalid URL template or missing path_params: ${error instanceof Error ? error.message : String(error)}. URL: ${url}, path_params: ${JSON.stringify(options.pathParams)}`
+        );
+      }
+    }
+    if (options.extraHeaders && "Authorization" in options.extraHeaders) {
+      console.warn(
+        "extraHeaders contains 'Authorization' which will be overwritten with the auto-injected Bearer token"
+      );
+    }
+    const tokenResponse = await this.#getToken(
+      providerStr,
+      options.user,
+      options.reason,
+      options.runId,
+      options.threadId,
+      options.toolCallId
+    );
+    const requestHeaders = options.extraHeaders ? { ...options.extraHeaders } : {};
+    requestHeaders["Authorization"] = `Bearer ${_extractAccessToken(tokenResponse)}`;
+    if (!requestHeaders["User-Agent"]) {
+      requestHeaders["User-Agent"] = SDK_USER_AGENT;
+    }
+    const startTime = Date.now();
+    let response;
+    try {
+      response = await this.#providerClient.request(methodStr, url, {
+        json: options.json,
+        headers: requestHeaders,
+        params: options.queryParams
+      });
+    } catch (error) {
+      if (_AlterVault.#isTimeoutOrAbortError(error)) {
+        throw new TimeoutError(
+          `Provider API request timed out: ${error instanceof Error ? error.message : String(error)}`,
+          {
+            provider: providerStr,
+            method: methodStr,
+            url
+          }
+        );
+      }
+      throw new NetworkError(
+        `Failed to call provider API: ${error instanceof Error ? error.message : String(error)}`,
+        {
+          provider: providerStr,
+          method: methodStr,
+          url,
+          error: String(error)
+        }
+      );
+    }
+    const latencyMs = Date.now() - startTime;
+    const auditHeaders = {};
+    for (const [key, value] of Object.entries(requestHeaders)) {
+      if (key.toLowerCase() !== "authorization") {
+        auditHeaders[key] = value;
+      }
+    }
+    const responseBody = await _AlterVault.#safeResponseBody(response);
+    const responseHeaders = {};
+    response.headers.forEach((value, key) => {
+      responseHeaders[key] = value;
+    });
+    this.#scheduleAuditLog({
+      connectionId: tokenResponse.connectionId,
+      providerId: providerStr,
+      method: methodStr,
+      url,
+      requestHeaders: auditHeaders,
+      requestBody: options.json ?? null,
+      responseStatus: response.status,
+      responseHeaders,
+      responseBody,
+      latencyMs,
+      reason: options.reason ?? null,
+      runId: options.runId ?? null,
+      threadId: options.threadId ?? null,
+      toolCallId: options.toolCallId ?? null
+    });
+    if (response.status >= HTTP_CLIENT_ERROR_START) {
+      throw new ProviderAPIError(
+        `Provider API returned error ${response.status}`,
+        response.status,
+        responseBody,
+        {
+          provider: providerStr,
+          method: methodStr,
+          url
+        }
+      );
+    }
+    return response;
+  }
+  /**
+   * Close HTTP clients and release resources.
+   * Waits for any pending audit tasks before closing.
+   */
+  async close() {
+    if (this.#closed) {
+      return;
+    }
+    this.#closed = true;
+    if (this.#auditPromises.size > 0) {
+      await Promise.allSettled([...this.#auditPromises]);
+    }
+  }
+  /**
+   * Async dispose support for `await using vault = new AlterVault(...)`.
+   * Requires TypeScript 5.2+ and Node.js 18+.
+   */
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+};
+Object.freeze(AlterVault.prototype);
+
+// src/providers/enums.ts
+var Provider = /* @__PURE__ */ ((Provider2) => {
+  Provider2["GOOGLE"] = "google";
+  Provider2["GITHUB"] = "github";
+  Provider2["SLACK"] = "slack";
+  Provider2["MICROSOFT"] = "microsoft";
+  Provider2["SALESFORCE"] = "salesforce";
+  Provider2["SENTRY"] = "sentry";
+  return Provider2;
+})(Provider || {});
+var HttpMethod = /* @__PURE__ */ ((HttpMethod2) => {
+  HttpMethod2["GET"] = "GET";
+  HttpMethod2["POST"] = "POST";
+  HttpMethod2["PUT"] = "PUT";
+  HttpMethod2["PATCH"] = "PATCH";
+  HttpMethod2["DELETE"] = "DELETE";
+  HttpMethod2["HEAD"] = "HEAD";
+  HttpMethod2["OPTIONS"] = "OPTIONS";
+  return HttpMethod2;
+})(HttpMethod || {});
+export {
+  APICallAuditLog,
+  AlterSDKError,
+  AlterVault,
+  ConnectionNotFoundError,
+  HttpMethod,
+  NetworkError,
+  PolicyViolationError,
+  Provider,
+  ProviderAPIError,
+  TimeoutError,
+  TokenExpiredError,
+  TokenResponse,
+  TokenRetrievalError
+};