@solvapay/server 1.2.0 → 1.2.1-preview-e89fa52f99b6d0c7bf9834fcf2d1403141051fa0

package/dist/index.d.cts

@@ -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,22 @@ 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 CreditDebitSkipReason = components['schemas']['CreditDebitSkippedResponse']['reason'];
+type CreditDebitResult = components['schemas']['CreditDebitSuccessResponse'] | components['schemas']['CreditDebitSkippedResponse'];
+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 +3201,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 +3226,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 +3272,7 @@ interface SolvaPayClient {
         productRef: string;
         planRef: string;
         customerRef: string;
+        currency?: string;
         idempotencyKey?: string;
     }): Promise<{
         processorPaymentId: string;
@@ -3729,12 +3900,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 {
@@ -3814,6 +3985,7 @@ interface SolvaPay {
         productRef: string;
         planRef: string;
         customerRef: string;
+        currency?: string;
         idempotencyKey?: string;
     }): Promise<{
         processorPaymentId: string;
@@ -3941,19 +4113,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.
      *
@@ -4008,6 +4172,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.
      *
@@ -4182,7 +4350,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)
@@ -4582,7 +4750,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
@@ -4734,6 +4902,7 @@ declare function getCustomerBalanceCore(request: Request, options?: {
 declare function createPaymentIntentCore(request: Request, body: {
     planRef: string;
     productRef: string;
+    currency?: string;
 }, options?: {
     solvaPay?: SolvaPay;
     includeEmail?: boolean;
@@ -5142,11 +5311,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
@@ -5203,4 +5371,4 @@ declare function verifyWebhook({ body, signature, secret, }: {
     secret: string;
 }): WebhookEvent;
 
-export { type ActivatePlanResult, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type LimitResponseWithPlan, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableAllowResult, type PayableFunction, type PayableGateOptions, type PayableGateResult, type PayableOptions, type PayablePaywallResult, type PaymentMethodInfo, type PaywallArgs, type PaywallDecision, PaywallError, type PaywallMetadata, type PaywallState, type PaywallStructuredContent, type ProcessPaymentResult, type ProtectHandlerContext, type PurchaseCheckResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, type TopupProcessResult, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, getAuthenticatedUserCore, getCustomerBalanceCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, syncCustomerCore, trackUsageCore, verifyWebhook, withRetry };
+export { type ActivatePlanResult, type AssignCreditsRequest, type AssignCreditsResponse, type AuthenticatedUser, type ConfigureMcpPlansRequest, type ConfigureMcpPlansResponse, type CreateSolvaPayConfig, type CreditDebitResult, type CreditDebitSkipReason, type CustomerBalanceResult, type CustomerResponseMapped, type CustomerWebhookObject, type ErrorResult, type GetUsageResult, type HttpAdapterOptions, type LimitActivationBalance, type LimitActivationProduct, type LimitPlanSummary, type LimitResponseWithPlan, type McpBootstrapPlanInput, type McpBootstrapRequest, type McpBootstrapResponse, type McpServerLike, type McpToolPlanMappingInput, type NextAdapterOptions, type OneTimePurchaseInfo, type PayableAllowResult, type PayableFunction, type PayableGateOptions, type PayableGateResult, type PayableOptions, type PayablePaywallResult, type PaymentMethodInfo, type PaywallArgs, type PaywallDecision, PaywallError, type PaywallMetadata, type PaywallState, type PaywallStructuredContent, type ProcessPaymentResult, type ProtectHandlerContext, type PurchaseCheckResult, type RegisterVirtualToolsMcpOptions, type RetryOptions, type SdkMerchantResponse, type SdkProductResponse, type ServerClientOptions, type SolvaPay, type SolvaPayClient, type ToolPlanMappingInput, type TopupProcessResult, type TrackUsageBulkRequest, type TrackUsageBulkResponse, type TrackUsageRequest, type TrackUsageResponse, VIRTUAL_TOOL_DEFINITIONS, type VirtualToolDefinition, type VirtualToolsOptions, type WebhookEvent, type WebhookEventForType, type WebhookEventObjectMap, type WebhookEventType, type WebhookProduct, activatePlanCore, buildGateMessage, buildNudgeMessage, buildPaywallGate, cancelPurchaseCore, checkLimitsCore, checkPurchaseCore, classifyPaywallState, type components, createCheckoutSessionCore, createCustomerSessionCore, createPaymentIntentCore, createSolvaPay, createSolvaPayClient, createTopupPaymentIntentCore, createVirtualTools, getAuthenticatedUserCore, getCustomerBalanceCore, getMerchantCore, getPaymentMethodCore, getProductCore, getUsageCore, handleRouteError, isErrorResult, isPaywallStructuredContent, jsonSchemaToZodRawShape, listPlansCore, paywallErrorToClientPayload, processPaymentIntentCore, processTopupPaymentIntentCore, reactivatePurchaseCore, registerVirtualToolsMcpImpl, syncCustomerCore, trackUsageCore, verifyWebhook, withRetry };