spaps-sdk 1.1.1 → 1.1.3

package/README.md

@@ -1,5 +1,9 @@
 # @spaps/sdk
 
+<a href="https://www.npmjs.com/package/spaps-sdk"><img alt="npm" src="https://img.shields.io/npm/v/spaps-sdk.svg"></a>
+<img alt="node" src="https://img.shields.io/badge/node-%3E%3D14-brightgreen">
+<img alt="types" src="https://img.shields.io/badge/types-TypeScript-blue">
+
 > Sweet Potato Authentication & Payment Service SDK
 
 Zero-config client for SPAPS authentication, payments, and permission checking. Works automatically with local development mode.
@@ -111,6 +115,38 @@ if (spaps.isAuthenticated()) {
 }
 ```
 
+## Local Mode Explained
+
+- If `apiUrl` is omitted or points to `localhost`/`127.0.0.1`, the SDK runs in local mode.
+- Local mode integrates seamlessly with the `spaps` CLI (`npx spaps local`), defaulting to `http://localhost:3300`.
+- No API key is required in local mode; tokens and data are managed locally for development.
+
+You can check the mode at runtime:
+
+```ts
+spaps.isLocalMode(); // true | false
+```
+
+## Environment Variables
+
+The SDK can read configuration from environment variables (useful in Next.js and Node):
+
+- `SPAPS_API_URL` or `NEXT_PUBLIC_SPAPS_API_URL` — API base URL
+- `SPAPS_API_KEY` — API key for production use
+
+Example (Node):
+
+```bash
+export SPAPS_API_URL=https://api.sweetpotato.dev
+export SPAPS_API_KEY=spaps_xxx
+```
+
+Example (Next.js):
+
+```env
+NEXT_PUBLIC_SPAPS_API_URL=https://api.sweetpotato.dev
+```
+
 ## Features
 
 ### 🚀 Zero Configuration
