@solvapay/server 2.1.0 → 2.2.0-preview-57b934dfcf7afd484b63b497eef3bf1599c0b597

package/dist/edge.d.ts

@@ -17,7 +17,7 @@ interface components {
             message?: string;
             purchaseRef?: string;
             /** @enum {string} */
-            status: 'activated' | 'already_active' | 'topup_required' | 'payment_required' | 'invalid';
+            status: 'activated' | 'already_active' | 'already_purchased' | 'topup_required' | 'payment_required' | 'invalid';
         };
         AttachBusinessDetailsResponse: {
             /** @description Calculated tax breakdown */
@@ -247,7 +247,7 @@ interface components {
              * Tax ID type
              * @enum {string}
              */
-            taxIdType?: 'eu_vat' | 'gb_vat' | 'us_ein';
+            taxIdType?: 'ae_trn' | 'al_tin' | 'am_tin' | 'ao_tin' | 'au_abn' | 'aw_tin' | 'az_tin' | 'ba_tin' | 'bb_tin' | 'bd_bin' | 'bf_ifu' | 'bh_vat' | 'bj_ifu' | 'bs_tin' | 'by_tin' | 'ca_gst_hst' | 'cd_nif' | 'ch_vat' | 'cl_tin' | 'cm_niu' | 'co_nit' | 'cr_tin' | 'cv_nif' | 'ec_ruc' | 'eg_tin' | 'et_tin' | 'eu_vat' | 'gb_vat' | 'ge_vat' | 'gn_nif' | 'hk_br' | 'id_npwp' | 'in_gst' | 'is_vat' | 'jp_trn' | 'ke_pin' | 'kg_tin' | 'kh_tin' | 'kr_brn' | 'kz_bin' | 'la_tin' | 'li_vat' | 'lk_vat' | 'ma_vat' | 'md_vat' | 'me_pib' | 'mk_vat' | 'mr_nif' | 'mx_rfc' | 'my_sst' | 'ng_tin' | 'no_vat' | 'np_pan' | 'nz_gst' | 'om_vat' | 'pe_ruc' | 'ph_tin' | 'rs_pib' | 'ru_inn' | 'sa_vat' | 'sg_gst' | 'sn_ninea' | 'sr_fin' | 'th_vat' | 'tj_tin' | 'tr_tin' | 'tw_vat' | 'tz_vat' | 'ua_vat' | 'ug_tin' | 'us_ein' | 'uy_ruc' | 'uz_vat' | 'vn_tin' | 'za_vat' | 'zm_tin' | 'zw_tin';
         };
         CancelPurchaseRequest: {
             reason?: string;
@@ -645,7 +645,13 @@ interface components {
             /** @enum {number} */
             debited: true;
             /**
-             * Estimated remaining units after debit
+             * How many metered items the remaining credit balance still covers
+             * @example 99
+             */
+            remainingUnits: number;
+            /**
+             * @deprecated
+             * @description Deprecated alias of remainingUnits. Prefer remainingUnits.
              * @example 99
              */
             unitsRemaining: number;
@@ -724,7 +730,7 @@ interface components {
              */
             name: string;
             /** @description Active purchases */
-            purchases?: components['schemas']['PurchaseInfo'][];
+            purchases?: components['schemas']['SdkPurchaseResponse'][];
             /**
              * Customer reference identifier
              * @example cus_3c4d5e6f7g8h
@@ -793,25 +799,30 @@ interface components {
         LimitBalanceDto: {
             /** @description Credit balance in credits (100 credits = 1 minor currency unit) */
             creditBalance: number;
-            /** @description Credits per usage unit */
+            /** @description Credits deducted per metered item (wallet coverage: remainingUnits = balance / creditsPerUnit) */
             creditsPerUnit: number;
             currency: string;
-            /** @description Estimated whole units remaining from prepaid credit balance */
+            /** @description How many metered items the credit balance still covers (`balance / creditsPerUnit`) */
             remainingUnits?: number;
         };
         LimitPlanItemDto: {
             /** @description Derived billing cycle */
             billingCycle?: string;
-            /** @description Per-unit charge in minor units (usage-based plans) */
+            /**
+             * @deprecated
+             * @description Deprecated alias of perUnitChargeMinor. Same minor-units value — not credits. Prefer perUnitChargeMinor.
+             */
             creditsPerUnit?: number;
             currency: string;
-            /** @description Derived included units for the metered allowance */
+            /** @description Derived included allowance for the metered meter. `0` is the unlimited sentinel (`LimitOption.cap === 0`). */
             freeUnits?: number;
             name?: string;
             /** @description Composable pricing options for this plan */
             options?: {
                 [key: string]: unknown;
             }[];
+            /** @description Per-request charge in minor currency units (usage-based plans) */
+            perUnitChargeMinor?: number;
             /** @description Headline price in smallest currency unit (e.g. cents) */
             price: number;
             reference: string;
@@ -842,7 +853,7 @@ interface components {
             confirmationUrl?: string;
             /** @description Credit balance in credits (100 credits = 1 minor currency unit), for pre-paid usage-based plans */
             creditBalance?: number;
-            /** @description Credits per usage unit (for pre-paid usage-based plans) */
+            /** @description Credits deducted per metered item (for prepaid usage-based plans) */
             creditsPerUnit?: number;
             /** @description ISO 4217 currency code for credit fields */
             currency?: string;
@@ -1057,11 +1068,18 @@ interface components {
              * @example 2025-10-27T10:00:00Z
              */
             completedAt: string;
+            /** @description Created at */
+            createdAt: string;
             /**
              * ISO 4217 currency code of the customer-facing charge
              * @example USD
              */
             currency: string;
+            /**
+             * Customer reference
+             * @example cus_3C4D5E6F
+             */
+            customerRef: string;
             /**
              * Product reference
              * @example prd_abc123
@@ -1189,7 +1207,7 @@ interface components {
             type: 'one-time';
         };
         ProcessPaymentSucceededRecurring: {
-            purchase: components['schemas']['PurchaseInfo'];
+            purchase: components['schemas']['SdkPurchaseResponse'];
             /**
              * discriminator enum property added by openapi-typescript
              * @enum {string}
@@ -1227,75 +1245,6 @@ interface components {
              */
             validityPeriod?: number;
         };
-        PurchaseInfo: {
-            /**
-             * Amount in USD cents (normalised for aggregation)
-             * @example 9900
-             */
-            amount: number;
-            /**
-             * Reason for cancellation
-             * @example Customer request
-             */
-            cancellationReason?: string;
-            /**
-             * When purchase was cancelled
-             * @example 2025-10-28T10:00:00Z
-             */
-            cancelledAt?: string;
-            /**
-             * ISO 4217 currency code of the customer-facing charge
-             * @example GBP
-             */
-            currency: string;
-            /**
-             * End date of purchase
-             * @example 2025-11-27T10:00:00Z
-             */
-            endDate?: string;
-            /**
-             * Exchange rate from original currency to USD
-             * @example 1.32
-             */
-            exchangeRate?: number;
-            /**
-             * Original amount in the payment currency (minor units)
-             * @example 7500
-             */
-            originalAmount?: number;
-            /**
-             * Plan reference from the plan snapshot, for reliable plan matching
-             * @example pln_abc123
-             */
-            planRef?: string;
-            /** @description Snapshot of the plan at time of purchase */
-            planSnapshot?: Record<string, never>;
-            /**
-             * Product name
-             * @example API Gateway Manager
-             */
-            productName: string;
-            /**
-             * Product reference
-             * @example prd_abc123
-             */
-            productRef?: string;
-            /**
-             * Purchase reference
-             * @example pur_1A2B3C4D
-             */
-            reference: string;
-            /**
-             * Start date
-             * @example 2025-10-27T10:00:00Z
-             */
-            startDate: string;
-            /**
-             * Purchase status
-             * @example active
-             */
-            status: string;
-        };
         PutAutoRechargeSdkDto: {
             currency: string;
             /** Format: email */
@@ -1605,6 +1554,11 @@ interface components {
             features?: {
                 [key: string]: unknown;
             } | null;
+            /**
+             * Whether the frozen plan meters usage
+             * @example true
+             */
+            isMetered?: boolean;
             /**
              * Plan name captured at purchase time
              * @example Pro Monthly
@@ -1714,14 +1668,20 @@ interface components {
              * @enum {string}
              */
             billingCycle?: 'weekly' | 'monthly' | 'quarterly' | 'yearly';
-            /** @description Cancellation reason */
+            /**
+             * Reason for cancellation
+             * @example Customer request
+             */
             cancellationReason?: string;
-            /** @description Cancelled at */
+            /**
+             * When purchase was cancelled
+             * @example 2025-10-28T10:00:00Z
+             */
             cancelledAt?: string;
             /** @description Created at */
             createdAt: string;
             /**
-             * Original payment currency code
+             * ISO 4217 currency code of the customer-facing charge
              * @example GBP
              */
             currency: string;
@@ -1735,15 +1695,18 @@ interface components {
              * @example cus_3C4D5E6F
              */
             customerRef: string;
-            /** @description End date */
+            /**
+             * End date of purchase
+             * @example 2025-11-27T10:00:00Z
+             */
             endDate?: string;
             /**
              * Exchange rate from original currency to USD
-             * @example 1.3082
+             * @example 1.32
              */
             exchangeRate?: number;
             /**
-             * Is recurring
+             * Whether the purchase is recurring
              * @example true
              */
             isRecurring: boolean;
@@ -1760,13 +1723,18 @@ interface components {
              */
             origin?: 'paid' | 'free_default' | 'manual' | 'one_time' | 'credit_topup' | 'admin_assignment';
             /**
-             * Original amount in the payment currency (cents/pence)
-             * @example 10000
+             * Original amount in the payment currency (minor units)
+             * @example 7500
              */
             originalAmount?: number;
             /** @description Paid at timestamp */
             paidAt?: string;
-            /** @description Plan snapshot at time of purchase (null for credit topups) */
+            /**
+             * Plan reference from the plan snapshot, for reliable plan matching
+             * @example pln_abc123
+             */
+            planRef?: string;
+            /** @description Snapshot of the plan at time of purchase */
             planSnapshot?: components['schemas']['SdkPlanSnapshotDto'];
             /**
              * Product name
@@ -1775,7 +1743,7 @@ interface components {
             productName?: string;
             /**
              * Product reference
-             * @example prd_1A2B3C4D
+             * @example prd_abc123
              */
             productRef?: string;
             /**
@@ -1788,7 +1756,10 @@ interface components {
              * @example false
              */
             requiresPayment?: boolean;
-            /** @description Start date */
+            /**
+             * Start date
+             * @example 2025-10-27T10:00:00Z
+             */
             startDate: string;
             /**
              * Purchase status
@@ -1803,6 +1774,8 @@ interface components {
             currency: string;
             /** @description Whether tax is included in the listed price */
             inclusive: boolean;
+            /** @description True when Stripe reports taxability_reason not_collecting (no registration) */
+            notRegistered?: boolean;
             /** @description Pre-tax amount in minor units */
             subtotal: number;
             /** @description Tax amount in minor units */
@@ -1817,7 +1790,7 @@ interface components {
             /** @description Total amount in minor units */
             total: number;
             /** @enum {string} */
-            treatment: 'reverse_charge' | 'standard' | 'none' | 'not_collecting';
+            treatment: 'reverse_charge' | 'standard' | 'none' | 'not_collecting' | 'not_supported';
         };
         UpdateCustomerRequest: {
             description?: string;
@@ -1971,7 +1944,7 @@ interface components {
              */
             overageCost: number;
             /**
-             * Units exceeding the plan limit
+             * Units exceeding the plan included amount
              * @example 0
              */
             overageUnits: number;
@@ -3849,6 +3822,8 @@ type WebhookEvent = {
  * Types related to the SolvaPay API client and backend communication.
  */
 
+/** SDK purchase row. Generated from the OpenAPI `SdkPurchaseResponse` schema. */
+type PurchaseInfo = components['schemas']['SdkPurchaseResponse'];
 type AttachBusinessDetailsParams = {
     paymentIntentId: string;
     customerRef?: string;
@@ -3890,8 +3865,7 @@ type LimitResponseWithPlan = components['schemas']['LimitResponse'] & {
 /**
  * Extended CustomerResponse with proper field mapping
  *
- * Note: The backend API returns purchases as PurchaseInfo objects.
- * Additional fields (paidAt, nextBillingDate) may be present in the response.
+ * Note: The backend API returns purchases as SdkPurchaseResponse objects.
  */
 type CustomerResponseMapped = {
     customerRef: string;
@@ -3899,21 +3873,20 @@ type CustomerResponseMapped = {
     name?: string;
     externalRef?: string;
     plan?: string;
-    purchases?: Array<components['schemas']['PurchaseInfo'] & {
-        paidAt?: string;
-        nextBillingDate?: string;
-    }>;
+    purchases?: PurchaseInfo[];
 };
 /**
  * One-time purchase information returned from payment processing
  */
 interface OneTimePurchaseInfo {
     reference: string;
+    customerRef: string;
     productRef?: string;
     amount: number;
     currency: string;
     creditsAdded?: number;
     completedAt: string;
+    createdAt: string;
 }
 /**
  * Result from processing a payment intent.
@@ -3933,7 +3906,7 @@ interface OneTimePurchaseInfo {
 type ProcessPaymentResult = {
     status: 'succeeded';
     type: 'recurring';
-    purchase: components['schemas']['PurchaseInfo'];
+    purchase: PurchaseInfo;
 } | {
     status: 'succeeded';
     type: 'one-time';
@@ -4241,10 +4214,10 @@ interface SolvaPayClient {
     cancelPurchase?(params: {
         purchaseRef: string;
         reason?: string;
-    }): Promise<components['schemas']['PurchaseInfo']>;
+    }): Promise<PurchaseInfo>;
     reactivatePurchase?(params: {
         purchaseRef: string;
-    }): Promise<components['schemas']['PurchaseInfo']>;
+    }): Promise<PurchaseInfo>;
     processPaymentIntent?(params: {
         paymentIntentId: string;
         productRef?: string;
@@ -6257,26 +6230,7 @@ interface PurchaseCheckResult {
     customerRef: string;
     email?: string;
     name?: string;
-    purchases: Array<{
-        reference: string;
-        productName?: string;
-        productRef?: string;
-        status?: string;
-        startDate?: string;
-        planSnapshot?: {
-            meterId?: string;
-            limit?: number;
-            freeUnits?: number;
-        };
-        usage?: {
-            used?: number;
-            overageUnits?: number;
-            overageCost?: number;
-            periodStart?: string;
-            periodEnd?: string;
-        };
-        [key: string]: unknown;
-    }>;
+    purchases: PurchaseInfo[];
 }
 declare function checkPurchaseCore(request: Request, options?: {
     solvaPay?: SolvaPay;
@@ -6305,8 +6259,12 @@ interface GetUsageResult {
 /**
  * Fetch the authenticated customer's usage snapshot for the active purchase.
  *
- * Derives the values from `checkPurchaseCore` — no extra backend call.
- * Returns `null` values when no usage-based plan is active.
+ * Consumption (`used`, period window) comes from `checkPurchaseCore`. The cap
+ * (`total`, `remaining`, `meterRef`) comes from `checkLimits` — the plan
+ * snapshot no longer carries `limit` or `meterRef` on the wire, so a metered
+ * plan costs one extra backend call. Non-metered plans skip it.
+ *
+ * Returns `null` values when no metered plan is active.
  */
 declare function getUsageCore(request: Request, options?: {
     solvaPay?: SolvaPay;

package/dist/edge.js

@@ -3286,21 +3286,40 @@ async function getUsageCore(request, options = {}) {
       percentUsed: null
     };
   }
-  const snap = activePurchase.planSnapshot;
   const usage = activePurchase.usage;
-  const meterRef = snap?.meterRef ?? snap?.meterId ?? null;
-  const total = typeof snap?.limit === "number" ? snap.limit : null;
   const used = typeof usage?.used === "number" ? usage.used : 0;
-  const remaining = total !== null ? Math.max(0, total - used) : null;
+  const period = {
+    ...usage?.periodStart ? { periodStart: usage.periodStart } : {},
+    ...usage?.periodEnd ? { periodEnd: usage.periodEnd } : {}
+  };
+  const isMetered = activePurchase.planSnapshot?.isMetered === true;
+  if (!isMetered || !activePurchase.productRef) {
+    return {
+      meterRef: null,
+      total: null,
+      used,
+      remaining: null,
+      percentUsed: null,
+      ...period,
+      purchaseRef: activePurchase.reference
+    };
+  }
+  const solvaPay = options.solvaPay || createSolvaPay();
+  const limits = await solvaPay.apiClient.checkLimits({
+    customerRef: purchaseResult.customerRef,
+    productRef: activePurchase.productRef
+  });
+  const hasFiniteCap = limits.remaining >= 0;
+  const remaining = hasFiniteCap ? limits.remaining : null;
+  const total = remaining === null ? null : used + remaining;
   const percentUsed = total !== null && total > 0 ? Math.min(100, Math.round(used / total * 1e4) / 100) : null;
   return {
-    meterRef,
+    meterRef: limits.meterName ?? null,
     total,
     used,
     remaining,
     percentUsed,
-    ...usage?.periodStart ? { periodStart: usage.periodStart } : {},
-    ...usage?.periodEnd ? { periodEnd: usage.periodEnd } : {},
+    ...period,
     purchaseRef: activePurchase.reference
   };
 }