spaps-sdk 1.6.8 → 1.7.0

package/dist/index.mjs

@@ -190,6 +190,10 @@ var init_permissions = __esm({
 init_permissions();
 import crypto from "crypto";
 import axios from "axios";
+import {
+  isX402PaymentRequired,
+  isX402ResourceStatus
+} from "spaps-types";
 import {
   createSecureMessageRequestSchema,
   secureMessageSchema,
@@ -480,12 +484,23 @@ function appendSupportedIssueReportScope(q, scope) {
   }
   q.append("scope", scope);
 }
-var SPAPSClient = class {
+var X402PaymentRequiredSDKError = class extends Error {
+  paymentRequiredHeader;
+  response;
+  constructor(paymentRequiredHeader, response) {
+    super("x402 payment required");
+    this.name = "X402PaymentRequiredSDKError";
+    this.paymentRequiredHeader = paymentRequiredHeader;
+    this.response = response;
+  }
+};
+var SPAPSClient = class _SPAPSClient {
   client;
   apiKey;
   accessToken;
   refreshToken;
   _isLocalMode = false;
+  headerProvider;
   unwrapApiResponse(response, fallback) {
     if (!response) {
       throw new Error(fallback);
@@ -502,6 +517,13 @@ var SPAPSClient = class {
     }
     return payload;
   }
+  skillEvalMutationConfig(options) {
+    const ifMatch = options?.ifMatch ?? options?.caseVersion;
+    if (ifMatch === void 0 || ifMatch === null || ifMatch === "") {
+      return void 0;
+    }
+    return { headers: { "If-Match": String(ifMatch) } };
+  }
   isAxiosResponse(value) {
     if (!value || typeof value !== "object") {
       return false;
@@ -521,6 +543,41 @@ var SPAPSClient = class {
     const record = value;
     return "success" in record && typeof record.success === "boolean";
   }
+  static isSdkManagedHeader(name) {
+    const normalized = name.toLowerCase();
+    return normalized === "authorization" || normalized === "x-api-key";
+  }
+  static hasHeader(headers, name) {
+    if (!headers) return false;
+    if (typeof headers.has === "function") {
+      return headers.has(name);
+    }
+    const normalized = name.toLowerCase();
+    return Object.keys(headers).some((key) => key.toLowerCase() === normalized);
+  }
+  static setHeader(headers, name, value) {
+    if (typeof headers.set === "function") {
+      headers.set(name, value);
+      return;
+    }
+    headers[name] = value;
+  }
+  static assertSafeHeaderValue(name, value) {
+    if (typeof value === "string" && /[\r\n]/.test(value)) {
+      throw new Error(`Invalid header value for ${name}: control characters not allowed`);
+    }
+  }
+  applyCustomHeaders(headers) {
+    const customHeaders = this.headerProvider?.();
+    if (!customHeaders) return;
+    for (const [key, value] of Object.entries(customHeaders)) {
+      if (_SPAPSClient.isSdkManagedHeader(key) || _SPAPSClient.hasHeader(headers, key)) {
+        continue;
+      }
+      _SPAPSClient.assertSafeHeaderValue(key, value);
+      _SPAPSClient.setHeader(headers, key, value);
+    }
+  }
   // Admin namespace for cleaner API
   admin = {
     createProduct: (productData) => this.createProduct(productData),
@@ -695,8 +752,43 @@ var SPAPSClient = class {
       return this.unwrapApiResponse(res, "Failed to reply to issue report");
     }
   };
+  /**
+   * Application-scoped short links for browser apps that need stable public URLs.
+   */
+  appLinks = {
+    /**
+     * Create a short link owned by the authenticated user.
+     */
+    create: async (payload) => {
+      const res = await this.client.post(
+        "/api/v1/app-links",
+        payload,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      return this.unwrapApiResponse(res, "Failed to create app link");
+    },
+    /**
+     * Resolve a public short link for the active application.
+     */
+    get: async (username, slug, options) => {
+      const q = new URLSearchParams();
+      if (options?.track) q.set("track", "true");
+      const qs = q.toString();
+      const res = await this.client.get(
+        `/api/v1/app-links/${encodeURIComponent(username)}/${encodeURIComponent(slug)}${qs ? `?${qs}` : ""}`,
+        this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0
+      );
+      return this.unwrapApiResponse(res, "Failed to get app link");
+    }
+  };
+  static envVar(name) {
+    if (typeof process !== "undefined" && process.env) {
+      return process.env[name];
+    }
+    return void 0;
+  }
   constructor(config = {}) {
-    const apiUrl = config.apiUrl || process.env.SPAPS_API_URL || process.env.NEXT_PUBLIC_SPAPS_API_URL;
+    const apiUrl = config.apiUrl || _SPAPSClient.envVar("SPAPS_API_URL") || _SPAPSClient.envVar("NEXT_PUBLIC_SPAPS_API_URL");
     const isBrowser = typeof window !== "undefined";
     let effectiveApiKey;
     if (config.publishableKey) {
@@ -709,7 +801,7 @@ var SPAPSClient = class {
     } else if (config.apiKey) {
       effectiveApiKey = config.apiKey;
     } else {
-      effectiveApiKey = process.env.SPAPS_API_KEY || process.env.NEXT_PUBLIC_SPAPS_API_KEY;
+      effectiveApiKey = _SPAPSClient.envVar("SPAPS_API_KEY") || _SPAPSClient.envVar("NEXT_PUBLIC_SPAPS_API_KEY");
     }
     if (!apiUrl || apiUrl.includes("localhost") || apiUrl.includes("127.0.0.1")) {
       this._isLocalMode = true;
@@ -718,6 +810,7 @@ var SPAPSClient = class {
     if (!this.apiKey && !this._isLocalMode) {
       console.warn("\u26A0\uFE0F SPAPS: No API key provided. Some features may not work.");
     }
+    this.headerProvider = config.headerProvider;
     this.client = axios.create({
       baseURL: apiUrl || "http://localhost:3301",
       timeout: config.timeout || 1e4,
@@ -727,11 +820,13 @@ var SPAPSClient = class {
       }
     });
     this.client.interceptors.request.use((config2) => {
-      if (this.apiKey && !config2.headers["X-API-Key"]) {
-        config2.headers["X-API-Key"] = this.apiKey;
+      config2.headers = config2.headers || {};
+      this.applyCustomHeaders(config2.headers);
+      if (this.apiKey && !_SPAPSClient.hasHeader(config2.headers, "X-API-Key")) {
+        _SPAPSClient.setHeader(config2.headers, "X-API-Key", this.apiKey);
       }
-      if (this.accessToken && !config2.headers.Authorization) {
-        config2.headers.Authorization = `Bearer ${this.accessToken}`;
+      if (this.accessToken && !_SPAPSClient.hasHeader(config2.headers, "Authorization")) {
+        _SPAPSClient.setHeader(config2.headers, "Authorization", `Bearer ${this.accessToken}`);
       }
       return config2;
     });
@@ -1033,6 +1128,7 @@ var SPAPSClient = class {
       reconcile: async (options = {}) => {
         const headers = {};
         if (options.reconToken) {
+          _SPAPSClient.assertSafeHeaderValue("X-Recon-Token", options.reconToken);
           headers["X-Recon-Token"] = options.reconToken;
         }
         const payload = {};
@@ -1258,6 +1354,176 @@ var SPAPSClient = class {
       return this.unwrapApiResponse(res, "Failed to disconnect");
     }
   };
+  /**
+   * x402 paid-resource namespace.
+   * Handles resource status checks, payment-gated actions, receipts, and handoff authorization.
+   */
+  x402 = {
+    getResourceStatus: async (resourceKey) => {
+      const res = await this.client.get(
+        `/api/x402/resources/${encodeURIComponent(resourceKey)}/status`
+      );
+      return this.unwrapApiResponse(res, "Failed to get x402 resource status");
+    },
+    executeAction: async (resourceKey, actionKey, options) => {
+      const headers = {};
+      if (this.accessToken) {
+        headers["Authorization"] = `Bearer ${this.accessToken}`;
+      }
+      if (options?.paymentSignature) {
+        headers["PAYMENT-SIGNATURE"] = options.paymentSignature;
+      }
+      const body = {};
+      if (options?.target) body.target = options.target;
+      const bridgeToken = options?.bridgeToken ?? options?.bridge_token;
+      if (bridgeToken !== void 0) body.bridge_token = bridgeToken;
+      const res = await this.client.post(
+        `/api/x402/resources/${encodeURIComponent(resourceKey)}/actions/${encodeURIComponent(actionKey)}`,
+        body,
+        { headers, validateStatus: (s) => s < 500 }
+      );
+      const paymentRequiredHeader = res.headers?.["payment-required"] || res.headers?.["PAYMENT-REQUIRED"] || "";
+      if (res.status === 402 && paymentRequiredHeader) {
+        throw new X402PaymentRequiredSDKError(
+          paymentRequiredHeader,
+          res.data
+        );
+      }
+      return this.unwrapApiResponse(res, "Failed to execute x402 action");
+    },
+    getReceipt: async (receiptId) => {
+      const res = await this.client.get(`/api/x402/receipts/${encodeURIComponent(receiptId)}`);
+      return this.unwrapApiResponse(res, "Failed to get x402 receipt");
+    },
+    listReceipts: async (params) => {
+      const q = new URLSearchParams();
+      if (params?.resourceKey) q.append("resource_key", params.resourceKey);
+      if (params?.limit !== void 0) q.append("limit", String(params.limit));
+      if (params?.offset !== void 0) q.append("offset", String(params.offset));
+      const qs = q.toString();
+      const res = await this.client.get(`/api/x402/receipts${qs ? `?${qs}` : ""}`);
+      return this.unwrapApiResponse(res, "Failed to list x402 receipts");
+    },
+    verifyHandoff: async (token, target, bridgeToken, options) => {
+      const body = {
+        token,
+        resource_key: options.resourceKey,
+        action_key: options.actionKey,
+        target,
+        bridge_token: bridgeToken
+      };
+      const res = await this.client.post("/api/x402/handoff/verify", body);
+      return this.unwrapApiResponse(res, "Failed to verify x402 handoff");
+    }
+  };
+  /**
+   * Blind comparative skill-eval namespace.
+   */
+  skillEvals = {
+    createCase: async (payload, options) => {
+      const headers = {};
+      if (this.accessToken) {
+        headers["Authorization"] = `Bearer ${this.accessToken}`;
+      }
+      if (options?.paymentSignature) {
+        headers["PAYMENT-SIGNATURE"] = options.paymentSignature;
+      }
+      const res = await this.client.post("/api/skill-evals/cases", payload, {
+        headers,
+        validateStatus: (s) => s < 500
+      });
+      const paymentRequiredHeader = res.headers?.["payment-required"] || res.headers?.["PAYMENT-REQUIRED"] || "";
+      if (res.status === 402 && paymentRequiredHeader) {
+        throw new X402PaymentRequiredSDKError(paymentRequiredHeader, res.data);
+      }
+      return this.unwrapApiResponse(
+        res,
+        "Failed to create skill eval case"
+      );
+    },
+    getCase: async (caseId) => {
+      const res = await this.client.get(
+        `/api/skill-evals/cases/${encodeURIComponent(caseId)}`
+      );
+      return this.unwrapApiResponse(res, "Failed to get skill eval case");
+    },
+    getReviewRoom: async (caseId) => {
+      const res = await this.client.get(
+        `/api/skill-evals/cases/${encodeURIComponent(caseId)}/room`
+      );
+      return this.unwrapApiResponse(res, "Failed to get skill eval room");
+    },
+    submitReview: async (caseId, payload, options) => {
+      const config = this.skillEvalMutationConfig(options);
+      const res = await this.client.post(
+        `/api/skill-evals/cases/${encodeURIComponent(caseId)}/reviews`,
+        payload,
+        ...config ? [config] : []
+      );
+      return this.unwrapApiResponse(
+        res,
+        "Failed to submit skill eval review"
+      );
+    },
+    respondToReview: async (caseId, reviewId, payload, options) => {
+      const config = this.skillEvalMutationConfig(options);
+      const res = await this.client.post(
+        `/api/skill-evals/cases/${encodeURIComponent(caseId)}/reviews/${encodeURIComponent(reviewId)}/response`,
+        payload,
+        ...config ? [config] : []
+      );
+      return this.unwrapApiResponse(
+        res,
+        "Failed to respond to skill eval review"
+      );
+    },
+    lockReviews: async (caseId, options) => {
+      const config = this.skillEvalMutationConfig(options);
+      const res = await this.client.post(
+        `/api/skill-evals/cases/${encodeURIComponent(caseId)}/lock`,
+        {},
+        ...config ? [config] : []
+      );
+      return this.unwrapApiResponse(
+        res,
+        "Failed to lock skill eval reviews"
+      );
+    },
+    revealEvidence: async (caseId, payload, options) => {
+      const config = this.skillEvalMutationConfig(options);
+      const res = await this.client.post(
+        `/api/skill-evals/cases/${encodeURIComponent(caseId)}/reveal`,
+        payload,
+        ...config ? [config] : []
+      );
+      return this.unwrapApiResponse(
+        res,
+        "Failed to reveal skill eval evidence"
+      );
+    },
+    createGovernanceSnapshot: async (caseId, payload, options) => {
+      const config = this.skillEvalMutationConfig(options);
+      const res = await this.client.post(
+        `/api/skill-evals/cases/${encodeURIComponent(caseId)}/governance-snapshots`,
+        payload,
+        ...config ? [config] : []
+      );
+      return this.unwrapApiResponse(
+        res,
+        "Failed to create skill eval governance snapshot"
+      );
+    },
+    importGovernanceOutcome: async (snapshotId, payload) => {
+      const res = await this.client.post(
+        `/api/skill-evals/governance-snapshots/${encodeURIComponent(snapshotId)}/outcome`,
+        payload
+      );
+      return this.unwrapApiResponse(
+        res,
+        "Failed to import skill eval governance outcome"
+      );
+    }
+  };
   /**
    * DayRate (Dynamic Scheduling) namespace
    * For booking half-day sessions with dynamic pricing
@@ -1286,6 +1552,21 @@ var SPAPSClient = class {
     createMultiBooking: async (payload) => {
       const res = await this.client.post("/api/dayrate/book-multi", payload);
       return this.unwrapApiResponse(res, "Failed to create multi-booking");
+    },
+    /**
+     * Create a single-slot booking hold backed by an x402 paid-resource action.
+     */
+    createX402Booking: async (payload) => {
+      const res = await this.client.post("/api/dayrate/book-x402", payload);
+      return this.unwrapApiResponse(res, "Failed to create x402 booking");
+    },
+    /**
+     * Get guest-safe checkout confirmation state for a Stripe session.
+     */
+    getCheckoutStatus: async (sessionId) => {
+      const query = new URLSearchParams({ sessionId }).toString();
+      const res = await this.client.get(`/api/dayrate/checkout-status?${query}`);
+      return this.unwrapApiResponse(res, "Failed to get checkout status");
     }
   };
   // Stripe Methods
@@ -1574,13 +1855,24 @@ var TokenManager = class _TokenManager {
       s.removeItem(_TokenManager.USER_KEY);
     }
   }
+  static decodePayload(token) {
+    try {
+      const parts = token.split(".");
+      if (parts.length !== 3 || !parts[1]) return null;
+      const decoded = JSON.parse(_TokenManager.base64Decode(parts[1]));
+      if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) return null;
+      return decoded;
+    } catch {
+      return null;
+    }
+  }
   static isTokenExpired(token) {
     try {
       const parts = token.split(".");
       if (parts.length !== 3 || !parts[1]) return true;
       const payload = JSON.parse(_TokenManager.base64Decode(parts[1]));
       const now = Math.floor(Date.now() / 1e3);
-      return payload.exp < now;
+      return typeof payload?.exp !== "number" || payload.exp < now;
     } catch {
       return true;
     }
@@ -1695,6 +1987,39 @@ var WalletUtils = class _WalletUtils {
     }
   }
 };
+function isEnvelope(value) {
+  if (!value || typeof value !== "object") return false;
+  const r = value;
+  return "success" in r && typeof r.success === "boolean";
+}
+function isSuccessEnvelope(value) {
+  return isEnvelope(value) && value.success === true;
+}
+function isErrorEnvelope(value) {
+  if (!isEnvelope(value) || value.success !== false) return false;
+  const error = value.error;
+  if (!error || typeof error !== "object") return false;
+  const r = error;
+  return typeof r.code === "string" && typeof r.message === "string";
+}
+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");
+  }
+  return value.data;
+}
+function unwrapNestedData(value) {
+  if (isEnvelope(value) && value.success !== false) {
+    const inner = value.data;
+    if (inner && typeof inner === "object" && "data" in inner) {
+      return inner.data;
+    }
+    return inner;
+  }
+  return value;
+}
 function createBrowserClient(publishableKey, options) {
   if (!publishableKey.startsWith("spaps_pub_")) {
     console.warn("\u26A0\uFE0F SPAPS: Expected a publishable key (spaps_pub_xxx). Using a secret key in browser is not recommended.");
@@ -1728,6 +2053,7 @@ export {
   TokenManager,
   WalletUtils,
   WebSocketAuthHelper,
+  X402PaymentRequiredSDKError,
   canAccessAdmin,
   createBrowserClient,
   createPermissionChecker,
@@ -1741,7 +2067,14 @@ export {
   getUserRole,
   hasPermission,
   isAdminAccount,
+  isEnvelope,
+  isErrorEnvelope,
+  isSuccessEnvelope,
+  isX402PaymentRequired,
+  isX402ResourceStatus,
   secureMessageMetadataSchema,
   secureMessageSchema,
+  unwrapEnvelope,
+  unwrapNestedData,
   verifyCryptoWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps-sdk",
-  "version": "1.6.8",
+  "version": "1.7.0",
   "description": "Sweet Potato Authentication & Payment Service SDK - Zero-config client with built-in permission checking, role-based access control, and dayrate scheduling",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,6 +20,7 @@
     "build": "tsup --tsconfig tsconfig.json src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup --tsconfig tsconfig.json src/index.ts --format cjs,esm --dts --watch",
     "test": "vitest run",
+    "test:cov": "vitest run --coverage --coverage.reporter=lcov --coverage.reporter=text",
     "test:readme": "vitest run test/readme-snippets.test.ts",
     "typecheck:readme": "tsc -p tsconfig.readme.json --noEmit",
     "smoke-test": "npm run build && node smoke-test.js",
@@ -54,6 +55,7 @@
   },
   "devDependencies": {
     "@types/node": "^20.10.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "tsup": "^8.0.1",
     "typescript": "^5.3.2",
     "vitest": "^4.0.18"