@@ -202,6 +238,30 @@ spaps.isLocalMode() // boolean
 await spaps.health()
 ```
 
+## Types
+
+The SDK ships with full TypeScript definitions. For most apps, import types directly from `spaps-sdk`:
+
+```ts
+import { SPAPSClient, type User, type Session, type Role } from 'spaps-sdk';
+```
+
+For advanced or library use cases, you can also import canonical types from the standalone package:
+
+```ts
+import type {
+  User,
+  Session,
+  Role,
+  Permission,
+  TokenPayload,
+} from 'spaps-types';
+```
+
+Notes:
+- `spaps-sdk` re-exports commonly used types for convenience.
+- `spaps-types` is useful when building framework integrations, server middleware, or utilities that need to share types without depending on the SDK runtime.
+
 ## Import Styles
 
 All these work:

package/dist/index.d.mts

@@ -1,8 +1,11 @@
+import { CreateProductRequest, Product, UpdateProductRequest, CreatePriceRequest, Price, ProductSyncResult, AuthResponse, User as User$1, CheckoutSession, Subscription, UsageBalance } from 'spaps-types';
+export { AdminPermission, AdminRole, AdminUser, ApiResponse, AuthResponse, CheckoutSession, CreatePriceRequest, CreateProductRequest, Price, Product, ProductSyncResult, Subscription, TokenPair, UpdateProductRequest, UsageBalance, User, UserProfile, UserRole, UserWallet } from 'spaps-types';
+
 /**
  * Permission checking utilities for SPAPS SDK
  * Client-side role and permission management
  */
-interface User$1 {
+interface User {
     id: string;
     email?: string;
     wallet_address?: string;
@@ -35,11 +38,11 @@ declare function getUserRole(identifier?: string, customAdmins?: (string | Admin
 /**
  * Check if user has specific permissions
  */
-declare function hasPermission(user: User$1 | null, requiredPermissions: string | string[], customAdmins?: (string | AdminConfig)[]): boolean;
+declare function hasPermission(user: User | null, requiredPermissions: string | string[], customAdmins?: (string | AdminConfig)[]): boolean;
 /**
  * Check if user can access admin features
  */
-declare function canAccessAdmin(user: User$1 | null, customAdmins?: (string | AdminConfig)[]): PermissionCheckResult;
+declare function canAccessAdmin(user: User | null, customAdmins?: (string | AdminConfig)[]): PermissionCheckResult;
 /**
  * Get role-aware error message
  */
@@ -47,7 +50,7 @@ declare function getRoleAwareErrorMessage(requiredRole: string, userRole: string
 /**
  * Get user display information with role indicators
  */
-declare function getUserDisplay(user: User$1 | null, customAdmins?: (string | AdminConfig)[]): {
+declare function getUserDisplay(user: User | null, customAdmins?: (string | AdminConfig)[]): {
     displayName: string;
     role: string;
     badge: string | null;
@@ -61,17 +64,17 @@ declare class PermissionChecker {
     constructor(customAdmins?: (string | AdminConfig)[]);
     isAdmin(identifier: string): boolean;
     getRole(identifier?: string): string;
-    hasPermission(user: User$1 | null, permissions: string | string[]): boolean;
-    canAccessAdmin(user: User$1 | null): PermissionCheckResult;
+    hasPermission(user: User | null, permissions: string | string[]): boolean;
+    canAccessAdmin(user: User | null): PermissionCheckResult;
     getErrorMessage(requiredRole: string, userRole: string, action?: string): string;
-    getUserDisplay(user: User$1 | null): {
+    getUserDisplay(user: User | null): {
         displayName: string;
         role: string;
         badge: string | null;
         isAdmin: boolean;
     };
-    requiresAuth(user: User$1 | null): boolean;
-    requiresAdmin(user: User$1 | null): boolean;
+    requiresAuth(user: User | null): boolean;
+    requiresAdmin(user: User | null): boolean;
     addCustomAdmin(admin: string | AdminConfig): void;
     removeCustomAdmin(admin: string | AdminConfig): void;
 }
@@ -85,100 +88,14 @@ declare const defaultPermissionChecker: PermissionChecker;
  * @spaps/sdk - Sweet Potato Authentication & Payment Service SDK
  * Zero-config client for SPAPS authentication and payments
  */
+
 interface SPAPSConfig {
     apiUrl?: string;
     apiKey?: string;
     autoDetect?: boolean;
     timeout?: number;
 }
-interface AuthResponse {
-    access_token: string;
-    refresh_token: string;
-    user: User;
-}
-interface User {
-    id: string;
-    email?: string;
-    wallet_address?: string;
-    chain_type?: string;
-    role: string;
-    created_at?: string;
-}
-interface CheckoutSession {
-    sessionId: string;
-    url: string;
-}
-interface Subscription {
-    id: string;
-    status: string;
-    plan: string;
-    current_period_end: string;
-}
-interface UsageBalance {
-    balance: number;
-    currency: string;
-    updated_at: string;
-}
-interface Product {
-    id: string;
-    name: string;
-    description?: string;
-    category: string;
-    active: boolean;
-    images?: string[];
-    metadata?: Record<string, string>;
-    statement_descriptor?: string;
-    unit_label?: string;
-    created?: number;
-    updated?: number;
-}
-interface Price {
-    id: string;
-    product: string;
-    unit_amount: number;
-    currency: string;
-    recurring?: {
-        interval: 'day' | 'week' | 'month' | 'year';
-        interval_count: number;
-    };
-    nickname?: string;
-    active: boolean;
-}
-interface CreateProductRequest {
-    name: string;
-    description?: string;
-    category: string;
-    images?: string[];
-    metadata?: Record<string, string>;
-    active?: boolean;
-    statement_descriptor?: string;
-    unit_label?: string;
-}
-interface UpdateProductRequest {
-    name?: string;
-    description?: string;
-    category?: string;
-    images?: string[];
-    metadata?: Record<string, string>;
-    active?: boolean;
-    statement_descriptor?: string;
-    unit_label?: string;
-}
-interface CreatePriceRequest {
-    product_id: string;
-    unit_amount: number;
-    currency: string;
-    interval?: 'day' | 'week' | 'month' | 'year';
-    interval_count?: number;
-    nickname?: string;
-}
-interface ProductSyncResult {
-    synced_count: number;
-    updated_count: number;
-    created_count: number;
-    errors: any[];
-    sync_time: string;
-}
+
 declare class SPAPSClient {
     private client;
     private apiKey?;
@@ -214,6 +131,18 @@ declare class SPAPSClient {
         }>;
     };
     constructor(config?: SPAPSConfig);
+    /** Raw API request helper that returns an ApiResponse-like shape */
+    request<T = any>(method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', url: string, data?: any, requiresAuth?: boolean): Promise<{
+        success: boolean;
+        data?: T;
+        error?: {
+            code: string;
+            message: string;
+            details?: any;
+        };
+    }>;
+    /** Health check helper that returns boolean */
+    healthCheck(): Promise<boolean>;
     login(email: string, password: string): Promise<{
         data: AuthResponse;
     }>;
@@ -228,8 +157,178 @@ declare class SPAPSClient {
     }>;
     logout(): Promise<void>;
     getUser(): Promise<{
-        data: User;
+        data: User$1;
     }>;
+    auth: {
+        /**
+         * Verify magic link token without mutating token state.
+         * Returns a simple success object from the API.
+         */
+        getNonce: (walletAddress: string) => Promise<any>;
+        signInWithWallet: (req: {
+            wallet_address: string;
+            signature: string;
+            message: string;
+            chain_type?: "solana" | "ethereum" | "bitcoin" | "base";
+            username?: string;
+        }) => Promise<any>;
+        authenticateWallet: (walletAddress: string, signFn: (message: string) => Promise<string> | string, chainType?: "solana" | "ethereum" | "bitcoin" | "base", username?: string) => Promise<any>;
+        signInWithPassword: (payload: {
+            email: string;
+            password: string;
+        }) => Promise<any>;
+        requestMagicLink: (payload: {
+            email: string;
+            redirect_url?: string;
+        }) => Promise<void>;
+        requestPasswordReset: (payload: {
+            email: string;
+            redirect_url?: string;
+        }) => Promise<void>;
+        confirmPasswordReset: (payload: {
+            token: string;
+            new_password: string;
+        }) => Promise<void>;
+        register: (payload: {
+            email: string;
+            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.
+         */
+        verifyMagicLink: (payload: {
+            token: string;
+        }) => Promise<{
+            success: boolean;
+        }>;
+        solana: {
+            linkWallet: (payload: {
+                wallet_address: string;
+                signature: string;
+                message: string;
+            }) => Promise<any>;
+            verifySignature: (payload: {
+                wallet_address: string;
+                signature: string;
+                message: string;
+            }) => Promise<any>;
+            generateMessage: (wallet_address: string) => Promise<any>;
+            getWallets: () => Promise<any>;
+            networkInfo: () => Promise<any>;
+        };
+        ethereum: {
+            linkWallet: (payload: {
+                wallet_address: string;
+                signature: string;
+                message: string;
+            }) => Promise<any>;
+            verifySignature: (payload: {
+                wallet_address: string;
+                signature: string;
+                message: string;
+            }) => Promise<any>;
+            verifyTypedData: (payload: {
+                wallet_address: string;
+                signature: string;
+                typed_data: any;
+            }) => Promise<any>;
+            generateMessage: (wallet_address: string) => Promise<any>;
+            generateTypedData: (wallet_address: string) => Promise<any>;
+            getWallets: () => Promise<any>;
+            networkInfo: () => Promise<any>;
+            balance: (wallet_address: string) => Promise<any>;
+            contractCheck: (wallet_address: string, contract_address: string) => Promise<any>;
+        };
+        refreshToken: (refreshToken: string) => Promise<any>;
+        /**
+         * Logout and clear tokens. Network errors are intentionally swallowed
+         * to avoid trapping users in a bad state during sign‑out flows.
+         */
+        logout: () => Promise<void>;
+        getCurrentUser: () => Promise<User$1>;
+        isAuthenticated: () => boolean;
+    };
+    payments: {
+        createCheckoutSession: (payload: any) => Promise<CheckoutSession>;
+        createPaymentCheckout: (params: {
+            price_id: string;
+            quantity?: number;
+            success_url: string;
+            cancel_url: string;
+        }) => Promise<CheckoutSession>;
+        createSubscriptionCheckout: (params: {
+            price_id: string;
+            success_url: string;
+            cancel_url: string;
+            trial_period_days?: number;
+        }) => Promise<CheckoutSession>;
+        getCheckoutSession: (sessionId: string) => Promise<any>;
+        listCheckoutSessions: (query?: {
+            limit?: number;
+            starting_after?: string;
+        }) => Promise<any>;
+        expireCheckoutSession: (sessionId: string) => Promise<any>;
+        listProducts: (query?: {
+            category?: string;
+            active?: boolean;
+            limit?: number;
+            starting_after?: string;
+        }) => Promise<{
+            products: Product[];
+            total: number;
+        }>;
+        getProduct: (productId: string) => Promise<Product>;
+        createCustomerPortalSession: (payload: {
+            return_url: string;
+        }) => Promise<{
+            id: string;
+            url: string;
+        }>;
+        createGuestCheckoutSession: (payload: any) => Promise<any>;
+        getGuestCheckoutSession: (sessionId: string) => Promise<any>;
+        listGuestCheckoutSessions: (query?: {
+            limit?: number;
+            starting_after?: string;
+        }) => Promise<any>;
+        convertGuestCheckoutSession: (payload: {
+            session_id: string;
+        }) => Promise<any>;
+        convertGuestCheckout: (payload: {
+            session_id: string;
+        }) => Promise<any>;
+        listAllProductsSuperAdmin: () => Promise<any>;
+        updateProductSuperAdmin: (productId: string, updates: any) => Promise<any>;
+        deleteProductSuperAdmin: (productId: string) => Promise<any>;
+        createProductWithPrice: (payload: any) => Promise<any>;
+        createProductWithPriceSuperAdmin: (productId: string, payload: any) => Promise<any>;
+        setDefaultPrice: (productId: string, payload: {
+            price_id: string;
+        }) => Promise<any>;
+        setDefaultPriceSuperAdmin: (productId: string, payload: {
+            price_id: string;
+        }) => Promise<any>;
+        createDefaultNewPrice: (productId: string, payload: any) => Promise<any>;
+        superAdminListAllProducts: () => Promise<any>;
+        superAdminUpdateProduct: (productId: string, updates: any) => Promise<any>;
+        superAdminArchiveProduct: (productId: string) => Promise<any>;
+        superAdminCreateProductWithPrice: (applicationId: string, payload: any) => Promise<any>;
+        superAdminCreatePriceAndSetDefault: (productId: string, payload: any) => Promise<any>;
+        superAdminSetDefaultPrice: (productId: string, payload: {
+            price_id: string;
+        }) => Promise<any>;
+    };
+    sessions: {
+        getCurrent: () => Promise<any>;
+        list: (params?: {
+            limit?: number;
+            starting_after?: string;
+        }) => Promise<any>;
+        validate: () => Promise<any>;
+        revoke: (sessionId: string) => Promise<any>;
+        revokeAll: () => Promise<any>;
+        touch: () => Promise<any>;
+    };
     createCheckoutSession(priceId: string, successUrl: string, cancelUrl?: string): Promise<{
         data: CheckoutSession;
     }>;
@@ -293,10 +392,28 @@ declare class SPAPSClient {
      * Check if current user has admin privileges
      * Note: This requires the user object from authentication
      */
-    isAdmin(user?: User): boolean;
+    isAdmin(user?: User$1): boolean;
     health(): Promise<{
         data: any;
     }>;
 }
 
-export { type AdminConfig, type AuthResponse, type CheckoutSession, type CreatePriceRequest, type CreateProductRequest, DEFAULT_ADMIN_ACCOUNTS, type PermissionCheckResult, PermissionChecker, type Price, type Product, type ProductSyncResult, SPAPSClient as SPAPS, SPAPSClient, type SPAPSConfig, type Subscription, SPAPSClient as SweetPotatoSDK, type UpdateProductRequest, type UsageBalance, type User, canAccessAdmin, createPermissionChecker, SPAPSClient as default, defaultPermissionChecker, getRoleAwareErrorMessage, getUserDisplay, getUserRole, hasPermission, isAdminAccount };
+declare class TokenManager {
+    private static readonly ACCESS_TOKEN_KEY;
+    private static readonly REFRESH_TOKEN_KEY;
+    private static readonly USER_KEY;
+    private static getStorage;
+    static storeTokens(tokens: AuthResponse): void;
+    static getAccessToken(): string | null;
+    static getRefreshToken(): string | null;
+    static getStoredUser(): User$1 | null;
+    static clearTokens(): void;
+    static isTokenExpired(token: string): boolean;
+    static autoRefreshToken(sdk: SPAPSClient): Promise<boolean>;
+}
+declare class WalletUtils {
+    static detectChainType(address: string): 'solana' | 'ethereum' | 'bitcoin' | null;
+    static isValidAddress(address: string, chainType?: 'solana' | 'ethereum' | 'bitcoin' | 'base'): boolean;
+}
+
+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 };