@solvapay/server 1.2.0 → 1.2.1-preview-e89fa52f99b6d0c7bf9834fcf2d1403141051fa0

package/README.md

@@ -23,7 +23,10 @@ import { createSolvaPay } from '@solvapay/server'
 const solvaPay = createSolvaPay({ apiKey: process.env.SOLVAPAY_SECRET_KEY })
 const payable = solvaPay.payable({ product: 'prd_YOUR_PRODUCT' })
 
-app.post('/tasks', payable.http(async args => ({ id: 'task_1', ...args })))
+app.post(
+  '/tasks',
+  payable.http(async args => ({ id: 'task_1', ...args })),
+)
 ```
 
 Guide: [Express integration](https://docs.solvapay.com/sdks/typescript/guides/express)
@@ -68,12 +71,12 @@ server.setRequestHandler(..., payable.mcp(handler)) // MCP (low-level)
 const fn = await payable.function(handler)          // Direct / jobs / tests
 ```
 
-| Adapter | Use when |
-| --- | --- |
-| `payable.http()` | Express, Fastify, traditional HTTP |
-| `payable.next()` | Next.js App Router |
-| `payable.mcp()` | MCP tool handlers (low-level) |
-| `payable.function()` | Tests, cron, non-HTTP contexts |
+| Adapter              | Use when                           |
+| -------------------- | ---------------------------------- |
+| `payable.http()`     | Express, Fastify, traditional HTTP |
+| `payable.next()`     | Next.js App Router                 |
+| `payable.mcp()`      | MCP tool handlers (low-level)      |
+| `payable.function()` | Tests, cron, non-HTTP contexts     |
 
 ### Authentication
 
