@alter-ai/alter-sdk 0.5.0 → 0.6.0

package/README.md

@@ -13,7 +13,7 @@ Official TypeScript SDK for [Alter Vault](https://alterai.dev) -Credential manag
 - **Automatic Token Refresh**: Tokens refreshed transparently by the backend
 - **API Key and Custom Credential Support**: Handles OAuth tokens, API keys, and custom credential formats automatically
 - **Actor Tracking**: First-class support for AI agent and MCP server observability
-- **HMAC Request Signing**: All SDK-to-backend requests are signed with a derived HMAC-SHA256 key for integrity, authenticity, and replay protection
+- **HMAC Request Signing**: All SDK-to-backend requests are cryptographically signed for integrity, authenticity, and replay protection
 - **Native Promises**: Built on native `fetch` -no heavy dependencies
 
 ## Installation
@@ -37,7 +37,7 @@ const vault = new AlterVault({
 const response = await vault.request(
   "CONNECTION_ID",  // from Alter Connect (see below)
   HttpMethod.GET,
-  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "https://api.example.com/v1/resource",
   {
     queryParams: { maxResults: "10" },
   },
@@ -66,7 +66,7 @@ await vault.close();
 // You can also discover connectionIds programmatically:
 const result = await vault.listConnections({ providerId: "google" });
 for (const conn of result.connections) {
-  console.log(`${conn.id}: ${conn.accountDisplayName}`);
+  console.log(`${conn.connectionId}: ${conn.accountDisplayName}`);
 }
 ```
 
@@ -80,7 +80,7 @@ The `request()` method returns the raw `Response` object. The token is injected
 const response = await vault.request(
   connectionId,
   HttpMethod.GET,
-  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "https://api.example.com/v1/resource",
 );
 ```
 
@@ -221,7 +221,7 @@ for (const result of results) {
 const response = await vault.request(
   results[0].connectionId,
   HttpMethod.GET,
-  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "https://api.example.com/v1/resource",
 );
 ```
 
@@ -254,7 +254,7 @@ const vault = new AlterVault({
 const response = await vault.request(
   connectionId,
   HttpMethod.GET,
-  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "https://api.example.com/v1/resource",
   {
     runId: "550e8400-e29b-41d4-a716-446655440000",  // auto-generated UUID if omitted
     threadId: "thread-xyz",
@@ -289,12 +289,12 @@ const calendarAgent = new AlterVault({
 await emailAgent.request(
   gmailConnectionId,  // from Alter Connect
   HttpMethod.GET,
-  "https://gmail.googleapis.com/gmail/v1/users/me/messages",
+  "https://api.example.com/v1/messages",
 );
 await calendarAgent.request(
   calendarConnectionId,  // from Alter Connect
   HttpMethod.GET,
-  "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+  "https://api.example.com/v1/resource",
 );
 
 // Clean up each instance
@@ -370,7 +370,7 @@ try {
   const response = await vault.request(
     connectionId,
     HttpMethod.GET,
-    "https://www.googleapis.com/calendar/v3/calendars/primary/events",
+    "https://api.example.com/v1/resource",
   );
 } catch (error) {
   // --- Connection unusable — user must re-authorize via Alter Connect ---
@@ -390,7 +390,7 @@ try {
 
   // --- Policy restrictions — may resolve on its own ---
   } else if (error instanceof PolicyViolationError) {
-    // Business hours, IP allowlist, or other Cerbos policy denial
+    // Business hours, IP allowlist, or other policy denial
     console.error(`Policy denied: ${error.message} (reason: ${error.policyError})`);
 
   // --- Transient / infrastructure errors — safe to retry ---
@@ -404,6 +404,8 @@ try {
     // Create a new Connect session so the user can grant updated scopes
   } else if (error instanceof ProviderAPIError) {
     console.error(`Provider error ${error.statusCode}: ${error.responseBody}`);
+  } else {
+    throw error;
   }
 }
 ```

package/dist/index.cjs

@@ -270,7 +270,8 @@ var TokenResponse = class _TokenResponse {
       expires_in: this.expiresIn,
       expires_at: this.expiresAt?.toISOString() ?? null,
       scopes: this.scopes,
-      connection_id: this.connectionId
+      connection_id: this.connectionId,
+      provider_id: this.providerId
     };
   }
   /**
@@ -287,7 +288,7 @@ var TokenResponse = class _TokenResponse {
   }
 };
 var ConnectionInfo = class {
-  id;
+  connectionId;
   providerId;
   scopes;
   accountIdentifier;
@@ -298,7 +299,7 @@ var ConnectionInfo = class {
   createdAt;
   lastUsedAt;
   constructor(data) {
-    this.id = data.id;
+    this.connectionId = data.connection_id;
     this.providerId = data.provider_id;
     this.scopes = data.scopes ?? [];
     this.accountIdentifier = data.account_identifier ?? null;
@@ -312,7 +313,7 @@ var ConnectionInfo = class {
   }
   toJSON() {
     return {
-      id: this.id,
+      connection_id: this.connectionId,
       provider_id: this.providerId,
       scopes: this.scopes,
       account_identifier: this.accountIdentifier,
@@ -325,7 +326,7 @@ var ConnectionInfo = class {
     };
   }
   toString() {
-    return `ConnectionInfo(id=${this.id}, provider=${this.providerId}, status=${this.status})`;
+    return `ConnectionInfo(connection_id=${this.connectionId}, provider=${this.providerId}, status=${this.status})`;
   }
 };
 var ConnectSession = class {
@@ -378,7 +379,17 @@ var ConnectResult = class {
     this.providerId = data.provider_id;
     this.accountIdentifier = data.account_identifier ?? null;
     this.scopes = data.scopes ?? [];
-    this.connectionPolicy = data.connection_policy ?? null;
+    const rawPolicy = data.connection_policy;
+    if (rawPolicy) {
+      const raw = rawPolicy;
+      this.connectionPolicy = 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;
+    }
     Object.freeze(this);
   }
   toJSON() {
@@ -387,7 +398,11 @@ var ConnectResult = class {
       provider_id: this.providerId,
       account_identifier: this.accountIdentifier,
       scopes: this.scopes,
-      connection_policy: this.connectionPolicy
+      connection_policy: this.connectionPolicy ? {
+        expires_at: this.connectionPolicy.expiresAt ?? null,
+        created_by: this.connectionPolicy.createdBy ?? null,
+        created_at: this.connectionPolicy.createdAt ?? null
+      } : null
     };
   }
   toString() {
@@ -401,7 +416,8 @@ var SENSITIVE_HEADERS = /* @__PURE__ */ new Set([
   "x-api-key",
   "x-auth-token",
   "x-amz-date",
-  "x-amz-content-sha256"
+  "x-amz-content-sha256",
+  "x-amz-security-token"
 ]);
 var APICallAuditLog = class {
   connectionId;
@@ -480,6 +496,7 @@ var import_node_crypto = require("crypto");
 var ALGORITHM = "AWS4-HMAC-SHA256";
 var AWS_HOST_RE = /^(?<service>[a-z0-9-]+)\.(?<region>[a-z]{2}(?:-[a-z0-9]+)+-\d+)\.amazonaws\.com$/;
 var S3_VIRTUAL_HOST_RE = /^[^.]+\.s3\.(?<region>[a-z]{2}(?:-[a-z0-9]+)+-\d+)\.amazonaws\.com$/;
+var VPCE_HOST_RE = /^vpce-[a-z0-9-]+\.(?<service>[a-z0-9-]+)\.(?<region>[a-z]{2}(?:-[a-z0-9]+)+-\d+)\.vpce\.amazonaws\.com$/;
 function hmacSha256(key, message) {
   return (0, import_node_crypto.createHmac)("sha256", key).update(message, "utf8").digest();
 }
@@ -502,6 +519,10 @@ function detectServiceAndRegion(hostname) {
   if (s3m?.groups) {
     return { service: "s3", region: s3m.groups.region };
   }
+  const vpcem = VPCE_HOST_RE.exec(lower);
+  if (vpcem?.groups) {
+    return { service: vpcem.groups.service, region: vpcem.groups.region };
+  }
   return { service: null, region: null };
 }
 function deriveSigningKey(secretKey, dateStamp, region, service) {
@@ -536,18 +557,21 @@ function canonicalQueryString(query) {
       ]);
     }
   }
-  sorted.sort((a, b) => {
+  const sigv4Encode = (s) => encodeURIComponent(s).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+  const encoded = sorted.map(
+    ([k, v]) => [sigv4Encode(k), sigv4Encode(v)]
+  );
+  encoded.sort((a, b) => {
     if (a[0] < b[0]) return -1;
     if (a[0] > b[0]) return 1;
     if (a[1] < b[1]) return -1;
     if (a[1] > b[1]) return 1;
     return 0;
   });
-  const sigv4Encode = (s) => encodeURIComponent(s).replace(
-    /[!'()*]/g,
-    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
-  );
-  return sorted.map(([k, v]) => `${sigv4Encode(k)}=${sigv4Encode(v)}`).join("&");
+  return encoded.map(([k, v]) => `${k}=${v}`).join("&");
 }
 function canonicalHeadersAndSigned(headers) {
   const canonical = {};
@@ -566,11 +590,9 @@ function signAwsRequest(opts) {
   const parsed = new URL(opts.url);
   const hostname = parsed.hostname;
   let { region, service } = opts;
-  if (region == null || service == null) {
-    const detected = detectServiceAndRegion(hostname);
-    if (region == null) region = detected.region;
-    if (service == null) service = detected.service;
-  }
+  const detected = detectServiceAndRegion(hostname);
+  if (detected.region != null) region = detected.region;
+  if (detected.service != null) service = detected.service;
   if (!region) {
     throw new Error(
       `Cannot determine AWS region from URL '${opts.url}'. Pass region explicitly via additional_credentials.`
@@ -653,7 +675,7 @@ function _extractAdditionalCredentials(token) {
   return _additionalCredsStore.get(token);
 }
 var _fetch;
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.6.0";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 var HTTP_FORBIDDEN = 403;
 var HTTP_NOT_FOUND = 404;

package/dist/index.d.cts

@@ -109,7 +109,7 @@ declare class TokenResponse {
  * Returned by listConnections(). Contains metadata only — no tokens.
  */
 declare class ConnectionInfo {
-    readonly id: string;
+    readonly connectionId: string;
     readonly providerId: string;
     readonly scopes: string[];
     readonly accountIdentifier: string | null;
@@ -120,7 +120,7 @@ declare class ConnectionInfo {
     readonly createdAt: string;
     readonly lastUsedAt: string | null;
     constructor(data: {
-        id: string;
+        connection_id: string;
         provider_id: string;
         scopes?: string[];
         account_identifier?: string | null;
@@ -185,11 +185,11 @@ declare class ConnectionListResult {
  */
 interface ConnectionPolicy {
     /** Hard expiry timestamp (ISO 8601 UTC) */
-    expires_at?: string | null;
+    readonly expiresAt?: string | null;
     /** Who set the policy: 'developer' or 'end_user' */
-    created_by?: string | null;
+    readonly createdBy?: string | null;
     /** When the policy was set (ISO 8601 UTC) */
-    created_at?: string | null;
+    readonly createdAt?: string | null;
 }
 declare class ConnectResult {
     readonly connectionId: string;
@@ -767,4 +767,4 @@ declare class TimeoutError extends NetworkError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
-export { APICallAuditLog, ActorType, AlterSDKError, AlterVault, type AlterVaultOptions, BackendError, ConnectConfigError, ConnectDeniedError, ConnectFlowError, type ConnectOptions, ConnectResult, ConnectSession, ConnectTimeoutError, ConnectionDeletedError, ConnectionExpiredError, ConnectionInfo, ConnectionListResult, ConnectionNotFoundError, ConnectionRevokedError, type CreateConnectSessionOptions, HttpMethod, type ListConnectionsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, ReAuthRequiredError, type RequestOptions, ScopeReauthRequiredError, TimeoutError, TokenResponse };
+export { APICallAuditLog, ActorType, AlterSDKError, AlterVault, type AlterVaultOptions, BackendError, ConnectConfigError, ConnectDeniedError, ConnectFlowError, type ConnectOptions, ConnectResult, ConnectSession, ConnectTimeoutError, ConnectionDeletedError, ConnectionExpiredError, ConnectionInfo, ConnectionListResult, ConnectionNotFoundError, type ConnectionPolicy, ConnectionRevokedError, type CreateConnectSessionOptions, HttpMethod, type ListConnectionsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, ReAuthRequiredError, type RequestOptions, ScopeReauthRequiredError, TimeoutError, TokenResponse };

package/dist/index.d.ts

@@ -109,7 +109,7 @@ declare class TokenResponse {
  * Returned by listConnections(). Contains metadata only — no tokens.
  */
 declare class ConnectionInfo {
-    readonly id: string;
+    readonly connectionId: string;
     readonly providerId: string;
     readonly scopes: string[];
     readonly accountIdentifier: string | null;
@@ -120,7 +120,7 @@ declare class ConnectionInfo {
     readonly createdAt: string;
     readonly lastUsedAt: string | null;
     constructor(data: {
-        id: string;
+        connection_id: string;
         provider_id: string;
         scopes?: string[];
         account_identifier?: string | null;
@@ -185,11 +185,11 @@ declare class ConnectionListResult {
  */
 interface ConnectionPolicy {
     /** Hard expiry timestamp (ISO 8601 UTC) */
-    expires_at?: string | null;
+    readonly expiresAt?: string | null;
     /** Who set the policy: 'developer' or 'end_user' */
-    created_by?: string | null;
+    readonly createdBy?: string | null;
     /** When the policy was set (ISO 8601 UTC) */
-    created_at?: string | null;
+    readonly createdAt?: string | null;
 }
 declare class ConnectResult {
     readonly connectionId: string;
@@ -767,4 +767,4 @@ declare class TimeoutError extends NetworkError {
     constructor(message: string, details?: Record<string, unknown>);
 }
 
-export { APICallAuditLog, ActorType, AlterSDKError, AlterVault, type AlterVaultOptions, BackendError, ConnectConfigError, ConnectDeniedError, ConnectFlowError, type ConnectOptions, ConnectResult, ConnectSession, ConnectTimeoutError, ConnectionDeletedError, ConnectionExpiredError, ConnectionInfo, ConnectionListResult, ConnectionNotFoundError, ConnectionRevokedError, type CreateConnectSessionOptions, HttpMethod, type ListConnectionsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, ReAuthRequiredError, type RequestOptions, ScopeReauthRequiredError, TimeoutError, TokenResponse };
+export { APICallAuditLog, ActorType, AlterSDKError, AlterVault, type AlterVaultOptions, BackendError, ConnectConfigError, ConnectDeniedError, ConnectFlowError, type ConnectOptions, ConnectResult, ConnectSession, ConnectTimeoutError, ConnectionDeletedError, ConnectionExpiredError, ConnectionInfo, ConnectionListResult, ConnectionNotFoundError, type ConnectionPolicy, ConnectionRevokedError, type CreateConnectSessionOptions, HttpMethod, type ListConnectionsOptions, NetworkError, PolicyViolationError, Provider, ProviderAPIError, ReAuthRequiredError, type RequestOptions, ScopeReauthRequiredError, TimeoutError, TokenResponse };

package/dist/index.js

@@ -209,7 +209,8 @@ var TokenResponse = class _TokenResponse {
       expires_in: this.expiresIn,
       expires_at: this.expiresAt?.toISOString() ?? null,
       scopes: this.scopes,
-      connection_id: this.connectionId
+      connection_id: this.connectionId,
+      provider_id: this.providerId
     };
   }
   /**
@@ -226,7 +227,7 @@ var TokenResponse = class _TokenResponse {
   }
 };
 var ConnectionInfo = class {
-  id;
+  connectionId;
   providerId;
   scopes;
   accountIdentifier;
@@ -237,7 +238,7 @@ var ConnectionInfo = class {
   createdAt;
   lastUsedAt;
   constructor(data) {
-    this.id = data.id;
+    this.connectionId = data.connection_id;
     this.providerId = data.provider_id;
     this.scopes = data.scopes ?? [];
     this.accountIdentifier = data.account_identifier ?? null;
@@ -251,7 +252,7 @@ var ConnectionInfo = class {
   }
   toJSON() {
     return {
-      id: this.id,
+      connection_id: this.connectionId,
       provider_id: this.providerId,
       scopes: this.scopes,
       account_identifier: this.accountIdentifier,
@@ -264,7 +265,7 @@ var ConnectionInfo = class {
     };
   }
   toString() {
-    return `ConnectionInfo(id=${this.id}, provider=${this.providerId}, status=${this.status})`;
+    return `ConnectionInfo(connection_id=${this.connectionId}, provider=${this.providerId}, status=${this.status})`;
   }
 };
 var ConnectSession = class {
@@ -317,7 +318,17 @@ var ConnectResult = class {
     this.providerId = data.provider_id;
     this.accountIdentifier = data.account_identifier ?? null;
     this.scopes = data.scopes ?? [];
-    this.connectionPolicy = data.connection_policy ?? null;
+    const rawPolicy = data.connection_policy;
+    if (rawPolicy) {
+      const raw = rawPolicy;
+      this.connectionPolicy = 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;
+    }
     Object.freeze(this);
   }
   toJSON() {
@@ -326,7 +337,11 @@ var ConnectResult = class {
       provider_id: this.providerId,
       account_identifier: this.accountIdentifier,
       scopes: this.scopes,
-      connection_policy: this.connectionPolicy
+      connection_policy: this.connectionPolicy ? {
+        expires_at: this.connectionPolicy.expiresAt ?? null,
+        created_by: this.connectionPolicy.createdBy ?? null,
+        created_at: this.connectionPolicy.createdAt ?? null
+      } : null
     };
   }
   toString() {
@@ -340,7 +355,8 @@ var SENSITIVE_HEADERS = /* @__PURE__ */ new Set([
   "x-api-key",
   "x-auth-token",
   "x-amz-date",
-  "x-amz-content-sha256"
+  "x-amz-content-sha256",
+  "x-amz-security-token"
 ]);
 var APICallAuditLog = class {
   connectionId;
@@ -419,6 +435,7 @@ import { createHash, createHmac } from "crypto";
 var ALGORITHM = "AWS4-HMAC-SHA256";
 var AWS_HOST_RE = /^(?<service>[a-z0-9-]+)\.(?<region>[a-z]{2}(?:-[a-z0-9]+)+-\d+)\.amazonaws\.com$/;
 var S3_VIRTUAL_HOST_RE = /^[^.]+\.s3\.(?<region>[a-z]{2}(?:-[a-z0-9]+)+-\d+)\.amazonaws\.com$/;
+var VPCE_HOST_RE = /^vpce-[a-z0-9-]+\.(?<service>[a-z0-9-]+)\.(?<region>[a-z]{2}(?:-[a-z0-9]+)+-\d+)\.vpce\.amazonaws\.com$/;
 function hmacSha256(key, message) {
   return createHmac("sha256", key).update(message, "utf8").digest();
 }
@@ -441,6 +458,10 @@ function detectServiceAndRegion(hostname) {
   if (s3m?.groups) {
     return { service: "s3", region: s3m.groups.region };
   }
+  const vpcem = VPCE_HOST_RE.exec(lower);
+  if (vpcem?.groups) {
+    return { service: vpcem.groups.service, region: vpcem.groups.region };
+  }
   return { service: null, region: null };
 }
 function deriveSigningKey(secretKey, dateStamp, region, service) {
@@ -475,18 +496,21 @@ function canonicalQueryString(query) {
       ]);
     }
   }
-  sorted.sort((a, b) => {
+  const sigv4Encode = (s) => encodeURIComponent(s).replace(
+    /[!'()*]/g,
+    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
+  );
+  const encoded = sorted.map(
+    ([k, v]) => [sigv4Encode(k), sigv4Encode(v)]
+  );
+  encoded.sort((a, b) => {
     if (a[0] < b[0]) return -1;
     if (a[0] > b[0]) return 1;
     if (a[1] < b[1]) return -1;
     if (a[1] > b[1]) return 1;
     return 0;
   });
-  const sigv4Encode = (s) => encodeURIComponent(s).replace(
-    /[!'()*]/g,
-    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`
-  );
-  return sorted.map(([k, v]) => `${sigv4Encode(k)}=${sigv4Encode(v)}`).join("&");
+  return encoded.map(([k, v]) => `${k}=${v}`).join("&");
 }
 function canonicalHeadersAndSigned(headers) {
   const canonical = {};
@@ -505,11 +529,9 @@ function signAwsRequest(opts) {
   const parsed = new URL(opts.url);
   const hostname = parsed.hostname;
   let { region, service } = opts;
-  if (region == null || service == null) {
-    const detected = detectServiceAndRegion(hostname);
-    if (region == null) region = detected.region;
-    if (service == null) service = detected.service;
-  }
+  const detected = detectServiceAndRegion(hostname);
+  if (detected.region != null) region = detected.region;
+  if (detected.service != null) service = detected.service;
   if (!region) {
     throw new Error(
       `Cannot determine AWS region from URL '${opts.url}'. Pass region explicitly via additional_credentials.`
@@ -592,7 +614,7 @@ function _extractAdditionalCredentials(token) {
   return _additionalCredsStore.get(token);
 }
 var _fetch;
-var SDK_VERSION = "0.5.0";
+var SDK_VERSION = "0.6.0";
 var SDK_USER_AGENT = `alter-sdk-node/${SDK_VERSION}`;
 var HTTP_FORBIDDEN = 403;
 var HTTP_NOT_FOUND = 404;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alter-ai/alter-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Official TypeScript SDK for Alter Vault — OAuth token management with policy enforcement",
   "type": "module",
   "main": "dist/index.cjs",