spaps-sdk 1.1.51 → 1.2.0

package/README.md

@@ -189,14 +189,21 @@ const user = await spaps.getUser();
 
 ### 💳 Stripe Integration
 ```javascript
-// Create checkout session
-const session = await spaps.createCheckoutSession(priceId, successUrl);
-window.location.href = session.data.url;
+// Create checkout session with consent control
+const session = await spaps.payments.createPaymentCheckout({
+  price_id: 'price_123',
+  success_url: 'https://app.example.com/success',
+  cancel_url: 'https://app.example.com/cancel',
+  require_legal_consent: true,
+  legal_consent_text: 'I agree I am 18+ and accept the HTMA Terms & Privacy.'
+});
+window.location.href = session.url;
 
 // Manage subscription
 const subscription = await spaps.getSubscription();
 await spaps.cancelSubscription();
 ```
+> `require_legal_consent` forces Stripe’s Terms/Privacy checkbox, and `legal_consent_text` (≤120 chars) customizes the copy. Text is sanitized and defaults to “I agree to the Terms of Service and Privacy Policy.” when omitted.
 
 ### 📊 Usage Tracking
 ```javascript

package/dist/index.d.mts

@@ -85,12 +85,53 @@ declare class PermissionChecker {
 declare function createPermissionChecker(customAdmins?: (string | AdminConfig)[]): PermissionChecker;
 declare const defaultPermissionChecker: PermissionChecker;
 
+type ApiKeyType = 'publishable' | 'secret';
 interface SPAPSConfig {
     apiUrl?: string;
+    /** @deprecated Use publishableKey or secretKey instead */
     apiKey?: string;
+    /** Browser-safe key for client-side usage (spaps_pub_xxx) */
+    publishableKey?: string;
+    /** Server-only key for full access (spaps_sec_xxx) */
+    secretKey?: string;
     autoDetect?: boolean;
     timeout?: number;
 }
+interface CheckoutLineItemPriceData {
+    currency: string;
+    unit_amount: number;
+    product_data: {
+        name: string;
+        description?: string;
+        metadata?: Record<string, string>;
+    };
+}
+interface CheckoutLineItem {
+    price_id?: string;
+    product_id?: string;
+    quantity: number;
+    price_data?: CheckoutLineItemPriceData;
+}
+interface CreateCheckoutSessionPayload {
+    mode: 'payment' | 'subscription';
+    line_items: CheckoutLineItem[];
+    success_url: string;
+    cancel_url: string;
+    metadata?: Record<string, string>;
+    customer_email?: string;
+    client_reference_id?: string;
+    payment_intent_data?: {
+        metadata?: Record<string, string>;
+    };
+    subscription_data?: {
+        metadata?: Record<string, string>;
+        trial_period_days?: number;
+    };
+    allow_promotion_codes?: boolean;
+    locale?: string;
+    require_legal_consent?: boolean;
+    legal_consent_text?: string;
+}
 
 declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Record<string, any>> {
     private client;
@@ -269,18 +310,22 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
                 cursor?: Record<string, unknown>;
             }>;
         };
-        createCheckoutSession: (payload: any) => Promise<CheckoutSession>;
+        createCheckoutSession: (payload: CreateCheckoutSessionPayload) => Promise<CheckoutSession>;
         createPaymentCheckout: (params: {
             price_id: string;
             quantity?: number;
             success_url: string;
             cancel_url: string;
+            require_legal_consent?: boolean;
+            legal_consent_text?: string;
         }) => Promise<CheckoutSession>;
         createSubscriptionCheckout: (params: {
             price_id: string;
             success_url: string;
             cancel_url: string;
             trial_period_days?: number;
+            require_legal_consent?: boolean;
+            legal_consent_text?: string;
         }) => Promise<CheckoutSession>;
         getCheckoutSession: (sessionId: string) => Promise<CheckoutSession>;
         listCheckoutSessions: (query?: {
@@ -446,5 +491,39 @@ declare class WalletUtils {
     static detectChainType(address: string): 'solana' | 'ethereum' | 'bitcoin' | null;
     static isValidAddress(address: string, chainType?: 'solana' | 'ethereum' | 'bitcoin' | 'base'): boolean;
 }
+/**
+ * Create a SPAPS client for browser/client-side usage
+ * Uses publishable key which is safe to expose in client bundles
+ *
+ * @example
+ * ```typescript
+ * // In your frontend code
+ * const spaps = createBrowserClient('spaps_pub_xxx');
+ *
+ * // Use for authentication and checkout
+ * const { user } = await spaps.auth.signInWithPassword({ email, password });
+ * const checkout = await spaps.payments.createCheckoutSession({...});
+ * ```
+ */
+declare function createBrowserClient(publishableKey: string, options?: Omit<SPAPSConfig, 'publishableKey' | 'secretKey' | 'apiKey'>): SPAPSClient;
+/**
+ * Create a SPAPS client for server-side usage
+ * Uses secret key which provides full access to all endpoints
+ *
+ * @example
+ * ```typescript
+ * // In your API routes (Next.js, Express, etc.)
+ * const spaps = createServerClient('spaps_sec_xxx');
+ *
+ * // Full access to admin operations
+ * await spaps.admin.createProduct({...});
+ * await spaps.payments.crypto.reconcile();
+ * ```
+ */
+declare function createServerClient(secretKey: string, options?: Omit<SPAPSConfig, 'publishableKey' | 'secretKey' | 'apiKey'>): SPAPSClient;
+/**
+ * Detect key type from key prefix
+ */
+declare function detectKeyType(key: string): ApiKeyType | null;
 
-export { type AdminConfig, DEFAULT_ADMIN_ACCOUNTS, type PermissionCheckResult, PermissionChecker, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, TokenManager, WalletUtils, canAccessAdmin, createPermissionChecker, SPAPSClient as default, defaultPermissionChecker, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, verifyCryptoWebhookSignature };
+export { type AdminConfig, type ApiKeyType, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, DEFAULT_ADMIN_ACCOUNTS, type PermissionCheckResult, PermissionChecker, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, TokenManager, WalletUtils, canAccessAdmin, createBrowserClient, createPermissionChecker, createServerClient, SPAPSClient as default, defaultPermissionChecker, detectKeyType, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, verifyCryptoWebhookSignature };

package/dist/index.d.ts

@@ -85,12 +85,53 @@ declare class PermissionChecker {
 declare function createPermissionChecker(customAdmins?: (string | AdminConfig)[]): PermissionChecker;
 declare const defaultPermissionChecker: PermissionChecker;
 
+type ApiKeyType = 'publishable' | 'secret';
 interface SPAPSConfig {
     apiUrl?: string;
+    /** @deprecated Use publishableKey or secretKey instead */
     apiKey?: string;
+    /** Browser-safe key for client-side usage (spaps_pub_xxx) */
+    publishableKey?: string;
+    /** Server-only key for full access (spaps_sec_xxx) */
+    secretKey?: string;
     autoDetect?: boolean;
     timeout?: number;
 }
+interface CheckoutLineItemPriceData {
+    currency: string;
+    unit_amount: number;
+    product_data: {
+        name: string;
+        description?: string;
+        metadata?: Record<string, string>;
+    };
+}
+interface CheckoutLineItem {
+    price_id?: string;
+    product_id?: string;
+    quantity: number;
+    price_data?: CheckoutLineItemPriceData;
+}
+interface CreateCheckoutSessionPayload {
+    mode: 'payment' | 'subscription';
+    line_items: CheckoutLineItem[];
+    success_url: string;
+    cancel_url: string;
+    metadata?: Record<string, string>;
+    customer_email?: string;
+    client_reference_id?: string;
+    payment_intent_data?: {
+        metadata?: Record<string, string>;
+    };
+    subscription_data?: {
+        metadata?: Record<string, string>;
+        trial_period_days?: number;
+    };
+    allow_promotion_codes?: boolean;
+    locale?: string;
+    require_legal_consent?: boolean;
+    legal_consent_text?: string;
+}
 
 declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Record<string, any>> {
     private client;
@@ -269,18 +310,22 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
                 cursor?: Record<string, unknown>;
             }>;
         };
-        createCheckoutSession: (payload: any) => Promise<CheckoutSession>;
+        createCheckoutSession: (payload: CreateCheckoutSessionPayload) => Promise<CheckoutSession>;
         createPaymentCheckout: (params: {
             price_id: string;
             quantity?: number;
             success_url: string;
             cancel_url: string;
+            require_legal_consent?: boolean;
+            legal_consent_text?: string;
         }) => Promise<CheckoutSession>;
         createSubscriptionCheckout: (params: {
             price_id: string;
             success_url: string;
             cancel_url: string;
             trial_period_days?: number;
+            require_legal_consent?: boolean;
+            legal_consent_text?: string;
         }) => Promise<CheckoutSession>;
         getCheckoutSession: (sessionId: string) => Promise<CheckoutSession>;
         listCheckoutSessions: (query?: {
@@ -446,5 +491,39 @@ declare class WalletUtils {
     static detectChainType(address: string): 'solana' | 'ethereum' | 'bitcoin' | null;
     static isValidAddress(address: string, chainType?: 'solana' | 'ethereum' | 'bitcoin' | 'base'): boolean;
 }
+/**
+ * Create a SPAPS client for browser/client-side usage
+ * Uses publishable key which is safe to expose in client bundles
+ *
+ * @example
+ * ```typescript
+ * // In your frontend code
+ * const spaps = createBrowserClient('spaps_pub_xxx');
+ *
+ * // Use for authentication and checkout
+ * const { user } = await spaps.auth.signInWithPassword({ email, password });
+ * const checkout = await spaps.payments.createCheckoutSession({...});
+ * ```
+ */
+declare function createBrowserClient(publishableKey: string, options?: Omit<SPAPSConfig, 'publishableKey' | 'secretKey' | 'apiKey'>): SPAPSClient;
+/**
+ * Create a SPAPS client for server-side usage
+ * Uses secret key which provides full access to all endpoints
+ *
+ * @example
+ * ```typescript
+ * // In your API routes (Next.js, Express, etc.)
+ * const spaps = createServerClient('spaps_sec_xxx');
+ *
+ * // Full access to admin operations
+ * await spaps.admin.createProduct({...});
+ * await spaps.payments.crypto.reconcile();
+ * ```
+ */
+declare function createServerClient(secretKey: string, options?: Omit<SPAPSConfig, 'publishableKey' | 'secretKey' | 'apiKey'>): SPAPSClient;
+/**
+ * Detect key type from key prefix
+ */
+declare function detectKeyType(key: string): ApiKeyType | null;
 
-export { type AdminConfig, DEFAULT_ADMIN_ACCOUNTS, type PermissionCheckResult, PermissionChecker, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, TokenManager, WalletUtils, canAccessAdmin, createPermissionChecker, SPAPSClient as default, defaultPermissionChecker, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, verifyCryptoWebhookSignature };
+export { type AdminConfig, type ApiKeyType, type CheckoutLineItem, type CheckoutLineItemPriceData, type CreateCheckoutSessionPayload, DEFAULT_ADMIN_ACCOUNTS, type PermissionCheckResult, PermissionChecker, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, TokenManager, WalletUtils, canAccessAdmin, createBrowserClient, createPermissionChecker, createServerClient, SPAPSClient as default, defaultPermissionChecker, detectKeyType, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount, verifyCryptoWebhookSignature };

package/dist/index.js

@@ -201,10 +201,13 @@ __export(index_exports, {
   TokenManager: () => TokenManager,
   WalletUtils: () => WalletUtils,
   canAccessAdmin: () => canAccessAdmin,
+  createBrowserClient: () => createBrowserClient,
   createPermissionChecker: () => createPermissionChecker,
   createSecureMessageRequestSchema: () => import_spaps_types.createSecureMessageRequestSchema,
+  createServerClient: () => createServerClient,
   default: () => index_default,
   defaultPermissionChecker: () => defaultPermissionChecker,
+  detectKeyType: () => detectKeyType,
   getRoleAwareErrorMessage: () => getRoleAwareErrorMessage,
   getUserDisplay: () => getUserDisplay,
   getUserRole: () => getUserRole,
@@ -279,6 +282,20 @@ var SPAPSClient = class {
   };
   constructor(config = {}) {
     const apiUrl = config.apiUrl || process.env.SPAPS_API_URL || process.env.NEXT_PUBLIC_SPAPS_API_URL;
+    const isBrowser = typeof window !== "undefined";
+    let effectiveApiKey;
+    if (config.publishableKey) {
+      effectiveApiKey = config.publishableKey;
+    } else if (config.secretKey) {
+      effectiveApiKey = config.secretKey;
+      if (isBrowser) {
+        console.warn("\u26A0\uFE0F SPAPS: Using secretKey in browser is not recommended. Use publishableKey instead.");
+      }
+    } else if (config.apiKey) {
+      effectiveApiKey = config.apiKey;
+    } else {
+      effectiveApiKey = process.env.SPAPS_API_KEY || process.env.NEXT_PUBLIC_SPAPS_API_KEY;
+    }
     if (!apiUrl || apiUrl.includes("localhost") || apiUrl.includes("127.0.0.1")) {
       this._isLocalMode = true;
       this.client = import_axios.default.create({
@@ -289,10 +306,10 @@ var SPAPSClient = class {
         }
       });
     } else {
-      if (!config.apiKey && !process.env.SPAPS_API_KEY) {
+      if (!effectiveApiKey) {
         console.warn("\u26A0\uFE0F SPAPS: No API key provided. Some features may not work.");
       }
-      this.apiKey = config.apiKey || process.env.SPAPS_API_KEY;
+      this.apiKey = effectiveApiKey;
       this.client = import_axios.default.create({
         baseURL: apiUrl,
         timeout: config.timeout || 1e4,
@@ -600,11 +617,25 @@ var SPAPSClient = class {
       return this.unwrapApiResponse(res, "Failed to create checkout session");
     },
     createPaymentCheckout: async (params) => {
-      const payload = { mode: "payment", line_items: [{ price_id: params.price_id, quantity: params.quantity ?? 1 }], success_url: params.success_url, cancel_url: params.cancel_url };
+      const payload = {
+        mode: "payment",
+        line_items: [{ price_id: params.price_id, quantity: params.quantity ?? 1 }],
+        success_url: params.success_url,
+        cancel_url: params.cancel_url,
+        require_legal_consent: params.require_legal_consent,
+        legal_consent_text: params.legal_consent_text
+      };
       return this.payments.createCheckoutSession(payload);
     },
     createSubscriptionCheckout: async (params) => {
-      const payload = { mode: "subscription", line_items: [{ price_id: params.price_id, quantity: 1 }], success_url: params.success_url, cancel_url: params.cancel_url };
+      const payload = {
+        mode: "subscription",
+        line_items: [{ price_id: params.price_id, quantity: 1 }],
+        success_url: params.success_url,
+        cancel_url: params.cancel_url,
+        require_legal_consent: params.require_legal_consent,
+        legal_consent_text: params.legal_consent_text
+      };
       if (params.trial_period_days) payload.subscription_data = { trial_period_days: params.trial_period_days };
       return this.payments.createCheckoutSession(payload);
     },
@@ -1026,6 +1057,29 @@ var WalletUtils = class _WalletUtils {
     }
   }
 };
+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.");
+  }
+  return new SPAPSClient({
+    ...options,
+    publishableKey
+  });
+}
+function createServerClient(secretKey, options) {
+  if (typeof window !== "undefined") {
+    console.warn("\u26A0\uFE0F SPAPS: createServerClient should only be used in server environments. Use createBrowserClient for browser usage.");
+  }
+  return new SPAPSClient({
+    ...options,
+    secretKey
+  });
+}
+function detectKeyType(key) {
+  if (key.startsWith("spaps_pub_")) return "publishable";
+  if (key.startsWith("spaps_sec_") || key.startsWith("spaps_")) return "secret";
+  return null;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_ADMIN_ACCOUNTS,
@@ -1035,9 +1089,12 @@ var WalletUtils = class _WalletUtils {
   TokenManager,
   WalletUtils,
   canAccessAdmin,
+  createBrowserClient,
   createPermissionChecker,
   createSecureMessageRequestSchema,
+  createServerClient,
   defaultPermissionChecker,
+  detectKeyType,
   getRoleAwareErrorMessage,
   getUserDisplay,
   getUserRole,

package/dist/index.mjs

@@ -255,6 +255,20 @@ var SPAPSClient = class {
   };
   constructor(config = {}) {
     const apiUrl = config.apiUrl || process.env.SPAPS_API_URL || process.env.NEXT_PUBLIC_SPAPS_API_URL;
+    const isBrowser = typeof window !== "undefined";
+    let effectiveApiKey;
+    if (config.publishableKey) {
+      effectiveApiKey = config.publishableKey;
+    } else if (config.secretKey) {
+      effectiveApiKey = config.secretKey;
+      if (isBrowser) {
+        console.warn("\u26A0\uFE0F SPAPS: Using secretKey in browser is not recommended. Use publishableKey instead.");
+      }
+    } else if (config.apiKey) {
+      effectiveApiKey = config.apiKey;
+    } else {
+      effectiveApiKey = process.env.SPAPS_API_KEY || process.env.NEXT_PUBLIC_SPAPS_API_KEY;
+    }
     if (!apiUrl || apiUrl.includes("localhost") || apiUrl.includes("127.0.0.1")) {
       this._isLocalMode = true;
       this.client = axios.create({
@@ -265,10 +279,10 @@ var SPAPSClient = class {
         }
       });
     } else {
-      if (!config.apiKey && !process.env.SPAPS_API_KEY) {
+      if (!effectiveApiKey) {
         console.warn("\u26A0\uFE0F SPAPS: No API key provided. Some features may not work.");
       }
-      this.apiKey = config.apiKey || process.env.SPAPS_API_KEY;
+      this.apiKey = effectiveApiKey;
       this.client = axios.create({
         baseURL: apiUrl,
         timeout: config.timeout || 1e4,
@@ -576,11 +590,25 @@ var SPAPSClient = class {
       return this.unwrapApiResponse(res, "Failed to create checkout session");
     },
     createPaymentCheckout: async (params) => {
-      const payload = { mode: "payment", line_items: [{ price_id: params.price_id, quantity: params.quantity ?? 1 }], success_url: params.success_url, cancel_url: params.cancel_url };
+      const payload = {
+        mode: "payment",
+        line_items: [{ price_id: params.price_id, quantity: params.quantity ?? 1 }],
+        success_url: params.success_url,
+        cancel_url: params.cancel_url,
+        require_legal_consent: params.require_legal_consent,
+        legal_consent_text: params.legal_consent_text
+      };
       return this.payments.createCheckoutSession(payload);
     },
     createSubscriptionCheckout: async (params) => {
-      const payload = { mode: "subscription", line_items: [{ price_id: params.price_id, quantity: 1 }], success_url: params.success_url, cancel_url: params.cancel_url };
+      const payload = {
+        mode: "subscription",
+        line_items: [{ price_id: params.price_id, quantity: 1 }],
+        success_url: params.success_url,
+        cancel_url: params.cancel_url,
+        require_legal_consent: params.require_legal_consent,
+        legal_consent_text: params.legal_consent_text
+      };
       if (params.trial_period_days) payload.subscription_data = { trial_period_days: params.trial_period_days };
       return this.payments.createCheckoutSession(payload);
     },
@@ -1002,6 +1030,29 @@ var WalletUtils = class _WalletUtils {
     }
   }
 };
+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.");
+  }
+  return new SPAPSClient({
+    ...options,
+    publishableKey
+  });
+}
+function createServerClient(secretKey, options) {
+  if (typeof window !== "undefined") {
+    console.warn("\u26A0\uFE0F SPAPS: createServerClient should only be used in server environments. Use createBrowserClient for browser usage.");
+  }
+  return new SPAPSClient({
+    ...options,
+    secretKey
+  });
+}
+function detectKeyType(key) {
+  if (key.startsWith("spaps_pub_")) return "publishable";
+  if (key.startsWith("spaps_sec_") || key.startsWith("spaps_")) return "secret";
+  return null;
+}
 export {
   DEFAULT_ADMIN_ACCOUNTS,
   PermissionChecker,
@@ -1010,10 +1061,13 @@ export {
   TokenManager,
   WalletUtils,
   canAccessAdmin,
+  createBrowserClient,
   createPermissionChecker,
   createSecureMessageRequestSchema,
+  createServerClient,
   index_default as default,
   defaultPermissionChecker,
+  detectKeyType,
   getRoleAwareErrorMessage,
   getUserDisplay,
   getUserRole,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spaps-sdk",
-  "version": "1.1.51",
+  "version": "1.2.0",
   "description": "Sweet Potato Authentication & Payment Service SDK - Zero-config client with built-in permission checking and role-based access control",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -44,7 +44,7 @@
     "email": "buildooor@gmail.com"
   },
   "dependencies": {
-    "spaps-types": "^1.0.57",
+    "spaps-types": "^1.0.58",
     "axios": "^1.6.0",
     "cross-fetch": "^4.0.0"
   },
@@ -72,4 +72,4 @@
   "engines": {
     "node": ">=14.0.0"
   }
-}
+}