@@ -109,7 +112,9 @@ Guide: [MCP](https://docs.solvapay.com/sdks/typescript/guides/mcp)
 `createSolvaPayClient` implements:
 
 - `checkLimits(params)` — usage limits; auto-enrolls on first call for free default plans
-- `trackUsage(params)` — metered billing
+- `trackUsage(params)` — metered billing; returns the recorded usage reference and any credit debit result
+- `trackUsageBulk({ events })` — record several metered usage events in one request
+- `assignCredits(params)` — grant credits to a customer balance with optional idempotency
 - `createCustomer(params)` / `getCustomer(params)` — customer lifecycle
 
 Full reference: [Server SDK docs](https://docs.solvapay.com/sdks/typescript/intro)

package/dist/edge.d.ts

@@ -29,6 +29,15 @@ interface components {
              * @example usd
              */
             defaultCurrency?: string;
+            /**
+             * Full set of currencies a customer may pay credit topups in, including the default currency. Omitted/single-entry means single-currency behavior.
+             * @example [
+             *       "USD",
+             *       "EUR",
+             *       "GBP"
+             *     ]
+             */
+            supportedTopupCurrencies?: string[];
             /**
              * Descriptor appearing on the customer card statement
              * @example ACME INC
@@ -246,6 +255,33 @@ interface components {
              */
             checkoutUrl: string;
         };
+        PlanPricingOptionDto: {
+            /**
+             * ISO 4217 currency code
+             * @example USD
+             */
+            currency: string;
+            /**
+             * Price in smallest currency unit (e.g. cents)
+             * @example 2999
+             */
+            price: number;
+            /**
+             * Base price in smallest currency unit (hybrid plans)
+             * @example 1999
+             */
+            basePrice?: number;
+            /**
+             * One-time setup fee in smallest currency unit
+             * @example 500
+             */
+            setupFee?: number;
+            /**
+             * Whether this is the default currency option for the plan
+             * @example true
+             */
+            default?: boolean;
+        };
         Plan: {
             /**
              * Plan type exposed in SDK
@@ -283,6 +319,8 @@ interface components {
              * @example USD
              */
             currency: string;
+            /** @description Per-currency price options for this plan */
+            pricingOptions?: components["schemas"]["PlanPricingOptionDto"][];
             /**
              * Currency symbol (derived from currency)
              * @example $
@@ -376,6 +414,13 @@ interface components {
             price?: number;
             creditsPerUnit?: number;
             currency?: string;
+            pricingOptions?: {
+                currency: string;
+                price: number;
+                basePrice?: number;
+                setupFee?: number;
+                default?: boolean;
+            }[];
             /** @enum {string} */
             billingModel?: "pre-paid" | "post-paid";
             freeUnits?: number;
@@ -414,6 +459,13 @@ interface components {
             price?: number;
             creditsPerUnit?: number;
             currency?: string;
+            pricingOptions?: {
+                currency: string;
+                price: number;
+                basePrice?: number;
+                setupFee?: number;
+                default?: boolean;
+            }[];
             /** @enum {string} */
             billingModel?: "pre-paid" | "post-paid";
             freeUnits?: number;
@@ -658,6 +710,13 @@ interface components {
                 name: string;
                 price: number;
                 currency: string;
+                pricingOptions?: {
+                    currency: string;
+                    price: number;
+                    basePrice?: number;
+                    setupFee?: number;
+                    default?: boolean;
+                }[];
                 /** @enum {string} */
                 billingCycle?: "weekly" | "monthly" | "quarterly" | "yearly" | "custom";
                 /** @enum {string} */
@@ -726,6 +785,13 @@ interface components {
                 name: string;
                 price: number;
                 currency: string;
+                pricingOptions?: {
+                    currency: string;
+                    price: number;
+                    basePrice?: number;
+                    setupFee?: number;
+                    default?: boolean;
+                }[];
                 /** @enum {string} */
                 billingCycle?: "weekly" | "monthly" | "quarterly" | "yearly" | "custom";
                 /** @enum {string} */
@@ -759,6 +825,52 @@ interface components {
         CloneProductDto: {
             name?: string;
         };
+        CreditDebitSuccessResponse: {
+            /** @enum {number} */
+            debited: true;
+            /**
+             * Credits debited for this usage event
+             * @example 10
+             */
+            amount: number;
+            /**
+             * Estimated remaining units after debit
+             * @example 99
+             */
+            unitsRemaining: number;
+        };
+        CreditDebitSkippedResponse: {
+            /** @enum {number} */
+            debited: false;
+            /**
+             * Reason no credit debit was recorded
+             * @example duplicate
+             * @enum {string}
+             */
+            reason: "duplicate" | "no_product_ref" | "customer_not_found" | "no_active_purchase" | "plan_not_credit_based";
+        };
+        UsageRecordResponse: {
+            /** @example true */
+            success: boolean;
+            /** @example usage_A1B2C3D4 */
+            reference: string;
+            creditDebit?: components["schemas"]["CreditDebitSuccessResponse"] | components["schemas"]["CreditDebitSkippedResponse"];
+        };
+        BulkUsageResultResponse: {
+            /** @example usage_A1B2C3D4 */
+            reference: string;
+            creditDebit?: components["schemas"]["CreditDebitSuccessResponse"] | components["schemas"]["CreditDebitSkippedResponse"];
+        };
+        BulkUsageResponse: {
+            /** @example true */
+            success: boolean;
+            /**
+             * Number of usage events inserted
+             * @example 2
+             */
+            inserted: number;
+            results: components["schemas"]["BulkUsageResultResponse"][];
+        };
         CreateUsageRequest: {
             customerRef: string;
             /**
@@ -1028,6 +1140,8 @@ interface components {
             creditsPerUnit?: number;
             billingModel?: string;
             billingCycle?: string;
+            /** @description Per-currency price options for this plan */
+            pricingOptions?: components["schemas"]["PlanPricingOptionDto"][];
         };
         LimitBalanceDto: {
             /** @description Credit balance in mils */
@@ -1111,6 +1225,22 @@ interface components {
             };
             externalRef?: string;
         };
+        GrantCustomerCreditsRequest: {
+            credits: number;
+            reason?: string;
+        };
+        GrantCustomerCreditsResponse: {
+            /** @description Whether the grant was recorded */
+            success: boolean;
+            /** @description Customer reference identifier */
+            customerRef: string;
+            /** @description Granted credit amount */
+            credits: number;
+            /** @description Customer credit balance after the grant */
+            balance: number;
+            /** @description Machine-readable grant reason */
+            reason?: string;
+        };
         CreateCustomerSessionRequest: {
             customerRef: string;
             productRef?: string;
@@ -2014,12 +2144,7 @@ interface operations {
                     [name: string]: unknown;
                 };
                 content: {
-                    "application/json": {
-                        /** @example true */
-                        success?: boolean;
-                        /** @example usage_A1B2C3D4 */
-                        reference?: string;
-                    };
+                    "application/json": components["schemas"]["UsageRecordResponse"];
                 };
             };
             /** @description Validation failed */
@@ -2049,7 +2174,9 @@ interface operations {
                 headers: {
                     [name: string]: unknown;
                 };
-                content?: never;
+                content: {
+                    "application/json": components["schemas"]["BulkUsageResponse"];
+                };
             };
             /** @description Validation failed */
             400: {
@@ -2581,6 +2708,43 @@ interface operations {
             };
         };
     };
+    CustomerSdkController_grantCredits: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Provider-scoped idempotency key for safe grant retries */
+                "Idempotency-Key"?: string;
+            };
+            path: {
+                /** @description Customer reference identifier */
+                reference: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["GrantCustomerCreditsRequest"];
+            };
+        };
+        responses: {
+            /** @description Credits granted successfully */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["GrantCustomerCreditsResponse"];
+                };
+            };
+            /** @description Customer not found */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+        };
+    };
     CustomerSdkController_createCustomerSession: {
         parameters: {
             query?: never;
@@ -2974,6 +3138,20 @@ type SdkMerchantResponse = components['schemas']['SdkMerchantResponseDto'];
 type SdkPlatformConfigResponse = components['schemas']['SdkPlatformConfigResponseDto'];
 /** SDK-facing product projection. Sourced from the existing OpenAPI spec. */
 type SdkProductResponse = components['schemas']['SdkProductResponse'];
+type TrackUsageRequest = Omit<Partial<components['schemas']['CreateUsageRequest']>, 'customerRef' | 'metadata'> & {
+    customerRef: string;
+    metadata?: Record<string, unknown>;
+};
+type TrackUsageResponse = components['schemas']['UsageRecordResponse'];
+interface TrackUsageBulkRequest {
+    events: TrackUsageRequest[];
+}
+type TrackUsageBulkResponse = components['schemas']['BulkUsageResponse'];
+type AssignCreditsRequest = components['schemas']['GrantCustomerCreditsRequest'] & {
+    customerRef: string;
+    idempotencyKey?: string;
+};
+type AssignCreditsResponse = components['schemas']['GrantCustomerCreditsResponse'];
 type McpBootstrapPlanInput = NonNullable<components['schemas']['McpBootstrapDto']['plans']>[number];
 type ToolPlanMappingInput = NonNullable<components['schemas']['McpBootstrapDto']['tools']>[number];
 type McpBootstrapRequest = components['schemas']['McpBootstrapDto'];
@@ -3021,19 +3199,8 @@ interface ConfigureMcpPlansResponse {
  */
 interface SolvaPayClient {
     checkLimits(params: CheckLimitsRequest): Promise<LimitResponseWithPlan>;
-    trackUsage(params: {
-        customerRef: string;
-        actionType?: 'transaction' | 'api_call' | 'hour' | 'email' | 'storage' | 'custom';
-        units?: number;
-        outcome?: 'success' | 'paywall' | 'fail';
-        productRef?: string;
-        purchaseRef?: string;
-        description?: string;
-        metadata?: Record<string, unknown>;
-        duration?: number;
-        timestamp?: string;
-        idempotencyKey?: string;
-    }): Promise<void>;
+    trackUsage(params: TrackUsageRequest): Promise<TrackUsageResponse>;
+    trackUsageBulk?(params: TrackUsageBulkRequest): Promise<TrackUsageBulkResponse>;
     createCustomer?(params: components['schemas']['CreateCustomerRequest']): Promise<{
         customerRef: string;
     }>;
@@ -3057,6 +3224,7 @@ interface SolvaPayClient {
         externalRef?: string;
         email?: string;
     }): Promise<CustomerResponseMapped>;
+    assignCredits?(params: AssignCreditsRequest): Promise<AssignCreditsResponse>;
     /**
      * SDK-facing merchant identity (GET /v1/sdk/merchant).
      * Returns the subset of provider fields safe for browser consumption —
@@ -3102,6 +3270,7 @@ interface SolvaPayClient {
         productRef: string;
         planRef: string;
         customerRef: string;
+        currency?: string;
         idempotencyKey?: string;
     }): Promise<{
         processorPaymentId: string;
@@ -3768,12 +3937,12 @@ interface PayableFunction {
  * const solvaPay = createSolvaPay();
  *
  * // Create payable handlers
-   * const payable = solvaPay.payable({ product: 'prd_myapi' });
-   *
-   * // Manage customers
-   * const customerRef = await solvaPay.ensureCustomer('user_123', 'user_123', {
-   *   email: 'user@example.com'
-   * });
+ * const payable = solvaPay.payable({ product: 'prd_myapi' });
+ *
+ * // Manage customers
+ * const customerRef = await solvaPay.ensureCustomer('user_123', 'user_123', {
+ *   email: 'user@example.com'
+ * });
  * ```
  */
 interface SolvaPay {
@@ -3853,6 +4022,7 @@ interface SolvaPay {
         productRef: string;
         planRef: string;
         customerRef: string;
+        currency?: string;
         idempotencyKey?: string;
     }): Promise<{
         processorPaymentId: string;
@@ -3980,19 +4150,11 @@ interface SolvaPay {
      * });
      * ```
      */
-    trackUsage(params: {
-        customerRef: string;
-        actionType?: 'transaction' | 'api_call' | 'hour' | 'email' | 'storage' | 'custom';
-        units?: number;
-        outcome?: 'success' | 'paywall' | 'fail';
-        productRef?: string;
-        purchaseRef?: string;
-        description?: string;
-        metadata?: Record<string, unknown>;
-        duration?: number;
-        timestamp?: string;
-        idempotencyKey?: string;
-    }): Promise<void>;
+    trackUsage(params: TrackUsageRequest): Promise<TrackUsageResponse>;
+    /**
+     * Track usage events in bulk.
+     */
+    trackUsageBulk(params: TrackUsageBulkRequest): Promise<TrackUsageBulkResponse>;
     /**
      * Create a new customer in SolvaPay backend.
      *
@@ -4047,6 +4209,10 @@ interface SolvaPay {
         customerRef?: string;
         externalRef?: string;
     }): Promise<CustomerResponseMapped>;
+    /**
+     * Assign credits to a customer balance.
+     */
+    assignCredits(params: AssignCreditsRequest): Promise<AssignCreditsResponse>;
     /**
      * Get credits for a customer.
      *
@@ -4221,7 +4387,7 @@ interface SolvaPay {
  *
  * 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.
+ * purchase checks.
  *
  * @param config - Optional configuration object
  * @param config.apiKey - API key for production use (defaults to `SOLVAPAY_SECRET_KEY` env var)
@@ -4535,7 +4701,7 @@ declare function handleRouteError(error: unknown, operationName: string, default
  * the standard Web API Request (Express, Fastify, Next.js, Edge Functions, etc.).
  *
  * Resolution order:
- * 1. `x-user-id` header — set by Next.js-style middleware (unchanged).
+ * 1. `SOLVAPAY_USER_ID_HEADER` header — set by Next.js-style middleware (unchanged).
  * 2. `Authorization: Bearer <jwt>` — verified via HS256 when a secret is
  *    configured (`SOLVAPAY_JWT_SECRET` or `SUPABASE_JWT_SECRET`), or
  *    unverified-decoded when no secret is configured. The unverified path
@@ -4687,6 +4853,7 @@ declare function getCustomerBalanceCore(request: Request, options?: {
 declare function createPaymentIntentCore(request: Request, body: {
     planRef: string;
     productRef: string;
+    currency?: string;
 }, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
@@ -5095,11 +5262,10 @@ declare function trackUsageCore(request: Request, body: {
     productRef?: string;
     description?: string;
     metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
 }, options?: {
     solvaPay?: SolvaPay;
-}): Promise<{
-    success: true;
-} | ErrorResult>;
+}): Promise<TrackUsageResponse | ErrorResult>;
 
 /**
  * SolvaPay Server SDK - Edge Runtime Entry Point