@solvapay/server 1.0.8-preview.6 → 1.0.8-preview.8

package/dist/src/factory.js

@@ -0,0 +1,215 @@
+/**
+ * SolvaPay Factory
+ *
+ * Main entry point for creating SolvaPay instances with the unified payable API
+ */
+import { createSolvaPayClient } from './client';
+import { SolvaPayPaywall } from './paywall';
+import { HttpAdapter, NextAdapter, McpAdapter, createAdapterHandler } from './adapters';
+import { SolvaPayError, getSolvaPayConfig } from '@solvapay/core';
+import { createVirtualTools } from './virtual-tools';
+import { registerVirtualToolsMcpImpl, } from './register-virtual-tools-mcp';
+/**
+ * Create a SolvaPay instance with paywall protection capabilities.
+ *
+ * This factory function creates a SolvaPay instance that can be used to
+ * protect API endpoints, functions, and MCP tools with usage limits and
+   * purchase checks.
+ *
+ * @param config - Optional configuration object
+ * @param config.apiKey - API key for production use (defaults to `SOLVAPAY_SECRET_KEY` env var)
+ * @param config.apiClient - Custom API client for testing or advanced use cases
+ * @param config.apiBaseUrl - Optional API base URL override
+ * @returns SolvaPay instance with payable() method and API client access
+ *
+ * @example
+ * ```typescript
+ * // Production: Use environment variable (recommended)
+ * const solvaPay = createSolvaPay();
+ *
+ * // Production: Pass API key explicitly
+ * const solvaPay = createSolvaPay({
+ *   apiKey: process.env.SOLVAPAY_SECRET_KEY
+ * });
+ *
+ * // Testing: Use mock client
+ * const solvaPay = createSolvaPay({
+ *   apiClient: mockClient
+ * });
+ *
+ * // Create payable handlers for your product
+ * const payable = solvaPay.payable({
+ *   product: 'prd_myapi',
+ *   plan: 'pln_premium'
+ * });
+ *
+ * // Protect endpoints with framework-specific adapters
+ * app.post('/tasks', payable.http(createTask));      // Express/Fastify
+ * export const POST = payable.next(createTask);      // Next.js App Router
+ * const handler = payable.mcp(createTask);           // MCP servers
+ * ```
+ *
+ * @see {@link SolvaPay} for the returned instance interface
+ * @see {@link CreateSolvaPayConfig} for configuration options
+ * @since 1.0.0
+ */
+export function createSolvaPay(config) {
+    // If no config provided, read from environment variables
+    let resolvedConfig;
+    if (!config) {
+        const envConfig = getSolvaPayConfig();
+        resolvedConfig = {
+            apiKey: envConfig.apiKey,
+            apiBaseUrl: envConfig.apiBaseUrl,
+        };
+    }
+    else {
+        resolvedConfig = config;
+    }
+    // Create or use provided API client
+    const apiClient = resolvedConfig.apiClient ||
+        createSolvaPayClient({
+            apiKey: resolvedConfig.apiKey,
+            apiBaseUrl: resolvedConfig.apiBaseUrl,
+        });
+    // Create paywall instance with debug flag controlled by environment variable
+    const paywall = new SolvaPayPaywall(apiClient, {
+        debug: process.env.SOLVAPAY_DEBUG !== 'false',
+        limitsCacheTTL: resolvedConfig.limitsCacheTTL,
+    });
+    return {
+        // Direct access to API client for advanced operations
+        apiClient,
+        // Common API methods exposed directly for convenience
+        ensureCustomer(customerRef, externalRef, options) {
+            return paywall.ensureCustomer(customerRef, externalRef, options);
+        },
+        createPaymentIntent(params) {
+            if (!apiClient.createPaymentIntent) {
+                throw new SolvaPayError('createPaymentIntent is not available on this API client');
+            }
+            return apiClient.createPaymentIntent(params);
+        },
+        processPaymentIntent(params) {
+            if (!apiClient.processPaymentIntent) {
+                throw new SolvaPayError('processPaymentIntent is not available on this API client');
+            }
+            return apiClient.processPaymentIntent(params);
+        },
+        checkLimits(params) {
+            return apiClient.checkLimits(params);
+        },
+        trackUsage(params) {
+            return apiClient.trackUsage(params);
+        },
+        createCustomer(params) {
+            if (!apiClient.createCustomer) {
+                throw new SolvaPayError('createCustomer is not available on this API client');
+            }
+            return apiClient.createCustomer({ ...params, metadata: params.metadata ?? {} });
+        },
+        getCustomer(params) {
+            return apiClient.getCustomer(params);
+        },
+        createCheckoutSession(params) {
+            return apiClient.createCheckoutSession({
+                customerRef: params.customerRef,
+                productRef: params.productRef,
+                planRef: params.planRef,
+            });
+        },
+        createCustomerSession(params) {
+            return apiClient.createCustomerSession(params);
+        },
+        bootstrapMcpProduct(params) {
+            if (!apiClient.bootstrapMcpProduct) {
+                throw new SolvaPayError('bootstrapMcpProduct is not available on this API client');
+            }
+            return apiClient.bootstrapMcpProduct(params);
+        },
+        configureMcpPlans(productRef, params) {
+            if (!apiClient.configureMcpPlans) {
+                throw new SolvaPayError('configureMcpPlans is not available on this API client');
+            }
+            return apiClient.configureMcpPlans(productRef, params);
+        },
+        getVirtualTools(options) {
+            return createVirtualTools(apiClient, options);
+        },
+        async registerVirtualToolsMcp(server, options) {
+            await registerVirtualToolsMcpImpl(server, apiClient, options);
+        },
+        // Payable API for framework-specific handlers
+        payable(options = {}) {
+            // Resolve product name (support both productRef and product)
+            const product = options.productRef ||
+                options.product ||
+                process.env.SOLVAPAY_PRODUCT ||
+                'default-product';
+            // Resolve plan (support both planRef and plan)
+            const plan = options.planRef || options.plan;
+            const usageType = options.usageType || 'requests';
+            const metadata = { product, plan, usageType };
+            return {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                http(
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                businessLogic, adapterOptions) {
+                    const adapter = new HttpAdapter({
+                        ...adapterOptions,
+                        getCustomerRef: adapterOptions?.getCustomerRef || options.getCustomerRef,
+                    });
+                    const handlerPromise = createAdapterHandler(adapter, paywall, metadata, businessLogic);
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    return async (req, reply) => {
+                        const handler = await handlerPromise;
+                        return handler([req, reply]);
+                    };
+                },
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                next(
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                businessLogic, adapterOptions) {
+                    const adapter = new NextAdapter({
+                        ...adapterOptions,
+                        getCustomerRef: adapterOptions?.getCustomerRef || options.getCustomerRef,
+                    });
+                    const handlerPromise = createAdapterHandler(adapter, paywall, metadata, businessLogic);
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    return async (request, context) => {
+                        const handler = await handlerPromise;
+                        return handler([request, context]);
+                    };
+                },
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                mcp(
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                businessLogic, adapterOptions) {
+                    const adapter = new McpAdapter({
+                        ...adapterOptions,
+                        getCustomerRef: adapterOptions?.getCustomerRef || options.getCustomerRef,
+                    });
+                    const handlerPromise = createAdapterHandler(adapter, paywall, metadata, businessLogic);
+                    return async (args, extra) => {
+                        const handler = await handlerPromise;
+                        return handler(args, extra);
+                    };
+                },
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                async function(
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                businessLogic) {
+                    const getCustomerRef = (args) => {
+                        const configuredRef = options.getCustomerRef?.(args);
+                        if (typeof configuredRef === 'string') {
+                            return configuredRef;
+                        }
+                        return args.auth?.customer_ref || 'anonymous';
+                    };
+                    return paywall.protect(businessLogic, metadata, getCustomerRef);
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=factory.js.map

package/dist/src/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/factory.ts"],"names":[],"mappings":"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"}

package/dist/src/helpers/auth.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Authentication Helper (Core)
+ *
+ * Generic helper for extracting authenticated user information from requests.
+ * Works with standard Web API Request (works everywhere).
+ */
+import type { AuthenticatedUser, ErrorResult } from './types';
+/**
+ * Extract authenticated user information from a standard Web API Request.
+ *
+ * This is a generic, framework-agnostic helper that extracts user ID, email,
+ * and name from authenticated requests. Works with any framework that uses
+ * the standard Web API Request (Express, Fastify, Next.js, Edge Functions, etc.).
+ *
+ * Uses dynamic imports to avoid requiring @solvapay/auth at build time,
+ * making it suitable for edge runtime environments.
+ *
+ * @param request - Standard Web API Request object
+ * @param options - Configuration options
+ * @param options.includeEmail - Whether to extract email from JWT token (default: true)
+ * @param options.includeName - Whether to extract name from JWT token (default: true)
+ * @returns Authenticated user info or error result
+ *
+ * @example
+ * ```typescript
+ * // In an API route handler
+ * export async function GET(request: Request) {
+ *   const userResult = await getAuthenticatedUserCore(request);
+ *
+ *   if (isErrorResult(userResult)) {
+ *     return Response.json(userResult, { status: userResult.status });
+ *   }
+ *
+ *   const { userId, email, name } = userResult;
+ *   // Use user info...
+ * }
+ * ```
+ *
+ * @see {@link AuthenticatedUser} for the return type
+ * @see {@link ErrorResult} for error handling
+ * @since 1.0.0
+ */
+export declare function getAuthenticatedUserCore(request: Request, options?: {
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<AuthenticatedUser | ErrorResult>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/src/helpers/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/helpers/auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,WAAW,CAAC,EAAE,OAAO,CAAA;CACjB,GACL,OAAO,CAAC,iBAAiB,GAAG,WAAW,CAAC,CAiC1C"}

package/dist/src/helpers/auth.js

@@ -0,0 +1,73 @@
+/**
+ * Authentication Helper (Core)
+ *
+ * Generic helper for extracting authenticated user information from requests.
+ * Works with standard Web API Request (works everywhere).
+ */
+import { handleRouteError } from './error';
+/**
+ * Extract authenticated user information from a standard Web API Request.
+ *
+ * This is a generic, framework-agnostic helper that extracts user ID, email,
+ * and name from authenticated requests. Works with any framework that uses
+ * the standard Web API Request (Express, Fastify, Next.js, Edge Functions, etc.).
+ *
+ * Uses dynamic imports to avoid requiring @solvapay/auth at build time,
+ * making it suitable for edge runtime environments.
+ *
+ * @param request - Standard Web API Request object
+ * @param options - Configuration options
+ * @param options.includeEmail - Whether to extract email from JWT token (default: true)
+ * @param options.includeName - Whether to extract name from JWT token (default: true)
+ * @returns Authenticated user info or error result
+ *
+ * @example
+ * ```typescript
+ * // In an API route handler
+ * export async function GET(request: Request) {
+ *   const userResult = await getAuthenticatedUserCore(request);
+ *
+ *   if (isErrorResult(userResult)) {
+ *     return Response.json(userResult, { status: userResult.status });
+ *   }
+ *
+ *   const { userId, email, name } = userResult;
+ *   // Use user info...
+ * }
+ * ```
+ *
+ * @see {@link AuthenticatedUser} for the return type
+ * @see {@link ErrorResult} for error handling
+ * @since 1.0.0
+ */
+export async function getAuthenticatedUserCore(request, options = {}) {
+    try {
+        // Dynamic import to avoid requiring auth package if not needed
+        const { requireUserId, getUserEmailFromRequest, getUserNameFromRequest } = await import('@solvapay/auth');
+        // Get userId from middleware/auth (set by middleware.ts or auth adapter)
+        const userIdOrError = requireUserId(request);
+        if (userIdOrError instanceof Response) {
+            // Convert Response to ErrorResult
+            const clonedResponse = userIdOrError.clone();
+            const body = await clonedResponse.json().catch(() => ({ error: 'Unauthorized' }));
+            return {
+                error: body.error || 'Unauthorized',
+                status: userIdOrError.status,
+                details: body.error || 'Unauthorized',
+            };
+        }
+        const userId = userIdOrError;
+        // Get user email and name from JWT token if requested
+        const email = options.includeEmail !== false ? await getUserEmailFromRequest(request) : null;
+        const name = options.includeName !== false ? await getUserNameFromRequest(request) : null;
+        return {
+            userId,
+            email,
+            name,
+        };
+    }
+    catch (error) {
+        return handleRouteError(error, 'Get authenticated user', 'Authentication failed');
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/src/helpers/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../src/helpers/auth.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,OAAgB,EAChB,UAGI,EAAE;IAEN,IAAI,CAAC;QACH,+DAA+D;QAC/D,MAAM,EAAE,aAAa,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,GAAG,MAAM,MAAM,CACrF,gBAAgB,CACjB,CAAA;QAED,yEAAyE;QACzE,MAAM,aAAa,GAAG,aAAa,CAAC,OAAO,CAAC,CAAA;QAC5C,IAAI,aAAa,YAAY,QAAQ,EAAE,CAAC;YACtC,kCAAkC;YAClC,MAAM,cAAc,GAAG,aAAa,CAAC,KAAK,EAAE,CAAA;YAC5C,MAAM,IAAI,GAAG,MAAM,cAAc,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC,CAAA;YACjF,OAAO;gBACL,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,cAAc;gBACnC,MAAM,EAAE,aAAa,CAAC,MAAM;gBAC5B,OAAO,EAAE,IAAI,CAAC,KAAK,IAAI,cAAc;aACtC,CAAA;QACH,CAAC;QACD,MAAM,MAAM,GAAG,aAAa,CAAA;QAE5B,sDAAsD;QACtD,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,uBAAuB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QAC5F,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QAEzF,OAAO;YACL,MAAM;YACN,KAAK;YACL,IAAI;SACL,CAAA;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,gBAAgB,CAAC,KAAK,EAAE,wBAAwB,EAAE,uBAAuB,CAAC,CAAA;IACnF,CAAC;AACH,CAAC"}

package/dist/src/helpers/checkout.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Checkout Helpers (Core)
+ *
+ * Generic helpers for checkout session operations.
+ * Works with standard Web API Request (works everywhere).
+ */
+import type { SolvaPay } from '../factory';
+import type { ErrorResult } from './types';
+/**
+ * Create checkout session - core implementation
+ *
+ * @param request - Standard Web API Request
+ * @param body - Checkout session parameters
+ * @param options - Configuration options
+ * @returns Checkout session response or error result
+ */
+export declare function createCheckoutSessionCore(request: Request, body: {
+    productRef: string;
+    planRef?: string;
+    returnUrl?: string;
+}, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+    returnUrl?: string;
+}): Promise<{
+    sessionId: string;
+    checkoutUrl: string;
+} | ErrorResult>;
+/**
+ * Create customer session - core implementation
+ *
+ * @param request - Standard Web API Request
+ * @param options - Configuration options
+ * @returns Customer session response or error result
+ */
+export declare function createCustomerSessionCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<{
+    sessionId: string;
+    customerUrl: string;
+} | ErrorResult>;
+//# sourceMappingURL=checkout.d.ts.map

package/dist/src/helpers/checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../../src/helpers/checkout.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAK1C;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE;IACJ,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,EACD,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,SAAS,CAAC,EAAE,MAAM,CAAA;CACd,GACL,OAAO,CACN;IACE,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB,GACD,WAAW,CACd,CA+CA;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,WAAW,CAAC,EAAE,OAAO,CAAA;CACjB,GACL,OAAO,CACN;IACE,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,EAAE,MAAM,CAAA;CACpB,GACD,WAAW,CACd,CAwBA"}

package/dist/src/helpers/checkout.js

@@ -0,0 +1,89 @@
+/**
+ * Checkout Helpers (Core)
+ *
+ * Generic helpers for checkout session operations.
+ * Works with standard Web API Request (works everywhere).
+ */
+import { createSolvaPay } from '../factory';
+import { handleRouteError, isErrorResult } from './error';
+import { syncCustomerCore } from './customer';
+/**
+ * Create checkout session - core implementation
+ *
+ * @param request - Standard Web API Request
+ * @param body - Checkout session parameters
+ * @param options - Configuration options
+ * @returns Checkout session response or error result
+ */
+export async function createCheckoutSessionCore(request, body, options = {}) {
+    try {
+        if (!body.productRef) {
+            return {
+                error: 'Missing required parameter: productRef is required',
+                status: 400,
+            };
+        }
+        const customerResult = await syncCustomerCore(request, {
+            solvaPay: options.solvaPay,
+            includeEmail: options.includeEmail,
+            includeName: options.includeName,
+        });
+        if (isErrorResult(customerResult)) {
+            return customerResult;
+        }
+        const customerRef = customerResult;
+        let returnUrl = body.returnUrl || options.returnUrl;
+        if (!returnUrl) {
+            try {
+                const url = new URL(request.url);
+                returnUrl = url.origin;
+            }
+            catch {
+                // If URL parsing fails, continue without returnUrl
+            }
+        }
+        const solvaPay = options.solvaPay || createSolvaPay();
+        const session = await solvaPay.createCheckoutSession({
+            productRef: body.productRef,
+            customerRef,
+            planRef: body.planRef || undefined,
+            returnUrl: returnUrl,
+        });
+        return {
+            sessionId: session.sessionId,
+            checkoutUrl: session.checkoutUrl,
+        };
+    }
+    catch (error) {
+        return handleRouteError(error, 'Create checkout session', 'Checkout session creation failed');
+    }
+}
+/**
+ * Create customer session - core implementation
+ *
+ * @param request - Standard Web API Request
+ * @param options - Configuration options
+ * @returns Customer session response or error result
+ */
+export async function createCustomerSessionCore(request, options = {}) {
+    try {
+        const customerResult = await syncCustomerCore(request, {
+            solvaPay: options.solvaPay,
+            includeEmail: options.includeEmail,
+            includeName: options.includeName,
+        });
+        if (isErrorResult(customerResult)) {
+            return customerResult;
+        }
+        const customerRef = customerResult;
+        const solvaPay = options.solvaPay || createSolvaPay();
+        const session = await solvaPay.createCustomerSession({
+            customerRef,
+        });
+        return session;
+    }
+    catch (error) {
+        return handleRouteError(error, 'Create customer session', 'Customer session creation failed');
+    }
+}
+//# sourceMappingURL=checkout.js.map

package/dist/src/helpers/checkout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.js","sourceRoot":"","sources":["../../../src/helpers/checkout.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE7C;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAAgB,EAChB,IAIC,EACD,UAKI,EAAE;IAQN,IAAI,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACrB,OAAO;gBACL,KAAK,EAAE,oDAAoD;gBAC3D,MAAM,EAAE,GAAG;aACZ,CAAA;QACH,CAAC;QAED,MAAM,cAAc,GAAG,MAAM,gBAAgB,CAAC,OAAO,EAAE;YACrD,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAA;QAEF,IAAI,aAAa,CAAC,cAAc,CAAC,EAAE,CAAC;YAClC,OAAO,cAAc,CAAA;QACvB,CAAC;QAED,MAAM,WAAW,GAAG,cAAc,CAAA;QAElC,IAAI,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,OAAO,CAAC,SAAS,CAAA;QACnD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;gBAChC,SAAS,GAAG,GAAG,CAAC,MAAM,CAAA;YACxB,CAAC;YAAC,MAAM,CAAC;gBACP,mDAAmD;YACrD,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,cAAc,EAAE,CAAA;QAErD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,qBAAqB,CAAC;YACnD,UAAU,EAAE,IAAI,CAAC,UAAU;YAC3B,WAAW;YACX,OAAO,EAAE,IAAI,CAAC,OAAO,IAAI,SAAS;YAClC,SAAS,EAAE,SAAS;SACrB,CAAC,CAAA;QAEF,OAAO;YACL,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAA;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,gBAAgB,CAAC,KAAK,EAAE,yBAAyB,EAAE,kCAAkC,CAAC,CAAA;IAC/F,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAAgB,EAChB,UAII,EAAE;IAQN,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,MAAM,gBAAgB,CAAC,OAAO,EAAE;YACrD,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAA;QAEF,IAAI,aAAa,CAAC,cAAc,CAAC,EAAE,CAAC;YAClC,OAAO,cAAc,CAAA;QACvB,CAAC;QAED,MAAM,WAAW,GAAG,cAAc,CAAA;QAElC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,cAAc,EAAE,CAAA;QAErD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,qBAAqB,CAAC;YACnD,WAAW;SACZ,CAAC,CAAA;QAEF,OAAO,OAAO,CAAA;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,gBAAgB,CAAC,KAAK,EAAE,yBAAyB,EAAE,kCAAkC,CAAC,CAAA;IAC/F,CAAC;AACH,CAAC"}

package/dist/src/helpers/customer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Customer Helper (Core)
+ *
+ * Generic helper for syncing customers with SolvaPay backend.
+ * Works with standard Web API Request (works everywhere).
+ */
+import type { SolvaPay } from '../factory';
+import type { ErrorResult } from './types';
+/**
+ * Sync customer with SolvaPay backend (ensure customer exists).
+ *
+ * This helper ensures a customer exists in the SolvaPay backend by:
+ * 1. Extracting authenticated user information from the request
+ * 2. Creating or retrieving the customer using the user ID as external reference
+ * 3. Syncing customer data (email, name) if provided
+ *
+ * Uses `externalRef` for consistent lookup and prevents duplicate customers.
+ * The returned customer reference is the SolvaPay backend customer ID.
+ *
+ * @param request - Standard Web API Request object
+ * @param options - Configuration options
+ * @param options.solvaPay - Optional SolvaPay instance (creates new one if not provided)
+ * @param options.includeEmail - Whether to include email in customer data (default: true)
+ * @param options.includeName - Whether to include name in customer data (default: true)
+ * @returns Customer reference (backend customer ID) or error result
+ *
+ * @example
+ * ```typescript
+ * // In an API route handler
+ * export async function POST(request: Request) {
+ *   const customerResult = await syncCustomerCore(request);
+ *
+ *   if (isErrorResult(customerResult)) {
+ *     return Response.json(customerResult, { status: customerResult.status });
+ *   }
+ *
+ *   const customerRef = customerResult;
+ *   // Use customer reference...
+ * }
+ * ```
+ *
+ * @see {@link getAuthenticatedUserCore} for user extraction
+ * @see {@link ErrorResult} for error handling
+ * @since 1.0.0
+ */
+export declare function syncCustomerCore(request: Request, options?: {
+    solvaPay?: SolvaPay;
+    includeEmail?: boolean;
+    includeName?: boolean;
+}): Promise<string | ErrorResult>;
+//# sourceMappingURL=customer.d.ts.map

package/dist/src/helpers/customer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customer.d.ts","sourceRoot":"","sources":["../../../src/helpers/customer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAK1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE;IACP,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,WAAW,CAAC,EAAE,OAAO,CAAA;CACjB,GACL,OAAO,CAAC,MAAM,GAAG,WAAW,CAAC,CAiC/B"}

package/dist/src/helpers/customer.js

@@ -0,0 +1,77 @@
+/**
+ * Customer Helper (Core)
+ *
+ * Generic helper for syncing customers with SolvaPay backend.
+ * Works with standard Web API Request (works everywhere).
+ */
+import { createSolvaPay } from '../factory';
+import { handleRouteError, isErrorResult } from './error';
+import { getAuthenticatedUserCore } from './auth';
+/**
+ * Sync customer with SolvaPay backend (ensure customer exists).
+ *
+ * This helper ensures a customer exists in the SolvaPay backend by:
+ * 1. Extracting authenticated user information from the request
+ * 2. Creating or retrieving the customer using the user ID as external reference
+ * 3. Syncing customer data (email, name) if provided
+ *
+ * Uses `externalRef` for consistent lookup and prevents duplicate customers.
+ * The returned customer reference is the SolvaPay backend customer ID.
+ *
+ * @param request - Standard Web API Request object
+ * @param options - Configuration options
+ * @param options.solvaPay - Optional SolvaPay instance (creates new one if not provided)
+ * @param options.includeEmail - Whether to include email in customer data (default: true)
+ * @param options.includeName - Whether to include name in customer data (default: true)
+ * @returns Customer reference (backend customer ID) or error result
+ *
+ * @example
+ * ```typescript
+ * // In an API route handler
+ * export async function POST(request: Request) {
+ *   const customerResult = await syncCustomerCore(request);
+ *
+ *   if (isErrorResult(customerResult)) {
+ *     return Response.json(customerResult, { status: customerResult.status });
+ *   }
+ *
+ *   const customerRef = customerResult;
+ *   // Use customer reference...
+ * }
+ * ```
+ *
+ * @see {@link getAuthenticatedUserCore} for user extraction
+ * @see {@link ErrorResult} for error handling
+ * @since 1.0.0
+ */
+export async function syncCustomerCore(request, options = {}) {
+    try {
+        // Get authenticated user
+        const userResult = await getAuthenticatedUserCore(request, {
+            includeEmail: options.includeEmail,
+            includeName: options.includeName,
+        });
+        if (isErrorResult(userResult)) {
+            return userResult;
+        }
+        const { userId, email, name } = userResult;
+        // Use provided SolvaPay instance or create new one
+        const solvaPay = options.solvaPay || createSolvaPay();
+        // Use userId as cache key (first param) and externalRef (second param)
+        // The first parameter (customerRef) is used as a cache key
+        // The second parameter (externalRef) is stored on the SolvaPay backend for customer lookup
+        // This ensures consistent lookup and prevents duplicate customers
+        // Pass email and name to ensure correct customer data
+        // Note: Customer lookup deduplication is handled automatically by the SDK
+        // The returned customerRef is the SolvaPay backend customer reference (different from Supabase user ID)
+        const customerRef = await solvaPay.ensureCustomer(userId, userId, {
+            email: email || undefined,
+            name: name || undefined,
+        });
+        return customerRef;
+    }
+    catch (error) {
+        return handleRouteError(error, 'Sync customer', 'Failed to sync customer');
+    }
+}
+//# sourceMappingURL=customer.js.map

package/dist/src/helpers/customer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"customer.js","sourceRoot":"","sources":["../../../src/helpers/customer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,QAAQ,CAAA;AAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgB,EAChB,UAII,EAAE;IAEN,IAAI,CAAC;QACH,yBAAyB;QACzB,MAAM,UAAU,GAAG,MAAM,wBAAwB,CAAC,OAAO,EAAE;YACzD,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAA;QAEF,IAAI,aAAa,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9B,OAAO,UAAU,CAAA;QACnB,CAAC;QAED,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,UAAU,CAAA;QAE1C,mDAAmD;QACnD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,cAAc,EAAE,CAAA;QAErD,uEAAuE;QACvE,2DAA2D;QAC3D,2FAA2F;QAC3F,kEAAkE;QAClE,sDAAsD;QACtD,0EAA0E;QAC1E,wGAAwG;QACxG,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE;YAChE,KAAK,EAAE,KAAK,IAAI,SAAS;YACzB,IAAI,EAAE,IAAI,IAAI,SAAS;SACxB,CAAC,CAAA;QAEF,OAAO,WAAW,CAAA;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,yBAAyB,CAAC,CAAA;IAC5E,CAAC;AACH,CAAC"}

package/dist/src/helpers/error.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Error Handling Helper
+ *
+ * Generic error handling utilities for route helpers
+ */
+import type { ErrorResult } from './types';
+/**
+ * Check if a result is an error result
+ */
+export declare function isErrorResult(result: unknown): result is ErrorResult;
+/**
+ * Handle route errors and convert to ErrorResult
+ */
+export declare function handleRouteError(error: unknown, operationName: string, defaultMessage?: string): ErrorResult;
+//# sourceMappingURL=error.d.ts.map

package/dist/src/helpers/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../../../src/helpers/error.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAE1C;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,WAAW,CAEpE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,OAAO,EACd,aAAa,EAAE,MAAM,EACrB,cAAc,CAAC,EAAE,MAAM,GACtB,WAAW,CAqBb"}