spaps-sdk 1.12.0 → 1.13.0

package/dist/index.js

@@ -203,6 +203,7 @@ __export(index_exports, {
   RoleHierarchy: () => RoleHierarchy,
   SPAPS: () => SPAPSClient,
   SPAPSClient: () => SPAPSClient,
+  SPAPSSDKError: () => SPAPSSDKError,
   TokenManager: () => TokenManager,
   WalletUtils: () => WalletUtils,
   WebSocketAuthHelper: () => WebSocketAuthHelper,
@@ -557,6 +558,148 @@ var X402PaymentRequiredSDKError = class extends Error {
     this.response = response;
   }
 };
+var SPAPSSDKError = class extends Error {
+  code;
+  status;
+  statusCode;
+  details;
+  requestId;
+  request_id;
+  diagnostics;
+  remediations;
+  constructor(options) {
+    super(options.message);
+    this.name = "SPAPSSDKError";
+    this.code = options.code;
+    this.status = options.status;
+    this.statusCode = options.status;
+    this.details = options.details;
+    this.requestId = options.requestId;
+    this.request_id = options.requestId;
+    this.diagnostics = options.diagnostics || [];
+    this.remediations = options.remediations || [];
+  }
+};
+function isObjectRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function toOptionalString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function toOptionalNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return void 0;
+}
+function extractResponseHeader(headers, name) {
+  if (!headers || typeof headers !== "object") return void 0;
+  const getter = headers.get;
+  if (typeof getter === "function") {
+    return toOptionalString(getter.call(headers, name));
+  }
+  const normalized = name.toLowerCase();
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() === normalized) {
+      return Array.isArray(value) ? toOptionalString(value[0]) : toOptionalString(value);
+    }
+  }
+  return void 0;
+}
+function extractRequestId(payload, fallback) {
+  if (!isObjectRecord(payload)) return fallback;
+  const metadata = isObjectRecord(payload.metadata) ? payload.metadata : {};
+  return toOptionalString(payload.request_id) || toOptionalString(metadata.request_id) || fallback;
+}
+function normalizeDiagnostics(payload, fallbackCode, fallbackMessage, status) {
+  const raw = isObjectRecord(payload) ? payload.diagnostics : void 0;
+  const diagnostics = [];
+  if (Array.isArray(raw)) {
+    for (const item of raw) {
+      if (!isObjectRecord(item)) continue;
+      const code = toOptionalString(item.code) || fallbackCode || "request_failed";
+      const message = toOptionalString(item.message) || fallbackMessage;
+      diagnostics.push({
+        code,
+        message,
+        status: toOptionalNumber(item.status) ?? status ?? null,
+        ...item.details !== void 0 ? { details: item.details } : {}
+      });
+    }
+  }
+  if (diagnostics.length > 0) {
+    return diagnostics;
+  }
+  if (fallbackCode || status !== void 0) {
+    return [
+      {
+        code: fallbackCode || `http_${status}`,
+        message: fallbackMessage,
+        status: status ?? null
+      }
+    ];
+  }
+  return [];
+}
+function normalizeRemediations(payload) {
+  const raw = isObjectRecord(payload) ? payload.remediations : void 0;
+  if (!Array.isArray(raw)) return [];
+  const remediations = [];
+  for (const item of raw) {
+    if (!isObjectRecord(item)) continue;
+    const kind = toOptionalString(item.kind);
+    if (!kind) continue;
+    remediations.push({
+      kind,
+      ...item.label === null || typeof item.label === "string" ? { label: item.label } : {},
+      ...item.method === null || typeof item.method === "string" ? { method: item.method } : {},
+      ...item.path === null || typeof item.path === "string" ? { path: item.path } : {},
+      ...item.cli === null || typeof item.cli === "string" ? { cli: item.cli } : {},
+      ...Array.isArray(item.requires) ? { requires: item.requires.filter((value) => typeof value === "string") } : {},
+      ...item.details !== void 0 ? { details: item.details } : {},
+      ...item.command_template === null || typeof item.command_template === "string" ? { command_template: item.command_template } : {},
+      ...item.safe_to_execute === null || typeof item.safe_to_execute === "boolean" ? { safe_to_execute: item.safe_to_execute } : {},
+      ...item.operator_gate_required === null || typeof item.operator_gate_required === "boolean" ? { operator_gate_required: item.operator_gate_required } : {}
+    });
+  }
+  return remediations;
+}
+function buildSPAPSSDKError(payload, fallback, status, requestId) {
+  const record = isObjectRecord(payload) ? payload : {};
+  const error = isObjectRecord(record.error) ? record.error : {};
+  const code = toOptionalString(error.code);
+  const message = toOptionalString(error.message) || fallback || "SPAPS request failed";
+  return new SPAPSSDKError({
+    message,
+    code,
+    status,
+    details: error.details,
+    requestId: extractRequestId(record, requestId),
+    diagnostics: normalizeDiagnostics(record, code, message, status),
+    remediations: normalizeRemediations(record)
+  });
+}
+function buildSPAPSSDKErrorFromAxios(error) {
+  const status = error.response?.status;
+  const requestId = extractResponseHeader(error.response?.headers, "x-request-id");
+  if (error.response) {
+    return buildSPAPSSDKError(
+      error.response.data,
+      error.message || "SPAPS request failed",
+      status,
+      requestId
+    );
+  }
+  return new SPAPSSDKError({
+    message: error.message || "SPAPS request failed",
+    code: error.code,
+    status,
+    requestId,
+    diagnostics: normalizeDiagnostics(void 0, error.code, error.message, status)
+  });
+}
 var SPAPSClient = class _SPAPSClient {
   client;
   apiKey;
@@ -568,10 +711,19 @@ var SPAPSClient = class _SPAPSClient {
     if (!response) {
       throw new Error(fallback);
     }
-    const payload = this.isAxiosResponse(response) ? response.data : this.isResponseLikeWithData(response) ? response.data : response;
+    const axiosResponse = this.isAxiosResponse(response) ? response : void 0;
+    if (axiosResponse?.status === 204) {
+      return void 0;
+    }
+    const payload = axiosResponse ? axiosResponse.data : this.isResponseLikeWithData(response) ? response.data : response;
     if (this.isApiResponse(payload)) {
       if (payload.success === false) {
-        throw new Error(payload.error?.message || fallback);
+        throw buildSPAPSSDKError(
+          payload,
+          fallback,
+          axiosResponse?.status,
+          extractResponseHeader(axiosResponse?.headers, "x-request-id")
+        );
       }
       if (payload.data !== void 0) {
         return payload.data;
@@ -598,6 +750,19 @@ var SPAPSClient = class _SPAPSClient {
     }
     return userId;
   }
+  requireAccessToken(message = "Authentication required. Please authenticate first.") {
+    if (!this.accessToken) {
+      throw new Error(message);
+    }
+    return this.accessToken;
+  }
+  authConfig(message) {
+    return {
+      headers: {
+        Authorization: `Bearer ${this.requireAccessToken(message)}`
+      }
+    };
+  }
   isAxiosResponse(value) {
     if (!value || typeof value !== "object") {
       return false;
@@ -617,6 +782,41 @@ var SPAPSClient = class _SPAPSClient {
     const record = value;
     return "success" in record && typeof record.success === "boolean";
   }
+  static isMfaRequiredAuthResponse(value) {
+    return Boolean(value && typeof value === "object" && value.mfa_required === true);
+  }
+  normalizeAuthPayload(payload) {
+    if (_SPAPSClient.isMfaRequiredAuthResponse(payload)) {
+      return payload;
+    }
+    if (payload?.tokens && payload?.user) {
+      return {
+        access_token: payload.tokens.access_token,
+        refresh_token: payload.tokens.refresh_token,
+        expires_in: payload.tokens.expires_in,
+        token_type: payload.token_type || "Bearer",
+        user: payload.user
+      };
+    }
+    return payload;
+  }
+  storeAuthTokens(result) {
+    if (_SPAPSClient.isMfaRequiredAuthResponse(result)) {
+      return;
+    }
+    if (result.access_token) {
+      this.accessToken = result.access_token;
+    }
+    if (result.refresh_token) {
+      this.refreshToken = result.refresh_token;
+    }
+  }
+  unwrapAuthMethodResponse(response, fallback) {
+    const payload = this.unwrapApiResponse(response, fallback);
+    const result = this.normalizeAuthPayload(payload);
+    this.storeAuthTokens(result);
+    return result;
+  }
   static isSdkManagedHeader(name) {
     const normalized = name.toLowerCase();
     return normalized === "authorization" || normalized === "x-api-key";
@@ -1046,6 +1246,203 @@ var SPAPSClient = class _SPAPSClient {
       return this.unwrapApiResponse(res, "Failed to get app link");
     }
   };
+  /**
+   * Application email whitelist helpers.
+   *
+   * `check` is API-key scoped. Mutations and admin reads require an
+   * authenticated admin JWT plus the configured API key.
+   */
+  whitelist = {
+    check: async (email) => {
+      const q = new URLSearchParams({ email });
+      const res = await this.client.get(`/api/v1/whitelist/check?${q.toString()}`);
+      return this.unwrapApiResponse(res, "Failed to check whitelist");
+    },
+    add: async (payload) => {
+      const res = await this.client.post(
+        "/api/v1/whitelist",
+        payload,
+        this.authConfig("Access token is required for whitelist admin operations")
+      );
+      return this.unwrapApiResponse(res, "Failed to add whitelist entry");
+    },
+    bulkAdd: async (payload) => {
+      const res = await this.client.post(
+        "/api/v1/whitelist/bulk",
+        payload,
+        this.authConfig("Access token is required for whitelist admin operations")
+      );
+      return this.unwrapApiResponse(res, "Failed to bulk add whitelist entries");
+    },
+    list: async (params = {}) => {
+      const q = new URLSearchParams();
+      if (params.limit !== void 0) q.set("limit", String(params.limit));
+      if (params.offset !== void 0) q.set("offset", String(params.offset));
+      if (params.tier) q.set("tier", params.tier);
+      const qs = q.toString();
+      const res = await this.client.get(
+        `/api/v1/whitelist${qs ? `?${qs}` : ""}`,
+        this.authConfig("Access token is required for whitelist admin operations")
+      );
+      return this.unwrapApiResponse(res, "Failed to list whitelist entries");
+    },
+    update: async (email, payload) => {
+      const res = await this.client.put(
+        `/api/v1/whitelist/${encodeURIComponent(email)}`,
+        payload,
+        this.authConfig("Access token is required for whitelist admin operations")
+      );
+      return this.unwrapApiResponse(res, "Failed to update whitelist entry");
+    },
+    stats: async () => {
+      const res = await this.client.get(
+        "/api/v1/whitelist/stats",
+        this.authConfig("Access token is required for whitelist admin operations")
+      );
+      return this.unwrapApiResponse(res, "Failed to get whitelist stats");
+    },
+    clear: async () => {
+      const res = await this.client.delete(
+        "/api/v1/whitelist/all",
+        this.authConfig("Access token is required for whitelist admin operations")
+      );
+      return this.unwrapApiResponse(res, "Failed to clear whitelist");
+    },
+    remove: async (email) => {
+      const res = await this.client.delete(
+        `/api/v1/whitelist/${encodeURIComponent(email)}`,
+        this.authConfig("Access token is required for whitelist admin operations")
+      );
+      return this.unwrapApiResponse(res, "Failed to remove whitelist entry");
+    }
+  };
+  /**
+   * User lookup and app membership administration helpers.
+   */
+  users = {
+    getEmailsBatch: async (userIds) => {
+      const res = await this.client.post("/api/users/emails", { user_ids: userIds });
+      return this.unwrapApiResponse(res, "Failed to get user emails");
+    },
+    getUsersBatch: async (userIds) => {
+      const res = await this.client.post("/api/users/batch", { user_ids: userIds });
+      return this.unwrapApiResponse(res, "Failed to get users");
+    },
+    memberships: {
+      list: async (params = {}) => {
+        const q = new URLSearchParams();
+        if (params.status) q.set("status", params.status);
+        if (params.limit !== void 0) q.set("limit", String(params.limit));
+        if (params.offset !== void 0) q.set("offset", String(params.offset));
+        if (params.cursor) q.set("cursor", params.cursor);
+        const qs = q.toString();
+        const res = await this.client.get(
+          `/api/users/memberships${qs ? `?${qs}` : ""}`,
+          this.authConfig("Access token is required for membership admin operations")
+        );
+        return this.unwrapApiResponse(res, "Failed to list memberships");
+      },
+      add: async (payload) => {
+        if (!payload.user_id && !payload.email) {
+          throw new Error("Either user_id or email is required");
+        }
+        const res = await this.client.post(
+          "/api/users/memberships",
+          payload,
+          this.authConfig("Access token is required for membership admin operations")
+        );
+        return this.unwrapApiResponse(res, "Failed to add membership");
+      },
+      remove: async (userId) => {
+        const res = await this.client.delete(
+          `/api/users/memberships/${encodeURIComponent(userId)}`,
+          this.authConfig("Access token is required for membership admin operations")
+        );
+        return this.unwrapApiResponse(res, "Failed to remove membership");
+      },
+      deleteAccount: async (userId, params = {}) => {
+        const config = {
+          ...this.authConfig("Access token is required for user account deletion"),
+          params
+        };
+        const res = await this.client.delete(
+          `/api/users/${encodeURIComponent(userId)}`,
+          config
+        );
+        return this.unwrapApiResponse(
+          res,
+          "Failed to delete user account"
+        );
+      }
+    }
+  };
+  /**
+   * Trusted-service support telemetry helpers.
+   *
+   * These endpoints require a secret API key. Case lifecycle patching also
+   * requires a super-admin JWT.
+   */
+  supportTelemetry = {
+    ingestEvent: async (payload) => {
+      const res = await this.client.post("/api/v1/support-telemetry/events", payload);
+      return this.unwrapApiResponse(
+        res,
+        "Failed to ingest support telemetry event"
+      );
+    },
+    listCases: async (params = {}) => {
+      const q = new URLSearchParams();
+      if (params.application_id) q.set("application_id", params.application_id);
+      if (params.status) q.set("status", params.status);
+      if (params.priority) q.set("priority", params.priority);
+      if (params.severity_gte) q.set("severity_gte", params.severity_gte);
+      if (params.assigned_to_user_id) q.set("assigned_to_user_id", params.assigned_to_user_id);
+      if (params.limit !== void 0) q.set("limit", String(params.limit));
+      if (params.offset !== void 0) q.set("offset", String(params.offset));
+      const qs = q.toString();
+      const res = await this.client.get(`/api/v1/support-telemetry/cases${qs ? `?${qs}` : ""}`);
+      return this.unwrapApiResponse(
+        res,
+        "Failed to list support telemetry cases"
+      );
+    },
+    getCase: async (caseId, params = {}) => {
+      const q = new URLSearchParams();
+      if (params.event_limit !== void 0) q.set("event_limit", String(params.event_limit));
+      if (params.event_offset !== void 0) q.set("event_offset", String(params.event_offset));
+      const qs = q.toString();
+      const res = await this.client.get(
+        `/api/v1/support-telemetry/cases/${encodeURIComponent(caseId)}${qs ? `?${qs}` : ""}`
+      );
+      return this.unwrapApiResponse(
+        res,
+        "Failed to get support telemetry case"
+      );
+    },
+    patchCase: async (caseId, payload) => {
+      const res = await this.client.patch(
+        `/api/v1/support-telemetry/cases/${encodeURIComponent(caseId)}`,
+        payload,
+        this.authConfig("Access token is required for support telemetry case updates")
+      );
+      return this.unwrapApiResponse(
+        res,
+        "Failed to patch support telemetry case"
+      );
+    },
+    getCaseByExternalRef: async (externalCaseRef, params = {}) => {
+      const q = new URLSearchParams();
+      if (params.application_id) q.set("application_id", params.application_id);
+      const qs = q.toString();
+      const res = await this.client.get(
+        `/api/v1/support-telemetry/cases/by-external/${encodeURIComponent(externalCaseRef)}${qs ? `?${qs}` : ""}`
+      );
+      return this.unwrapApiResponse(
+        res,
+        "Failed to get support telemetry case by external ref"
+      );
+    }
+  };
   /**
    * Marketing events and experiment results.
    *
@@ -1164,7 +1561,7 @@ var SPAPSClient = class _SPAPSClient {
             this.refreshToken = void 0;
           }
         }
-        return Promise.reject(error);
+        return Promise.reject(buildSPAPSSDKErrorFromAxios(error));
       }
     );
   }
@@ -1179,6 +1576,9 @@ var SPAPSClient = class _SPAPSClient {
       const res = await this.client.request(config);
       return { success: true, data: res.data };
     } catch (err) {
+      if (err instanceof SPAPSSDKError) {
+        return Promise.reject(err);
+      }
       const message = err?.response?.data?.error?.message || err?.message || "Request failed";
       return Promise.reject(new Error(message));
     }
@@ -1238,8 +1638,20 @@ var SPAPSClient = class _SPAPSClient {
   async getUser() {
     return this.client.get("/api/auth/user");
   }
+  async getSessionContext() {
+    const res = await this.client.get("/api/auth/session-context", this.authConfig());
+    return this.unwrapApiResponse(res, "Failed to get session context");
+  }
   // -------- Facade namespaces (compat with previous SDK shape) --------
   auth = {
+    getMethods: async () => {
+      const res = await this.client.get("/api/auth/methods");
+      return this.unwrapApiResponse(res, "Auth method discovery failed");
+    },
+    getSessionContext: async () => {
+      const res = await this.client.get("/api/auth/session-context", this.authConfig());
+      return this.unwrapApiResponse(res, "Failed to get session context");
+    },
     /**
      * Verify magic link token without mutating token state.
      * Returns a simple success object from the API.
@@ -1252,12 +1664,7 @@ var SPAPSClient = class _SPAPSClient {
     },
     signInWithWallet: async (req) => {
       const res = await this.client.post("/api/auth/wallet-sign-in", req);
-      const body = res.data;
-      if (body?.success === false) throw new Error(body?.error?.message || "Wallet sign-in failed");
-      const data = body?.data ?? body;
-      this.accessToken = data.access_token;
-      this.refreshToken = data.refresh_token;
-      return data;
+      return this.unwrapAuthMethodResponse(res, "Wallet sign-in failed");
     },
     authenticateWallet: async (walletAddress, signFn, chainType, username) => {
       const nonce = await this.auth.getNonce(walletAddress);
@@ -1266,12 +1673,11 @@ var SPAPSClient = class _SPAPSClient {
     },
     signInWithPassword: async (payload) => {
       const res = await this.client.post("/api/auth/login", payload);
-      const body = res.data;
-      if (body?.success === false) throw new Error(body?.error?.message || "Login failed");
-      const data = body?.data ?? body;
-      this.accessToken = data.access_token;
-      this.refreshToken = data.refresh_token;
-      return data;
+      return this.unwrapAuthMethodResponse(res, "Login failed");
+    },
+    login: async (payload) => {
+      const res = await this.client.post("/api/auth/login", payload);
+      return this.unwrapAuthMethodResponse(res, "Login failed");
     },
     requestMagicLink: async (payload) => {
       await this.client.post("/api/auth/magic-link", payload);
@@ -1293,6 +1699,20 @@ var SPAPSClient = class _SPAPSClient {
       if (body?.success === false) throw new Error(body?.error?.message || "Set password failed");
       return { message: body?.message || "Password updated successfully" };
     },
+    deleteCurrentAccount: async (payload) => {
+      const config = {
+        ...this.authConfig("Access token is required to delete the current account"),
+        data: payload
+      };
+      const res = await this.client.delete("/api/auth/me", config);
+      const result = this.unwrapApiResponse(
+        res,
+        "Failed to delete current account"
+      );
+      this.accessToken = void 0;
+      this.refreshToken = void 0;
+      return result;
+    },
     register: async (payload) => {
       const res = await this.client.post("/api/auth/register", payload);
       const body = res.data;
@@ -1309,18 +1729,71 @@ var SPAPSClient = class _SPAPSClient {
     verifyMagicLink: async (payload) => {
       const res = await this.client.post("/api/auth/verify-magic-link", {
         token: payload.token,
-        type: payload.type || "magiclink"
+        type: payload.type || "magiclink",
+        ...payload.state ? { state: payload.state } : {}
       });
-      const body = res.data;
-      if (body?.success === false) throw new Error(body?.error?.message || "Magic link verification failed");
-      const data = {
-        access_token: body.tokens?.access_token || body.access_token,
-        refresh_token: body.tokens?.refresh_token || body.refresh_token,
-        user: body.user
-      };
-      this.accessToken = data.access_token;
-      this.refreshToken = data.refresh_token;
-      return data;
+      return this.unwrapAuthMethodResponse(res, "Magic link verification failed");
+    },
+    oidc: {
+      getNonce: async () => {
+        const res = await this.client.post("/api/auth/oidc/nonce");
+        return this.unwrapApiResponse(res, "OIDC nonce request failed");
+      },
+      signIn: async (payload) => {
+        const res = await this.client.post("/api/auth/oidc/sign-in", payload);
+        return this.unwrapAuthMethodResponse(res, "OIDC sign-in failed");
+      }
+    },
+    webauthn: {
+      registerOptions: async () => {
+        const res = await this.client.post("/api/auth/webauthn/register/options");
+        return this.unwrapApiResponse(res, "WebAuthn registration options failed");
+      },
+      registerVerify: async (payload) => {
+        const res = await this.client.post("/api/auth/webauthn/register/verify", payload);
+        return this.unwrapApiResponse(
+          res,
+          "WebAuthn registration verification failed"
+        );
+      },
+      assertionOptions: async (payload) => {
+        const res = await this.client.post("/api/auth/webauthn/assertion/options", payload ?? {});
+        return this.unwrapApiResponse(res, "WebAuthn assertion options failed");
+      },
+      assertionVerify: async (payload) => {
+        const res = await this.client.post("/api/auth/webauthn/assertion/verify", payload);
+        return this.unwrapAuthMethodResponse(res, "WebAuthn assertion verification failed");
+      }
+    },
+    mfa: {
+      totp: {
+        enroll: async () => {
+          const res = await this.client.post("/api/auth/mfa/totp/enroll");
+          return this.unwrapApiResponse(res, "MFA TOTP enrollment failed");
+        },
+        activate: async (payload) => {
+          const res = await this.client.post("/api/auth/mfa/totp/activate", payload);
+          return this.unwrapApiResponse(res, "MFA TOTP activation failed");
+        },
+        disable: async (payload) => {
+          const res = await this.client.post("/api/auth/mfa/totp/disable", payload);
+          return this.unwrapApiResponse(res, "MFA TOTP disable failed");
+        }
+      },
+      verify: async (payload) => {
+        const res = await this.client.post("/api/auth/mfa/verify", payload);
+        return this.unwrapAuthMethodResponse(res, "MFA verification failed");
+      }
+    },
+    sms: {
+      request: async (payload) => {
+        const res = await this.client.post("/api/auth/sms/request", payload);
+        return this.unwrapApiResponse(res, "SMS OTP request failed");
+      },
+      verify: async (payload) => {
+        const res = await this.client.post("/api/auth/sms/verify", payload);
+        return this.unwrapAuthMethodResponse(res, "SMS OTP verification failed");
+      }
     },
     solana: {
       linkWallet: async (payload) => {
@@ -1952,6 +2425,92 @@ var SPAPSClient = class _SPAPSClient {
       return this.unwrapApiResponse(res, "Failed to list usage history");
     }
   };
+  /**
+   * Agent-oriented access decisions and action preparation.
+   *
+   * `check` intentionally resolves for denied decisions; inspect
+   * `allowed`, `outcome`, and `next_actions` to decide what to do next.
+   */
+  access = {
+    check: async (payload) => {
+      const res = await this.client.post("/api/access/decide", payload);
+      return this.unwrapApiResponse(res, "Failed to check access");
+    },
+    decide: async (payload) => {
+      const res = await this.client.post("/api/access/decide", payload);
+      return this.unwrapApiResponse(res, "Failed to decide access");
+    },
+    prepareAction: async (payload) => {
+      const res = await this.client.post("/api/actions/prepare", payload);
+      return this.unwrapApiResponse(res, "Failed to prepare action");
+    },
+    getDecision: async (decisionTraceId) => {
+      const res = await this.client.get(`/api/access/decisions/${encodeURIComponent(decisionTraceId)}`);
+      return this.unwrapApiResponse(res, "Failed to get access decision");
+    },
+    explain: async (decisionTraceId) => {
+      const res = await this.client.get(`/api/graph/explain/${encodeURIComponent(decisionTraceId)}`);
+      return this.unwrapApiResponse(res, "Failed to explain access decision");
+    }
+  };
+  /**
+   * Capability graph inspection helpers. These require a secret key.
+   */
+  graph = {
+    listNodes: async (query = {}) => {
+      const params = new URLSearchParams();
+      if (query.node_type) params.set("node_type", query.node_type);
+      if (query.status) params.set("status", query.status);
+      if (query.q) params.set("q", query.q);
+      if (query.cursor) params.set("cursor", query.cursor);
+      if (query.limit !== void 0) params.set("limit", String(query.limit));
+      if (query.application_id) params.set("application_id", query.application_id);
+      const suffix = params.toString() ? `?${params.toString()}` : "";
+      const res = await this.client.get(`/api/graph/nodes${suffix}`);
+      return this.unwrapApiResponse(res, "Failed to list capability graph nodes");
+    },
+    getPaths: async (query) => {
+      const params = new URLSearchParams();
+      params.set("from_node_key", query.from_node_key);
+      params.set("to_node_key", query.to_node_key);
+      if (query.max_depth !== void 0) params.set("max_depth", String(query.max_depth));
+      if (query.limit !== void 0) params.set("limit", String(query.limit));
+      if (query.include_stale !== void 0) params.set("include_stale", String(query.include_stale));
+      if (query.application_id) params.set("application_id", query.application_id);
+      const res = await this.client.get(`/api/graph/paths?${params.toString()}`);
+      return this.unwrapApiResponse(res, "Failed to get capability graph paths");
+    },
+    getImpact: async (query) => {
+      const params = new URLSearchParams();
+      params.set("node_key", query.node_key);
+      if (query.max_depth !== void 0) params.set("max_depth", String(query.max_depth));
+      if (query.limit !== void 0) params.set("limit", String(query.limit));
+      if (query.include_stale !== void 0) params.set("include_stale", String(query.include_stale));
+      if (query.application_id) params.set("application_id", query.application_id);
+      const res = await this.client.get(`/api/graph/impact?${params.toString()}`);
+      return this.unwrapApiResponse(res, "Failed to get capability graph impact");
+    },
+    explain: async (decisionTraceId) => {
+      return this.access.explain(decisionTraceId);
+    },
+    refresh: async (correlationId, applicationId) => {
+      const params = new URLSearchParams();
+      if (correlationId) params.set("correlation_id", correlationId);
+      if (applicationId) params.set("application_id", applicationId);
+      const suffix = params.toString() ? `?${params.toString()}` : "";
+      const res = await this.client.post(`/api/graph/refresh${suffix}`);
+      return this.unwrapApiResponse(res, "Failed to refresh capability graph");
+    }
+  };
+  /**
+   * Machine-readable capability graph contract for agents and SDK adapters.
+   */
+  contract = {
+    get: async () => {
+      const res = await this.client.get("/api/contract");
+      return this.unwrapApiResponse(res, "Failed to get capability graph contract");
+    }
+  };
   // Stripe Methods
   async createCheckoutSession(priceId, successUrl, cancelUrl) {
     return this.client.post("/api/stripe/checkout-sessions", {
@@ -2088,11 +2647,12 @@ var SPAPSClient = class _SPAPSClient {
     if (!this.accessToken) {
       throw new Error("Authentication required. Please authenticate first.");
     }
-    return this.client.delete(`/api/stripe/products/${productId}`, {
+    const res = await this.client.delete(`/api/stripe/products/${productId}`, {
       headers: {
         "Authorization": `Bearer ${this.accessToken}`
       }
     });
+    return this.unwrapApiResponse(res, "Failed to archive product");
   }
   /**
    * Create a new price for a product (Admin required)
@@ -2404,8 +2964,7 @@ function isErrorEnvelope(value) {
 function unwrapEnvelope(value, fallbackMessage) {
   if (!isEnvelope(value)) return value;
   if (value.success === false) {
-    const message = isErrorEnvelope(value) ? value.error.message : void 0;
-    throw new Error(message || fallbackMessage || "SPAPS request failed");
+    throw buildSPAPSSDKError(value, fallbackMessage || "SPAPS request failed");
   }
   return value.data;
 }
@@ -2453,6 +3012,7 @@ function detectKeyType(key) {
   RoleHierarchy,
   SPAPS,
   SPAPSClient,
+  SPAPSSDKError,
   TokenManager,
   WalletUtils,
   WebSocketAuthHelper,