spaps-sdk 1.1.52 → 1.2.1

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;
@@ -203,14 +244,13 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
             password: string;
         }) => Promise<any>;
         /**
-         * Verify a magic link token. Does not set access/refresh tokens.
-         * Consumers should redirect or prompt login based on the returned status.
+         * Verify a magic link token and authenticate the user.
+         * Returns full auth response with tokens and auto-stores them.
          */
         verifyMagicLink: (payload: {
             token: string;
-        }) => Promise<{
-            success: boolean;
-        }>;
+            type?: string;
+        }) => Promise<AuthResponse>;
         solana: {
             linkWallet: (payload: {
                 wallet_address: string;
@@ -269,18 +309,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?: {
@@ -357,6 +401,51 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
         revokeAll: () => Promise<any>;
         touch: () => Promise<any>;
     };
+    /**
+     * CFO (QuickBooks) namespace for managing multi-account connections
+     */
+    cfo: {
+        /**
+         * Get all QuickBooks connections for the current user
+         */
+        getConnections: () => Promise<{
+            connections: Array<{
+                id: string;
+                status: string;
+                companyName?: string;
+                realmId?: string;
+                connectedAt?: string;
+            }>;
+        }>;
+        /**
+         * Get connection status (returns primary connection for backward compatibility)
+         */
+        getStatus: () => Promise<{
+            connection: {
+                id: string;
+                status: string;
+                companyName?: string;
+                realmId?: string;
+            } | null;
+            totalConnections: number;
+        }>;
+        /**
+         * Start adding a new QuickBooks connection
+         * Returns auth URL to redirect user to QuickBooks OAuth
+         */
+        addConnection: () => Promise<{
+            authUrl: string;
+            connectionId: string;
+            existingConnections: number;
+        }>;
+        /**
+         * Disconnect a specific QuickBooks account
+         */
+        disconnect: (connectionId: string) => Promise<{
+            success: boolean;
+            message: string;
+        }>;
+    };
     createCheckoutSession(priceId: string, successUrl: string, cancelUrl?: string): Promise<{
         data: CheckoutSession;
     }>;
@@ -417,6 +506,12 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
     isAuthenticated(): boolean;
     getAccessToken(): string | undefined;
     setAccessToken(token: string): void;
+    setRefreshToken(token: string): void;
+    /**
+     * Restore tokens (for SSO/OAuth flows)
+     * Sets both access and refresh tokens
+     */
+    restoreTokens(accessToken: string, refreshToken?: string): void;
     isLocalMode(): boolean;
     /**
      * Check if current user has admin privileges
@@ -433,6 +528,10 @@ declare class TokenManager {
     private static readonly ACCESS_TOKEN_KEY;
     private static readonly REFRESH_TOKEN_KEY;
     private static readonly USER_KEY;
+    /**
+     * Cross-platform base64 decode (works in both Node.js and browser)
+     */
+    private static base64Decode;
     private static getStorage;
     static storeTokens(tokens: AuthResponse): void;
     static getAccessToken(): string | null;
@@ -441,10 +540,62 @@ declare class TokenManager {
     static clearTokens(): void;
     static isTokenExpired(token: string): boolean;
     static autoRefreshToken(sdk: SPAPSClient): Promise<boolean>;
+    /**
+     * Parse auth tokens from URL fragment (for OAuth callbacks)
+     * URL format: https://app.com/callback#access_token=xxx&refresh_token=xxx
+     */
+    static parseTokensFromUrlFragment(url?: string): {
+        access_token?: string;
+        refresh_token?: string;
+        user_id?: string;
+    } | null;
+    /**
+     * Handle OAuth callback - parse tokens from URL and store them
+     * Returns user info decoded from JWT, or null if no tokens found
+     */
+    static handleOAuthCallback(sdk: SPAPSClient): {
+        id: string;
+        email?: string;
+        role?: string;
+    } | null;
 }
 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;
@@ -203,14 +244,13 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
             password: string;
         }) => Promise<any>;
         /**
-         * Verify a magic link token. Does not set access/refresh tokens.
-         * Consumers should redirect or prompt login based on the returned status.
+         * Verify a magic link token and authenticate the user.
+         * Returns full auth response with tokens and auto-stores them.
          */
         verifyMagicLink: (payload: {
             token: string;
-        }) => Promise<{
-            success: boolean;
-        }>;
+            type?: string;
+        }) => Promise<AuthResponse>;
         solana: {
             linkWallet: (payload: {
                 wallet_address: string;
@@ -269,18 +309,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?: {
@@ -357,6 +401,51 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
         revokeAll: () => Promise<any>;
         touch: () => Promise<any>;
     };
+    /**
+     * CFO (QuickBooks) namespace for managing multi-account connections
+     */
+    cfo: {
+        /**
+         * Get all QuickBooks connections for the current user
+         */
+        getConnections: () => Promise<{
+            connections: Array<{
+                id: string;
+                status: string;
+                companyName?: string;
+                realmId?: string;
+                connectedAt?: string;
+            }>;
+        }>;
+        /**
+         * Get connection status (returns primary connection for backward compatibility)
+         */
+        getStatus: () => Promise<{
+            connection: {
+                id: string;
+                status: string;
+                companyName?: string;
+                realmId?: string;
+            } | null;
+            totalConnections: number;
+        }>;
+        /**
+         * Start adding a new QuickBooks connection
+         * Returns auth URL to redirect user to QuickBooks OAuth
+         */
+        addConnection: () => Promise<{
+            authUrl: string;
+            connectionId: string;
+            existingConnections: number;
+        }>;
+        /**
+         * Disconnect a specific QuickBooks account
+         */
+        disconnect: (connectionId: string) => Promise<{
+            success: boolean;
+            message: string;
+        }>;
+    };
     createCheckoutSession(priceId: string, successUrl: string, cancelUrl?: string): Promise<{
         data: CheckoutSession;
     }>;
@@ -417,6 +506,12 @@ declare class SPAPSClient<SecureMessageMetadata extends Record<string, any> = Re
     isAuthenticated(): boolean;
     getAccessToken(): string | undefined;
     setAccessToken(token: string): void;
+    setRefreshToken(token: string): void;
+    /**
+     * Restore tokens (for SSO/OAuth flows)
+     * Sets both access and refresh tokens
+     */
+    restoreTokens(accessToken: string, refreshToken?: string): void;
     isLocalMode(): boolean;
     /**
      * Check if current user has admin privileges
@@ -433,6 +528,10 @@ declare class TokenManager {
     private static readonly ACCESS_TOKEN_KEY;
     private static readonly REFRESH_TOKEN_KEY;
     private static readonly USER_KEY;
+    /**
+     * Cross-platform base64 decode (works in both Node.js and browser)
+     */
+    private static base64Decode;
     private static getStorage;
     static storeTokens(tokens: AuthResponse): void;
     static getAccessToken(): string | null;
@@ -441,10 +540,62 @@ declare class TokenManager {
     static clearTokens(): void;
     static isTokenExpired(token: string): boolean;
     static autoRefreshToken(sdk: SPAPSClient): Promise<boolean>;
+    /**
+     * Parse auth tokens from URL fragment (for OAuth callbacks)
+     * URL format: https://app.com/callback#access_token=xxx&refresh_token=xxx
+     */
+    static parseTokensFromUrlFragment(url?: string): {
+        access_token?: string;
+        refresh_token?: string;
+        user_id?: string;
+    } | null;
+    /**
+     * Handle OAuth callback - parse tokens from URL and store them
+     * Returns user info decoded from JWT, or null if no tokens found
+     */
+    static handleOAuthCallback(sdk: SPAPSClient): {
+        id: string;
+        email?: string;
+        role?: string;
+    } | null;
 }
 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,
@@ -453,12 +470,24 @@ var SPAPSClient = class {
       return data;
     },
     /**
-     * Verify a magic link token. Does not set access/refresh tokens.
-     * Consumers should redirect or prompt login based on the returned status.
+     * Verify a magic link token and authenticate the user.
+     * Returns full auth response with tokens and auto-stores them.
      */
     verifyMagicLink: async (payload) => {
-      const res = await this.client.post("/api/auth/verify-magic-link", payload);
-      return this.unwrapApiResponse(res, "Failed to verify magic link");
+      const res = await this.client.post("/api/auth/verify-magic-link", {
+        token: payload.token,
+        type: payload.type || "magiclink"
+      });
+      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;
     },
     solana: {
       linkWallet: async (payload) => {
@@ -600,11 +629,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);
     },
@@ -760,6 +803,40 @@ var SPAPSClient = class {
       return this.unwrapApiResponse(res, "Failed to touch session");
     }
   };
+  /**
+   * CFO (QuickBooks) namespace for managing multi-account connections
+   */
+  cfo = {
+    /**
+     * Get all QuickBooks connections for the current user
+     */
+    getConnections: async () => {
+      const res = await this.client.get("/api/cfo/user-connections", this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0);
+      return this.unwrapApiResponse(res, "Failed to get connections");
+    },
+    /**
+     * Get connection status (returns primary connection for backward compatibility)
+     */
+    getStatus: async () => {
+      const res = await this.client.get("/api/cfo/user-status", this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0);
+      return this.unwrapApiResponse(res, "Failed to get status");
+    },
+    /**
+     * Start adding a new QuickBooks connection
+     * Returns auth URL to redirect user to QuickBooks OAuth
+     */
+    addConnection: async () => {
+      const res = await this.client.post("/api/cfo/user-add-connection", {}, this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0);
+      return this.unwrapApiResponse(res, "Failed to start connection");
+    },
+    /**
+     * Disconnect a specific QuickBooks account
+     */
+    disconnect: async (connectionId) => {
+      const res = await this.client.delete(`/api/cfo/user-connections/${connectionId}`, this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0);
+      return this.unwrapApiResponse(res, "Failed to disconnect");
+    }
+  };
   // Stripe Methods
   async createCheckoutSession(priceId, successUrl, cancelUrl) {
     return this.client.post("/api/stripe/create-checkout-session", {
@@ -883,6 +960,19 @@ var SPAPSClient = class {
   setAccessToken(token) {
     this.accessToken = token;
   }
+  setRefreshToken(token) {
+    this.refreshToken = token;
+  }
+  /**
+   * Restore tokens (for SSO/OAuth flows)
+   * Sets both access and refresh tokens
+   */
+  restoreTokens(accessToken, refreshToken) {
+    this.accessToken = accessToken;
+    if (refreshToken) {
+      this.refreshToken = refreshToken;
+    }
+  }
   isLocalMode() {
     return this._isLocalMode;
   }
@@ -937,6 +1027,17 @@ var TokenManager = class _TokenManager {
   static ACCESS_TOKEN_KEY = "sweet_potato_access_token";
   static REFRESH_TOKEN_KEY = "sweet_potato_refresh_token";
   static USER_KEY = "sweet_potato_user";
+  /**
+   * Cross-platform base64 decode (works in both Node.js and browser)
+   */
+  static base64Decode(str) {
+    if (typeof Buffer !== "undefined") {
+      return Buffer.from(str, "base64").toString("utf8");
+    } else if (typeof atob !== "undefined") {
+      return atob(str);
+    }
+    throw new Error("No base64 decode method available");
+  }
   static getStorage() {
     if (typeof globalThis !== "undefined" && globalThis.localStorage) return globalThis.localStorage;
     if (typeof globalThis !== "undefined" && globalThis.window?.localStorage) return globalThis.window.localStorage;
@@ -977,7 +1078,7 @@ var TokenManager = class _TokenManager {
     try {
       const parts = token.split(".");
       if (parts.length !== 3 || !parts[1]) return true;
-      const payload = JSON.parse(atob(parts[1]));
+      const payload = JSON.parse(_TokenManager.base64Decode(parts[1]));
       const now = Math.floor(Date.now() / 1e3);
       return payload.exp < now;
     } catch {
@@ -1001,6 +1102,74 @@ var TokenManager = class _TokenManager {
       return false;
     }
   }
+  /**
+   * Parse auth tokens from URL fragment (for OAuth callbacks)
+   * URL format: https://app.com/callback#access_token=xxx&refresh_token=xxx
+   */
+  static parseTokensFromUrlFragment(url) {
+    let hash;
+    if (url) {
+      try {
+        hash = new URL(url).hash;
+      } catch {
+        return null;
+      }
+    } else if (typeof window !== "undefined") {
+      hash = window.location.hash;
+    } else {
+      return null;
+    }
+    if (!hash || hash.length < 2) return null;
+    const params = new URLSearchParams(hash.substring(1));
+    const access_token = params.get("access_token");
+    const refresh_token = params.get("refresh_token");
+    if (!access_token) return null;
+    return {
+      access_token,
+      refresh_token: refresh_token || void 0,
+      user_id: params.get("user_id") || void 0
+    };
+  }
+  /**
+   * Handle OAuth callback - parse tokens from URL and store them
+   * Returns user info decoded from JWT, or null if no tokens found
+   */
+  static handleOAuthCallback(sdk) {
+    const tokens = _TokenManager.parseTokensFromUrlFragment();
+    if (!tokens?.access_token) {
+      console.debug("[SPAPS] handleOAuthCallback: No access token found in URL fragment");
+      return null;
+    }
+    if (typeof window !== "undefined") {
+      window.history.replaceState(null, "", window.location.pathname + window.location.search);
+    }
+    try {
+      const parts = tokens.access_token.split(".");
+      if (parts.length !== 3 || !parts[1]) {
+        console.warn("[SPAPS] handleOAuthCallback: Invalid JWT format - expected 3 parts");
+        return null;
+      }
+      const payload = JSON.parse(_TokenManager.base64Decode(parts[1]));
+      const user = {
+        id: payload.user_id || payload.sub,
+        email: payload.email,
+        role: payload.role || "user"
+      };
+      _TokenManager.storeTokens({
+        access_token: tokens.access_token,
+        refresh_token: tokens.refresh_token || "",
+        user
+      });
+      sdk.setAccessToken(tokens.access_token);
+      if (tokens.refresh_token) {
+        sdk.setRefreshToken(tokens.refresh_token);
+      }
+      return user;
+    } catch (err) {
+      console.warn("[SPAPS] handleOAuthCallback: Failed to decode JWT", err);
+      return null;
+    }
+  }
 };
 var WalletUtils = class _WalletUtils {
   static detectChainType(address) {
@@ -1026,6 +1195,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 +1227,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,
@@ -429,12 +443,24 @@ var SPAPSClient = class {
       return data;
     },
     /**
-     * Verify a magic link token. Does not set access/refresh tokens.
-     * Consumers should redirect or prompt login based on the returned status.
+     * Verify a magic link token and authenticate the user.
+     * Returns full auth response with tokens and auto-stores them.
      */
     verifyMagicLink: async (payload) => {
-      const res = await this.client.post("/api/auth/verify-magic-link", payload);
-      return this.unwrapApiResponse(res, "Failed to verify magic link");
+      const res = await this.client.post("/api/auth/verify-magic-link", {
+        token: payload.token,
+        type: payload.type || "magiclink"
+      });
+      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;
     },
     solana: {
       linkWallet: async (payload) => {
@@ -576,11 +602,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);
     },
@@ -736,6 +776,40 @@ var SPAPSClient = class {
       return this.unwrapApiResponse(res, "Failed to touch session");
     }
   };
+  /**
+   * CFO (QuickBooks) namespace for managing multi-account connections
+   */
+  cfo = {
+    /**
+     * Get all QuickBooks connections for the current user
+     */
+    getConnections: async () => {
+      const res = await this.client.get("/api/cfo/user-connections", this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0);
+      return this.unwrapApiResponse(res, "Failed to get connections");
+    },
+    /**
+     * Get connection status (returns primary connection for backward compatibility)
+     */
+    getStatus: async () => {
+      const res = await this.client.get("/api/cfo/user-status", this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0);
+      return this.unwrapApiResponse(res, "Failed to get status");
+    },
+    /**
+     * Start adding a new QuickBooks connection
+     * Returns auth URL to redirect user to QuickBooks OAuth
+     */
+    addConnection: async () => {
+      const res = await this.client.post("/api/cfo/user-add-connection", {}, this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0);
+      return this.unwrapApiResponse(res, "Failed to start connection");
+    },
+    /**
+     * Disconnect a specific QuickBooks account
+     */
+    disconnect: async (connectionId) => {
+      const res = await this.client.delete(`/api/cfo/user-connections/${connectionId}`, this.accessToken ? { headers: { Authorization: `Bearer ${this.accessToken}` } } : void 0);
+      return this.unwrapApiResponse(res, "Failed to disconnect");
+    }
+  };
   // Stripe Methods
   async createCheckoutSession(priceId, successUrl, cancelUrl) {
     return this.client.post("/api/stripe/create-checkout-session", {
@@ -859,6 +933,19 @@ var SPAPSClient = class {
   setAccessToken(token) {
     this.accessToken = token;
   }
+  setRefreshToken(token) {
+    this.refreshToken = token;
+  }
+  /**
+   * Restore tokens (for SSO/OAuth flows)
+   * Sets both access and refresh tokens
+   */
+  restoreTokens(accessToken, refreshToken) {
+    this.accessToken = accessToken;
+    if (refreshToken) {
+      this.refreshToken = refreshToken;
+    }
+  }
   isLocalMode() {
     return this._isLocalMode;
   }
@@ -913,6 +1000,17 @@ var TokenManager = class _TokenManager {
   static ACCESS_TOKEN_KEY = "sweet_potato_access_token";
   static REFRESH_TOKEN_KEY = "sweet_potato_refresh_token";
   static USER_KEY = "sweet_potato_user";
+  /**
+   * Cross-platform base64 decode (works in both Node.js and browser)
+   */
+  static base64Decode(str) {
+    if (typeof Buffer !== "undefined") {
+      return Buffer.from(str, "base64").toString("utf8");
+    } else if (typeof atob !== "undefined") {
+      return atob(str);
+    }
+    throw new Error("No base64 decode method available");
+  }
   static getStorage() {
     if (typeof globalThis !== "undefined" && globalThis.localStorage) return globalThis.localStorage;
     if (typeof globalThis !== "undefined" && globalThis.window?.localStorage) return globalThis.window.localStorage;
@@ -953,7 +1051,7 @@ var TokenManager = class _TokenManager {
     try {
       const parts = token.split(".");
       if (parts.length !== 3 || !parts[1]) return true;
-      const payload = JSON.parse(atob(parts[1]));
+      const payload = JSON.parse(_TokenManager.base64Decode(parts[1]));
       const now = Math.floor(Date.now() / 1e3);
       return payload.exp < now;
     } catch {
@@ -977,6 +1075,74 @@ var TokenManager = class _TokenManager {
       return false;
     }
   }
+  /**
+   * Parse auth tokens from URL fragment (for OAuth callbacks)
+   * URL format: https://app.com/callback#access_token=xxx&refresh_token=xxx
+   */
+  static parseTokensFromUrlFragment(url) {
+    let hash;
+    if (url) {
+      try {
+        hash = new URL(url).hash;
+      } catch {
+        return null;
+      }
+    } else if (typeof window !== "undefined") {
+      hash = window.location.hash;
+    } else {
+      return null;
+    }
+    if (!hash || hash.length < 2) return null;
+    const params = new URLSearchParams(hash.substring(1));
+    const access_token = params.get("access_token");
+    const refresh_token = params.get("refresh_token");
+    if (!access_token) return null;
+    return {
+      access_token,
+      refresh_token: refresh_token || void 0,
+      user_id: params.get("user_id") || void 0
+    };
+  }
+  /**
+   * Handle OAuth callback - parse tokens from URL and store them
+   * Returns user info decoded from JWT, or null if no tokens found
+   */
+  static handleOAuthCallback(sdk) {
+    const tokens = _TokenManager.parseTokensFromUrlFragment();
+    if (!tokens?.access_token) {
+      console.debug("[SPAPS] handleOAuthCallback: No access token found in URL fragment");
+      return null;
+    }
+    if (typeof window !== "undefined") {
+      window.history.replaceState(null, "", window.location.pathname + window.location.search);
+    }
+    try {
+      const parts = tokens.access_token.split(".");
+      if (parts.length !== 3 || !parts[1]) {
+        console.warn("[SPAPS] handleOAuthCallback: Invalid JWT format - expected 3 parts");
+        return null;
+      }
+      const payload = JSON.parse(_TokenManager.base64Decode(parts[1]));
+      const user = {
+        id: payload.user_id || payload.sub,
+        email: payload.email,
+        role: payload.role || "user"
+      };
+      _TokenManager.storeTokens({
+        access_token: tokens.access_token,
+        refresh_token: tokens.refresh_token || "",
+        user
+      });
+      sdk.setAccessToken(tokens.access_token);
+      if (tokens.refresh_token) {
+        sdk.setRefreshToken(tokens.refresh_token);
+      }
+      return user;
+    } catch (err) {
+      console.warn("[SPAPS] handleOAuthCallback: Failed to decode JWT", err);
+      return null;
+    }
+  }
 };
 var WalletUtils = class _WalletUtils {
   static detectChainType(address) {
@@ -1002,6 +1168,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 +1199,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.52",
+  "version": "1.2.1",
   "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.59",
     "axios": "^1.6.0",
     "cross-fetch": "^4.0.0"
   },