@alter-ai/alter-sdk 0.6.0 → 0.7.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/client.ts
-import { createHash as createHash2, createHmac as createHmac2, randomUUID } from "crypto";
+import { createHash as createHash2, createHmac as createHmac2, randomBytes, randomUUID } from "crypto";
 
 // src/exceptions.ts
 var AlterSDKError = class extends Error {
@@ -29,30 +29,38 @@ var ReAuthRequiredError = class extends BackendError {
     this.name = "ReAuthRequiredError";
   }
 };
-var ConnectionExpiredError = class extends ReAuthRequiredError {
+var GrantExpiredError = class extends ReAuthRequiredError {
   constructor(message, details) {
     super(message, details);
-    this.name = "ConnectionExpiredError";
+    this.name = "GrantExpiredError";
   }
 };
-var ConnectionRevokedError = class extends ReAuthRequiredError {
-  connectionId;
-  constructor(message, connectionId, details) {
+var GrantRevokedError = class extends ReAuthRequiredError {
+  grantId;
+  constructor(message, grantId, details) {
     super(message, details);
-    this.name = "ConnectionRevokedError";
-    this.connectionId = connectionId;
+    this.name = "GrantRevokedError";
+    this.grantId = grantId;
   }
 };
-var ConnectionDeletedError = class extends ReAuthRequiredError {
+var CredentialRevokedError = class extends ReAuthRequiredError {
+  grantId;
+  constructor(message, grantId, details) {
+    super(message, details);
+    this.name = "CredentialRevokedError";
+    this.grantId = grantId;
+  }
+};
+var GrantDeletedError = class extends ReAuthRequiredError {
   constructor(message, details) {
     super(message, details);
-    this.name = "ConnectionDeletedError";
+    this.name = "GrantDeletedError";
   }
 };
-var ConnectionNotFoundError = class extends BackendError {
+var GrantNotFoundError = class extends BackendError {
   constructor(message, details) {
     super(message, details);
-    this.name = "ConnectionNotFoundError";
+    this.name = "GrantNotFoundError";
   }
 };
 var PolicyViolationError = class extends BackendError {
@@ -98,12 +106,12 @@ var ProviderAPIError = class extends AlterSDKError {
   }
 };
 var ScopeReauthRequiredError = class extends ProviderAPIError {
-  connectionId;
+  grantId;
   providerId;
-  constructor(message, connectionId, providerId, statusCode, responseBody, details) {
+  constructor(message, grantId, providerId, statusCode, responseBody, details) {
     super(message, statusCode, responseBody, details);
     this.name = "ScopeReauthRequiredError";
-    this.connectionId = connectionId;
+    this.grantId = grantId;
     this.providerId = providerId;
   }
 };
@@ -124,7 +132,6 @@ var TimeoutError = class extends NetworkError {
 var ActorType = /* @__PURE__ */ ((ActorType2) => {
   ActorType2["BACKEND_SERVICE"] = "backend_service";
   ActorType2["AI_AGENT"] = "ai_agent";
-  ActorType2["MCP_SERVER"] = "mcp_server";
   return ActorType2;
 })(ActorType || {});
 var TokenResponse = class _TokenResponse {
@@ -136,8 +143,8 @@ var TokenResponse = class _TokenResponse {
   expiresAt;
   /** OAuth scopes granted */
   scopes;
-  /** Connection ID that provided this token */
-  connectionId;
+  /** Grant ID that provided this token */
+  grantId;
   /** Provider ID (google, github, etc.) */
   providerId;
   /** HTTP header name for credential injection (e.g., "Authorization", "X-API-Key") */
@@ -153,8 +160,8 @@ var TokenResponse = class _TokenResponse {
     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;
-    this.providerId = data.provider_id ?? "";
+    this.grantId = data.grant_id;
+    this.providerId = data.provider_id ?? null;
     this.injectionHeader = data.injection_header ?? "Authorization";
     this.injectionFormat = data.injection_format ?? "Bearer {token}";
     if (data.additional_credentials) {
@@ -209,7 +216,7 @@ var TokenResponse = class _TokenResponse {
       expires_in: this.expiresIn,
       expires_at: this.expiresAt?.toISOString() ?? null,
       scopes: this.scopes,
-      connection_id: this.connectionId,
+      grant_id: this.grantId,
       provider_id: this.providerId
     };
   }
@@ -217,7 +224,7 @@ var TokenResponse = class _TokenResponse {
    * Custom string representation — EXCLUDES access_token for security.
    */
   toString() {
-    return `TokenResponse(connection_id=${this.connectionId}, token_type=${this.tokenType}, scopes=[${this.scopes.join(", ")}])`;
+    return `TokenResponse(grant_id=${this.grantId}, token_type=${this.tokenType}, scopes=[${this.scopes.join(", ")}])`;
   }
   /**
    * Custom Node.js inspect output — EXCLUDES access_token for security.
@@ -226,8 +233,8 @@ var TokenResponse = class _TokenResponse {
     return this.toString();
   }
 };
-var ConnectionInfo = class {
-  connectionId;
+var GrantInfo = class {
+  grantId;
   providerId;
   scopes;
   accountIdentifier;
@@ -238,7 +245,7 @@ var ConnectionInfo = class {
   createdAt;
   lastUsedAt;
   constructor(data) {
-    this.connectionId = data.connection_id;
+    this.grantId = data.grant_id;
     this.providerId = data.provider_id;
     this.scopes = data.scopes ?? [];
     this.accountIdentifier = data.account_identifier ?? null;
@@ -252,7 +259,7 @@ var ConnectionInfo = class {
   }
   toJSON() {
     return {
-      connection_id: this.connectionId,
+      grant_id: this.grantId,
       provider_id: this.providerId,
       scopes: this.scopes,
       account_identifier: this.accountIdentifier,
@@ -265,7 +272,7 @@ var ConnectionInfo = class {
     };
   }
   toString() {
-    return `ConnectionInfo(connection_id=${this.connectionId}, provider=${this.providerId}, status=${this.status})`;
+    return `GrantInfo(grant_id=${this.grantId}, provider=${this.providerId}, status=${this.status})`;
   }
 };
 var ConnectSession = class {
@@ -292,60 +299,91 @@ var ConnectSession = class {
     return `ConnectSession(url=${this.connectUrl}, expires_in=${this.expiresIn})`;
   }
 };
-var ConnectionListResult = class {
-  connections;
+var GrantListResult = class {
+  grants;
   total;
   limit;
   offset;
   hasMore;
   constructor(data) {
-    this.connections = data.connections;
+    this.grants = data.grants;
     this.total = data.total;
     this.limit = data.limit;
     this.offset = data.offset;
     this.hasMore = data.has_more;
     Object.freeze(this);
   }
+  /**
+   * Custom JSON serialization — snake_case wire format.
+   */
+  toJSON() {
+    return {
+      grants: this.grants.map((g) => g.toJSON()),
+      total: this.total,
+      limit: this.limit,
+      offset: this.offset,
+      has_more: this.hasMore
+    };
+  }
 };
 var ConnectResult = class {
-  connectionId;
+  grantId;
   providerId;
   accountIdentifier;
   scopes;
-  connectionPolicy;
+  grantPolicy;
   constructor(data) {
-    this.connectionId = data.connection_id;
+    this.grantId = data.grant_id;
     this.providerId = data.provider_id;
     this.accountIdentifier = data.account_identifier ?? null;
     this.scopes = data.scopes ?? [];
-    const rawPolicy = data.connection_policy;
+    const rawPolicy = data.grant_policy;
     if (rawPolicy) {
       const raw = rawPolicy;
-      this.connectionPolicy = Object.freeze({
+      this.grantPolicy = Object.freeze({
         expiresAt: raw["expires_at"] !== void 0 ? raw["expires_at"] : rawPolicy.expiresAt ?? null,
         createdBy: raw["created_by"] !== void 0 ? raw["created_by"] : rawPolicy.createdBy ?? null,
         createdAt: raw["created_at"] !== void 0 ? raw["created_at"] : rawPolicy.createdAt ?? null
       });
     } else {
-      this.connectionPolicy = null;
+      this.grantPolicy = null;
     }
     Object.freeze(this);
   }
   toJSON() {
     return {
-      connection_id: this.connectionId,
+      grant_id: this.grantId,
       provider_id: this.providerId,
       account_identifier: this.accountIdentifier,
       scopes: this.scopes,
-      connection_policy: this.connectionPolicy ? {
-        expires_at: this.connectionPolicy.expiresAt ?? null,
-        created_by: this.connectionPolicy.createdBy ?? null,
-        created_at: this.connectionPolicy.createdAt ?? null
+      grant_policy: this.grantPolicy ? {
+        expires_at: this.grantPolicy.expiresAt ?? null,
+        created_by: this.grantPolicy.createdBy ?? null,
+        created_at: this.grantPolicy.createdAt ?? null
       } : null
     };
   }
   toString() {
-    return `ConnectResult(connection_id=${this.connectionId}, provider=${this.providerId})`;
+    return `ConnectResult(grant_id=${this.grantId}, provider=${this.providerId})`;
+  }
+};
+var AuthResult = class {
+  userToken;
+  userInfo;
+  constructor(data) {
+    this.userToken = data.user_token;
+    this.userInfo = data.user_info ?? {};
+    Object.freeze(this);
+  }
+  toJSON() {
+    return {
+      user_token: this.userToken,
+      user_info: this.userInfo
+    };
+  }
+  toString() {
+    const sub = this.userInfo?.sub ?? "unknown";
+    return `AuthResult(sub=${sub})`;
   }
 };
 var SENSITIVE_HEADERS = /* @__PURE__ */ new Set([
@@ -359,7 +397,7 @@ var SENSITIVE_HEADERS = /* @__PURE__ */ new Set([
   "x-amz-security-token"
 ]);
 var APICallAuditLog = class {
-  connectionId;
+  grantId;
   providerId;
   method;
   url;
@@ -378,22 +416,28 @@ var APICallAuditLog = class {
   threadId;
   /** Tool invocation ID for actor tracking */
   toolCallId;
+  /** Specific tool being invoked (e.g., "read_calendar") */
+  toolId;
+  /** Tool bundle identifier (e.g., "google-calendar-mcp-server") */
+  toolBundleId;
   constructor(data) {
-    this.connectionId = data.connectionId;
-    this.providerId = data.providerId;
+    this.grantId = data.grant_id;
+    this.providerId = data.provider_id;
     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.requestHeaders = data.request_headers ?? null;
+    this.requestBody = data.request_body ?? null;
+    this.responseStatus = data.response_status;
+    this.responseHeaders = data.response_headers ?? null;
+    this.responseBody = data.response_body ?? null;
+    this.latencyMs = data.latency_ms;
     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;
+    this.runId = data.run_id ?? null;
+    this.threadId = data.thread_id ?? null;
+    this.toolCallId = data.tool_call_id ?? null;
+    this.toolId = data.tool_id ?? null;
+    this.toolBundleId = data.tool_bundle_id ?? null;
   }
   /**
    * Sanitize sensitive data before sending.
@@ -402,7 +446,7 @@ var APICallAuditLog = class {
    */
   sanitize() {
     const sanitized = {
-      connection_id: this.connectionId,
+      grant_id: this.grantId,
       provider_id: this.providerId,
       method: this.method,
       url: this.url,
@@ -415,7 +459,9 @@ var APICallAuditLog = class {
       reason: this.reason,
       run_id: this.runId,
       thread_id: this.threadId,
-      tool_call_id: this.toolCallId
+      tool_call_id: this.toolCallId,
+      tool_id: this.toolId,
+      tool_bundle_id: this.toolBundleId
     };
     return sanitized;
   }
@@ -614,7 +660,7 @@ function _extractAdditionalCredentials(token) {
   return _additionalCredsStore.get(token);
 }
 var _fetch;
-var SDK_VERSION = "0.6.0";
+var SDK_VERSION = "0.7.0";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 var HTTP_FORBIDDEN = 403;
 var HTTP_NOT_FOUND = 404;
@@ -726,6 +772,7 @@ var AlterVault = class _AlterVault {
   #actorVersion;
   #clientType;
   #framework;
+  #toolBundleId;
   constructor(options) {
     _AlterVault.#validateInitParams(
       options.apiKey,
@@ -737,13 +784,14 @@ var AlterVault = class _AlterVault {
       ["actorName", options.actorName],
       ["actorVersion", options.actorVersion],
       ["clientType", options.clientType],
-      ["framework", options.framework]
+      ["framework", options.framework],
+      ["toolBundleId", options.toolBundleId]
     ];
     for (const [name, value] of actorStrings) {
       _AlterVault.#validateActorString(value, name);
     }
     this.#hmacKey = createHmac2("sha256", options.apiKey).update("alter-signing-v1").digest();
-    this.baseUrl = (process.env.ALTER_BASE_URL ?? "https://backend.alterai.dev").replace(/\/+$/, "");
+    this.baseUrl = (process.env.ALTER_BASE_URL ?? "https://backend.alterauth.com").replace(/\/+$/, "");
     const timeoutMs = options.timeout ?? 3e4;
     this.#actorType = options.actorType;
     this.#actorIdentifier = options.actorIdentifier;
@@ -752,6 +800,7 @@ var AlterVault = class _AlterVault {
     this.#clientType = options.clientType;
     this.#userTokenGetter = options.userTokenGetter ?? null;
     this.#framework = options.framework;
+    this.#toolBundleId = options.toolBundleId;
     if (!_fetch) {
       _fetch = globalThis.fetch;
     }
@@ -799,7 +848,7 @@ var AlterVault = class _AlterVault {
     }
     if (!actorType) {
       throw new AlterSDKError(
-        "actor_type is required (use ActorType.AI_AGENT, ActorType.MCP_SERVER, or ActorType.BACKEND_SERVICE)"
+        "actor_type is required (use ActorType.AI_AGENT or ActorType.BACKEND_SERVICE)"
       );
     }
     const validValues = Object.values(ActorType);
@@ -828,7 +877,8 @@ var AlterVault = class _AlterVault {
       "X-Alter-Actor-Name": this.#actorName,
       "X-Alter-Actor-Version": this.#actorVersion,
       "X-Alter-Client-Type": this.#clientType,
-      "X-Alter-Framework": this.#framework
+      "X-Alter-Framework": this.#framework,
+      "X-Alter-Tool-Bundle-ID": this.#toolBundleId
     };
     for (const [key, value] of Object.entries(actorHeaders)) {
       if (value) {
@@ -840,21 +890,24 @@ var AlterVault = class _AlterVault {
   /**
    * Compute HMAC-SHA256 signature headers for an Alter backend request.
    *
-   * String-to-sign format: METHOD\nPATH_WITH_SORTED_QUERY\nTIMESTAMP\nCONTENT_HASH
+   * String-to-sign format: METHOD\nPATH_WITH_SORTED_QUERY\nTIMESTAMP\nNONCE\nCONTENT_HASH
    *
    * The path should include sorted query parameters if present (e.g. "/sdk/endpoint?a=1&b=2").
-   * Currently all SDK→backend calls are POSTs without query params, so the path is clean.
+   * Currently all SDK->backend calls are POSTs without query params, so the path is clean.
    */
   #computeHmacHeaders(method, path, body) {
     const timestamp = String(Math.floor(Date.now() / 1e3));
+    const nonce = randomBytes(16).toString("hex");
     const contentHash = createHash2("sha256").update(body ?? "").digest("hex");
     const stringToSign = `${method.toUpperCase()}
 ${path}
 ${timestamp}
+${nonce}
 ${contentHash}`;
     const signature = createHmac2("sha256", this.#hmacKey).update(stringToSign).digest("hex");
     return {
       "X-Alter-Timestamp": timestamp,
+      "X-Alter-Nonce": nonce,
       "X-Alter-Content-SHA256": contentHash,
       "X-Alter-Signature": signature
     };
@@ -862,7 +915,7 @@ ${contentHash}`;
   /**
    * Build per-request actor headers for instance tracking.
    */
-  #getActorRequestHeaders(runId, threadId, toolCallId) {
+  #getActorRequestHeaders(runId, threadId, toolCallId, toolId, toolBundleId) {
     const headers = {};
     if (this.#cachedActorId) {
       headers["X-Alter-Actor-ID"] = this.#cachedActorId;
@@ -892,6 +945,24 @@ ${contentHash}`;
         );
       }
     }
+    if (toolId) {
+      if (toolId.length <= MAX_TRACKING_ID_LENGTH && SAFE_HEADER_PATTERN.test(toolId)) {
+        headers["X-Alter-Tool-ID"] = toolId;
+      } else {
+        console.warn(
+          "Invalid tool_id (too long or invalid chars), skipping"
+        );
+      }
+    }
+    if (toolBundleId) {
+      if (toolBundleId.length <= MAX_TRACKING_ID_LENGTH && SAFE_HEADER_PATTERN.test(toolBundleId)) {
+        headers["X-Alter-Tool-Bundle-ID"] = toolBundleId;
+      } else {
+        console.warn(
+          "Invalid tool_bundle_id (too long or invalid chars), skipping"
+        );
+      }
+    }
     return headers;
   }
   /**
@@ -943,9 +1014,20 @@ ${contentHash}`;
     }
     return null;
   }
+  /**
+   * Parse JSON from response, unwrapping FastAPI's HTTPException envelope.
+   *
+   * FastAPI wraps `HTTPException.detail` in `{"detail": ...}`.  When the
+   * inner detail is an object we unwrap it so callers can access error
+   * fields (`error`, `message`, `details`) directly.
+   */
   static async #safeParseJson(response) {
     try {
-      return await response.clone().json();
+      const data = await response.clone().json();
+      if ("detail" in data && typeof data.detail === "object" && data.detail !== null && !Array.isArray(data.detail)) {
+        return data.detail;
+      }
+      return data;
     } catch {
       try {
         const text = await response.clone().text();
@@ -964,38 +1046,69 @@ ${contentHash}`;
     }
     if (response.status === HTTP_FORBIDDEN) {
       const errorData = await _AlterVault.#safeParseJson(response);
-      if (errorData.error === "connection_expired") {
-        throw new ConnectionExpiredError(
-          errorData.message ?? "Connection expired per TTL policy",
+      const errorCode = errorData.error;
+      if (errorCode === "grant_expired") {
+        throw new GrantExpiredError(
+          errorData.message ?? "Grant expired per TTL policy",
           errorData.details
         );
       }
+      if (errorCode === "grant_revoked") {
+        throw new GrantRevokedError(
+          errorData.message ?? "Grant has been revoked. User must re-authorize.",
+          errorData.grant_id
+        );
+      }
+      if (errorCode === "credential_revoked") {
+        throw new CredentialRevokedError(
+          errorData.message ?? "Credential has been revoked. User must re-authorize.",
+          errorData.grant_id
+        );
+      }
+      if (errorData.error === "scope_mismatch") {
+        const details = errorData.details ?? {};
+        throw new ScopeReauthRequiredError(
+          errorData.message ?? "Grant is missing required scopes",
+          details.grant_id ?? void 0,
+          details.provider_id ?? void 0,
+          response.status,
+          JSON.stringify(errorData),
+          details
+        );
+      }
       throw new PolicyViolationError(
         errorData.message ?? "Access denied by policy",
-        errorData.error,
+        errorCode,
         errorData.details
       );
     }
     if (response.status === HTTP_GONE) {
       const errorData = await _AlterVault.#safeParseJson(response);
-      throw new ConnectionDeletedError(
-        errorData.message ?? "Connection has been deleted. A new connection_id will be issued on re-authorization.",
+      throw new GrantDeletedError(
+        errorData.message ?? "Grant has been deleted. A new grant_id will be issued on re-authorization.",
         errorData
       );
     }
     if (response.status === HTTP_NOT_FOUND) {
       const errorData = await _AlterVault.#safeParseJson(response);
-      throw new ConnectionNotFoundError(
-        errorData.message ?? "OAuth connection not found for the given connection_id",
+      throw new GrantNotFoundError(
+        errorData.message ?? "OAuth grant not found for the given grant_id",
         errorData
       );
     }
     if (response.status === HTTP_BAD_REQUEST || response.status === HTTP_BAD_GATEWAY) {
       const errorData = await _AlterVault.#safeParseJson(response);
-      if (errorData.error === "connection_revoked") {
-        throw new ConnectionRevokedError(
-          errorData.message ?? "Connection has been revoked. User must re-authorize.",
-          errorData.connection_id,
+      if (errorData.error === "grant_revoked") {
+        throw new GrantRevokedError(
+          errorData.message ?? "Grant has been revoked. User must re-authorize.",
+          errorData.grant_id,
+          errorData
+        );
+      }
+      if (errorData.error === "credential_revoked") {
+        throw new CredentialRevokedError(
+          errorData.message ?? "Underlying credential has been revoked. User must re-authorize.",
+          errorData.grant_id,
           errorData
         );
       }
@@ -1045,11 +1158,13 @@ ${contentHash}`;
     }
     return token;
   }
-  async #getToken(connectionId, reason, requestMetadata, runId, threadId, toolCallId, provider, account) {
+  async #getToken(grantId, reason, requestMetadata, runId, threadId, toolCallId, toolId, provider, account, toolBundleId) {
     const actorHeaders = this.#getActorRequestHeaders(
       runId,
       threadId,
-      toolCallId
+      toolCallId,
+      toolId,
+      toolBundleId
     );
     let response;
     let tokenBody;
@@ -1066,7 +1181,7 @@ ${contentHash}`;
       }
     } else {
       tokenBody = {
-        connection_id: connectionId,
+        grant_id: grantId,
         reason: reason ?? null,
         request: requestMetadata ?? null
       };
@@ -1094,7 +1209,7 @@ ${contentHash}`;
       }
       throw new BackendError(
         `Failed to retrieve token: ${error instanceof Error ? error.message : String(error)}`,
-        { connection_id: connectionId, error: String(error) }
+        { grant_id: grantId, error: String(error) }
       );
     }
     this.#cacheActorIdFromResponse(response);
@@ -1106,13 +1221,13 @@ ${contentHash}`;
     if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(tokenResponse.injectionHeader)) {
       throw new BackendError(
         `Backend returned invalid injection_header: ${tokenResponse.injectionHeader}`,
-        { connectionId: String(connectionId) }
+        { grantId: String(grantId) }
       );
     }
     if (/[\r\n\x00]/.test(tokenResponse.injectionFormat)) {
       throw new BackendError(
         `Backend returned invalid injection_format (contains control characters)`,
-        { connectionId: String(connectionId) }
+        { grantId: String(grantId) }
       );
     }
     _storeAccessToken(tokenResponse, typedData.access_token);
@@ -1130,20 +1245,22 @@ ${contentHash}`;
   async #logApiCall(params) {
     try {
       const auditLog = new APICallAuditLog({
-        connectionId: params.connectionId,
-        providerId: params.providerId,
+        grant_id: params.grantId,
+        provider_id: 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,
+        request_headers: params.requestHeaders,
+        request_body: params.requestBody,
+        response_status: params.responseStatus,
+        response_headers: params.responseHeaders,
+        response_body: params.responseBody,
+        latency_ms: params.latencyMs,
         reason: params.reason,
-        runId: params.runId,
-        threadId: params.threadId,
-        toolCallId: params.toolCallId
+        run_id: params.runId,
+        thread_id: params.threadId,
+        tool_call_id: params.toolCallId,
+        tool_id: params.toolId,
+        tool_bundle_id: params.toolBundleId
       });
       const sanitized = auditLog.sanitize();
       const actorHeaders = this.#getActorRequestHeaders(params.runId);
@@ -1219,7 +1336,7 @@ ${contentHash}`;
    * 4. Logs the call for audit (fire-and-forget)
    * 5. Returns the raw response
    */
-  async request(connectionId, method, url, options) {
+  async request(grantId, method, url, options) {
     if (this.#closed) {
       throw new AlterSDKError(
         "SDK instance has been closed. Create a new AlterVault instance to make requests."
@@ -1227,13 +1344,13 @@ ${contentHash}`;
     }
     const provider = options?.provider;
     const account = options?.account;
-    if (!connectionId && !provider) {
-      throw new AlterSDKError("Provide connectionId or options.provider");
+    if (!grantId && !provider) {
+      throw new AlterSDKError("Provide grantId or options.provider");
     }
-    if (connectionId && provider) {
-      throw new AlterSDKError("Cannot provide both connectionId and options.provider");
+    if (grantId && provider) {
+      throw new AlterSDKError("Cannot provide both grantId and options.provider");
     }
-    const effectiveConnectionId = connectionId ?? null;
+    const effectiveGrantId = grantId ?? null;
     let currentUrl = url;
     const runId = options?.runId ?? randomUUID();
     const methodStr = String(method).toUpperCase();
@@ -1274,14 +1391,16 @@ ${contentHash}`;
       }
     }
     const { tokenResponse, scopeMismatch } = await this.#getToken(
-      effectiveConnectionId,
+      effectiveGrantId,
       options?.reason,
       { method: methodStr, url: currentUrl },
       runId,
       options?.threadId,
       options?.toolCallId,
+      options?.toolId,
       provider,
-      account
+      account,
+      options?.toolBundleId
     );
     const requestHeaders = options?.extraHeaders ? { ...options.extraHeaders } : {};
     const accessToken = _extractAccessToken(tokenResponse);
@@ -1300,7 +1419,7 @@ ${contentHash}`;
       if (!additionalCreds.secret_key) {
         throw new BackendError(
           "AWS SigV4 credential is missing secret_key in additional_credentials. Re-store the credential with both Access Key ID and Secret Access Key.",
-          { connection_id: effectiveConnectionId }
+          { grant_id: effectiveGrantId }
         );
       }
       const awsHeaders = signAwsRequest({
@@ -1367,7 +1486,7 @@ ${contentHash}`;
         throw new TimeoutError(
           `Provider API request timed out: ${error instanceof Error ? error.message : String(error)}`,
           {
-            connection_id: effectiveConnectionId,
+            grant_id: effectiveGrantId,
             method: methodStr,
             url: currentUrl
           }
@@ -1376,7 +1495,7 @@ ${contentHash}`;
       throw new NetworkError(
         `Failed to call provider API: ${error instanceof Error ? error.message : String(error)}`,
         {
-          connection_id: effectiveConnectionId,
+          grant_id: effectiveGrantId,
           method: methodStr,
           url: currentUrl,
           error: String(error)
@@ -1405,8 +1524,8 @@ ${contentHash}`;
       responseHeaders[key] = value;
     });
     this.#scheduleAuditLog({
-      connectionId: tokenResponse.connectionId,
-      providerId: tokenResponse.providerId || effectiveConnectionId || "",
+      grantId: tokenResponse.grantId,
+      providerId: tokenResponse.providerId || effectiveGrantId || "",
       method: methodStr,
       url: auditUrl,
       requestHeaders: auditHeaders,
@@ -1418,18 +1537,20 @@ ${contentHash}`;
       reason: options?.reason ?? null,
       runId,
       threadId: options?.threadId ?? null,
-      toolCallId: options?.toolCallId ?? null
+      toolCallId: options?.toolCallId ?? null,
+      toolId: options?.toolId ?? null,
+      toolBundleId: options?.toolBundleId ?? null
     });
     if (response.status >= HTTP_CLIENT_ERROR_START) {
       if (response.status === HTTP_FORBIDDEN && scopeMismatch) {
         throw new ScopeReauthRequiredError(
-          "Provider API returned 403 and the connection's scopes don't match the provider config. The user needs to re-authorize to grant updated permissions.",
-          tokenResponse.connectionId,
-          tokenResponse.providerId,
+          "Provider API returned 403 and the grant's scopes don't match the provider config. The user needs to re-authorize to grant updated permissions.",
+          tokenResponse.grantId,
+          tokenResponse.providerId ?? void 0,
           response.status,
           responseBody,
           {
-            connection_id: tokenResponse.connectionId,
+            grant_id: tokenResponse.grantId,
             provider_id: tokenResponse.providerId,
             method: methodStr,
             url: currentUrl
@@ -1441,7 +1562,7 @@ ${contentHash}`;
         response.status,
         responseBody,
         {
-          connection_id: effectiveConnectionId,
+          grant_id: effectiveGrantId,
           method: methodStr,
           url: currentUrl
         }
@@ -1450,12 +1571,12 @@ ${contentHash}`;
     return response;
   }
   /**
-   * List OAuth connections for this app.
+   * List OAuth grants for this app.
    *
-   * Returns paginated connection metadata (no tokens).
+   * Returns paginated grant metadata (no tokens).
    * Useful for discovering which services a user has connected.
    */
-  async listConnections(options) {
+  async listGrants(options) {
     if (this.#closed) {
       throw new AlterSDKError(
         "SDK instance has been closed. Create a new AlterVault instance to make requests."
@@ -1473,12 +1594,12 @@ ${contentHash}`;
         listBody.user_token = await this.#getUserToken();
       } catch (err) {
         console.warn(
-          "user_token_getter failed in listConnections, falling back to un-scoped listing:",
+          "user_token_getter failed in listGrants, falling back to un-scoped listing:",
           err instanceof Error ? err.message : String(err)
         );
       }
     }
-    const listPath = "/sdk/oauth/connections/list";
+    const listPath = "/sdk/oauth/grants/list";
     const listBodyStr = JSON.stringify(listBody);
     const listHmac = this.#computeHmacHeaders("POST", listPath, listBodyStr);
     try {
@@ -1500,19 +1621,19 @@ ${contentHash}`;
         );
       }
       throw new AlterSDKError(
-        `Failed to list connections: ${error instanceof Error ? error.message : String(error)}`
+        `Failed to list grants: ${error instanceof Error ? error.message : String(error)}`
       );
     }
     this.#cacheActorIdFromResponse(response);
     await this.#handleErrorResponse(response);
     const data = await response.json();
-    const connections = data.connections.map(
-      (c) => new ConnectionInfo(
-        c
+    const grants = data.grants.map(
+      (g) => new GrantInfo(
+        g
       )
     );
-    return new ConnectionListResult({
-      connections,
+    return new GrantListResult({
+      grants,
       total: data.total,
       limit: data.limit,
       offset: data.offset,
@@ -1538,10 +1659,10 @@ ${contentHash}`;
       allowed_origin: options.allowedOrigin ?? null,
       metadata: options.metadata ?? null
     };
-    if (options.connectionPolicy) {
-      sessionBody.connection_policy = {
-        max_ttl_seconds: options.connectionPolicy.maxTtlSeconds ?? null,
-        default_ttl_seconds: options.connectionPolicy.defaultTtlSeconds ?? null
+    if (options.grantPolicy) {
+      sessionBody.grant_policy = {
+        max_ttl_seconds: options.grantPolicy.maxTtlSeconds ?? null,
+        default_ttl_seconds: options.grantPolicy.defaultTtlSeconds ?? null
       };
     }
     if (this.#userTokenGetter) {
@@ -1608,7 +1729,7 @@ ${contentHash}`;
     const openBrowser = options.openBrowser ?? true;
     const session = await this.createConnectSession({
       allowedProviders: options.providers,
-      connectionPolicy: options.connectionPolicy
+      grantPolicy: options.grantPolicy
     });
     if (openBrowser) {
       try {
@@ -1639,14 +1760,14 @@ ${contentHash}`;
       const pollResult = await this.#pollSession(session.sessionToken);
       const pollStatus = pollResult.status;
       if (pollStatus === "completed") {
-        const connectionsData = pollResult.connections ?? [];
-        return connectionsData.map(
-          (conn) => new ConnectResult({
-            connection_id: conn.connection_id ?? "",
-            provider_id: conn.provider_id ?? "",
-            account_identifier: conn.account_identifier ?? null,
-            scopes: conn.scopes ?? [],
-            connection_policy: conn.connection_policy ?? null
+        const grantsData = pollResult.grants ?? [];
+        return grantsData.map(
+          (grant) => new ConnectResult({
+            grant_id: grant.grant_id ?? "",
+            provider_id: grant.provider_id ?? "",
+            account_identifier: grant.account_identifier ?? null,
+            scopes: grant.scopes ?? [],
+            grant_policy: grant.grant_policy ?? null
           })
         );
       }
@@ -1673,12 +1794,133 @@ ${contentHash}`;
           "Connect session expired before OAuth was completed"
         );
       }
+      if (pollStatus !== "pending") {
+        throw new ConnectFlowError(
+          `Unexpected poll status from server: ${pollStatus}`,
+          { status: pollStatus }
+        );
+      }
     }
     throw new ConnectTimeoutError(
       `OAuth flow did not complete within ${timeout} seconds. The user may not have finished authorizing in the browser.`,
       { timeout }
     );
   }
+  /**
+   * Trigger IDP login for end user via browser.
+   *
+   * Opens the app's configured IDP login page in the user's default browser.
+   * Polls for completion and returns the user's IDP JWT token.
+   *
+   * After authenticate() completes, the returned userToken is automatically
+   * used for subsequent request() calls that use identity resolution.
+   *
+   * @param options - Optional configuration (timeout in milliseconds, default 300000 = 5 min)
+   * @returns AuthResult with userToken and userInfo
+   * @throws ConnectTimeoutError if authentication times out
+   * @throws AlterSDKError if session creation or authentication fails
+   */
+  async authenticate(options) {
+    if (this.#closed) {
+      throw new AlterSDKError(
+        "SDK instance has been closed. Create a new AlterVault instance to make requests."
+      );
+    }
+    const timeoutMs = options?.timeout ?? 3e5;
+    const actorHeaders = this.#getActorRequestHeaders();
+    const sessionPath = "/sdk/auth/session";
+    const sessionBodyStr = JSON.stringify({});
+    const sessionHmac = this.#computeHmacHeaders("POST", sessionPath, sessionBodyStr);
+    let sessionResp;
+    try {
+      sessionResp = await this.#alterClient.post(sessionPath, {
+        body: sessionBodyStr,
+        headers: { ...actorHeaders, ...sessionHmac, "Content-Type": "application/json" }
+      });
+    } 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 AlterSDKError(
+        `Failed to create auth session: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    this.#cacheActorIdFromResponse(sessionResp);
+    await this.#handleErrorResponse(sessionResp);
+    const sessionData = await sessionResp.json();
+    try {
+      const openModule = await import("open");
+      const openFn = openModule.default;
+      if (openFn) {
+        await openFn(sessionData.auth_url);
+      } else {
+        console.log(
+          `Open this URL to authenticate: ${sessionData.auth_url}`
+        );
+      }
+    } catch {
+      console.log(
+        `Open this URL to authenticate: ${sessionData.auth_url}`
+      );
+    }
+    const startTime = Date.now();
+    while (true) {
+      if (Date.now() - startTime > timeoutMs) {
+        throw new ConnectTimeoutError(
+          "Authentication timed out",
+          { timeout: timeoutMs }
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, 2e3));
+      const pollPath = "/sdk/auth/poll";
+      const pollBodyStr = JSON.stringify({ session_token: sessionData.session_token });
+      const pollHmac = this.#computeHmacHeaders("POST", pollPath, pollBodyStr);
+      let pollResp;
+      try {
+        pollResp = await this.#alterClient.post(pollPath, {
+          body: pollBodyStr,
+          headers: { ...actorHeaders, ...pollHmac, "Content-Type": "application/json" }
+        });
+      } catch {
+        continue;
+      }
+      this.#cacheActorIdFromResponse(pollResp);
+      if (!pollResp.ok) {
+        continue;
+      }
+      const pollData = await pollResp.json();
+      if (pollData.status === "completed") {
+        const userToken = pollData.user_token;
+        if (!userToken) {
+          throw new AlterSDKError(
+            "Authentication completed but no user token was returned by the IDP"
+          );
+        }
+        this.#userTokenGetter = () => userToken;
+        return new AuthResult({
+          user_token: userToken,
+          user_info: pollData.user_info
+        });
+      }
+      if (pollData.status === "error") {
+        throw new AlterSDKError(
+          pollData.error_message ?? "Authentication failed"
+        );
+      }
+      if (pollData.status === "expired") {
+        throw new AlterSDKError("Authentication session expired");
+      }
+    }
+  }
   /**
    * Poll the Connect session for completion status (INTERNAL).
    *
@@ -1829,6 +2071,7 @@ export {
   ActorType,
   AlterSDKError,
   AlterVault,
+  AuthResult,
   BackendError,
   ConnectConfigError,
   ConnectDeniedError,
@@ -1836,12 +2079,13 @@ export {
   ConnectResult,
   ConnectSession,
   ConnectTimeoutError,
-  ConnectionDeletedError,
-  ConnectionExpiredError,
-  ConnectionInfo,
-  ConnectionListResult,
-  ConnectionNotFoundError,
-  ConnectionRevokedError,
+  CredentialRevokedError,
+  GrantDeletedError,
+  GrantExpiredError,
+  GrantInfo,
+  GrantListResult,
+  GrantNotFoundError,
+  GrantRevokedError,
   HttpMethod,
   NetworkError,
   PolicyViolationError,