@basaltkit/subscriptions 1.2.0 → 2.0.0

package/dist/index.d.ts

@@ -19,7 +19,12 @@ declare function meter(limit: number): Meter;
 type FeatureValue = boolean | number | Meter;
 type BillingPeriod = 'monthly' | 'yearly';
 interface PlanDefinition {
-    /** 0 = free · number = same price both periods · object = per period · 'custom' = sales-led */
+    /**
+     * Price in the currency's minor unit (integer; cents — `2900` = $29.00).
+     * 0 = free · number = same price both periods · object = per period ·
+     * 'custom' = sales-led. Only gated (`> 0`) and displayed here; the actual
+     * Stripe charge uses a pre-created price id on the gateway.
+     */
     price: number | {
         monthly: number;
         yearly: number;
@@ -268,12 +273,16 @@ declare class FakeBillingGateway implements BillingGateway {
  * `BillingGateway` (card subscriptions). Recurring billing is modelled by
  * creating one payment per period (invoice → reference → webhook confirms → the
  * period is activated).
+ *
+ * **All amounts are integers in the currency's minor unit** (cents; `100 = 1.00`)
+ * — the Stripe convention. Use the `money` helpers (`toMinor`/`formatMoney`) at
+ * the human boundary. Drivers translate to each provider's expected format.
  */
 /** A one-off payment request handed to a `PaymentGateway`. */
 interface PaymentRequest {
     /** Who is paying — a tenant/user/customer id you reconcile against. */
     billableId: string;
-    /** Amount in the currency's major unit (e.g. 5000 = 5000,00 Kz). */
+    /** Amount in the currency's minor unit (integer; `500000` = 5.000,00 Kz). */
     amount: number;
     /** ISO 4217. Defaults to the gateway's own (AOA for Angolan gateways). */
     currency?: string;
@@ -464,7 +473,7 @@ interface RecurringSubscription {
     /** The customer/tenant this subscription bills. One per billableId. */
     billableId: string;
     plan: string;
-    /** Price per period, in the currency's major unit. */
+    /** Price per period, in the currency's minor unit (integer; cents). */
     amount: number;
     interval: RecurringInterval;
     status: RecurringStatus;
@@ -558,6 +567,38 @@ declare class RecurringReferenceBilling {
     cancel(billableId: string): Promise<void>;
 }
 
+/**
+ * Money handling for the subscriptions ecosystem. **All amounts in the public
+ * API are integers in the currency's minor unit** — cents, `100 = 1.00`. This
+ * is the Stripe/Adyen convention: exact, no floating-point rounding, and no
+ * ambiguity about units. Use these helpers to convert at the human boundary
+ * (input forms, display) and to validate.
+ *
+ * ```ts
+ * toMinor(5000, 'AOA')      // 500000  (5.000,00 Kz)
+ * toMajor(500000, 'AOA')    // 5000
+ * formatMoney(500000, 'AOA', 'pt-AO') // "5.000,00 AOA"
+ * assertMinorUnits(2999)    // ok      ($29.99)
+ * assertMinorUnits(29.99)   // throws
+ * ```
+ */
+/** Number of minor-unit decimal places for a currency (default 2). */
+declare function currencyDecimals(currency: string): number;
+/** Convert a major-unit amount (e.g. `5000` Kz) to minor units (`500000`). */
+declare function toMinor(major: number, currency: string): number;
+/** Convert minor units (`500000`) back to a major-unit amount (`5000` Kz). */
+declare function toMajor(minor: number, currency: string): number;
+/** Format a minor-unit amount for display. Falls back to a plain string if Intl lacks the currency. */
+declare function formatMoney(minor: number, currency: string, locale?: string): string;
+/** True when `amount` is a valid minor-unit value (a non-negative integer). */
+declare function isMinorUnits(amount: number): boolean;
+/**
+ * Throw unless `amount` is a valid minor-unit value. Drivers call this so a
+ * major-unit slip (e.g. `29.99` instead of `2999`) fails fast instead of
+ * silently under/over-charging.
+ */
+declare function assertMinorUnits(amount: number, label?: string): void;
+
 declare class StripeRequestError extends BasaltError {
     readonly httpStatus: number;
     constructor(httpStatus: number, message: string);
@@ -770,4 +811,4 @@ declare function billingRoutes(options: BillingRoutesOptions): BasaltRoute[];
  */
 declare function billingWebhookRoute(gateway: BillingGateway): BasaltRoute;
 
-export { type BillingGateway, type BillingPeriod, type BillingRoutesOptions, type CheckoutInput, type CreateSubscriptionInput, FakeBillingGateway, FakePaymentGateway, FeatureUnavailableError, type FeatureValue, GatewayUnsupportedError, type HandleEventResult, MemoryPaymentStore, MemoryRecurringStore, MemorySubscriptionStore, MemoryUsageStore, MemoryWebhookStore, type Meter, type NewPayment, NotSubscribedError, type PaymentApplyResult, type PaymentEvent, type PaymentGateway, type PaymentInstruction, PaymentLedger, type PaymentLedgerOptions, type PaymentRecord, type PaymentRecordStatus, type PaymentRequest, type PaymentStore, type PlanDefinition, type Plans, type PortalInput, QuotaExceededError, type RecurringBillingOptions, type RecurringInterval, RecurringReferenceBilling, type RecurringStatus, type RecurringStore, type RecurringSubscription, type RedisLike, RedisUsageStore, type RedisUsageStoreOptions, type RedisWebhookClient, RedisWebhookStore, type RedisWebhookStoreOptions, SUBSCRIPTIONS, StripeBillingGateway, type StripeGatewayOptions, StripeRequestError, type SubscribeInput, type SubscriptionRecord, type SubscriptionStatus, type SubscriptionStore, Subscriptions, type SubscriptionsOptions, type SubscriptionsPluginOptions, type SwapInput, UnknownPlanError, type UsageConsumeResult, type UsageStore, type WebhookEvent, WebhookInvalidError, type WebhookStore, addInterval, billingRoutes, billingWebhookRoute, definePlans, featureLimit, isMeter, meter, planPrice, subscriptionsPlugin };
+export { type BillingGateway, type BillingPeriod, type BillingRoutesOptions, type CheckoutInput, type CreateSubscriptionInput, FakeBillingGateway, FakePaymentGateway, FeatureUnavailableError, type FeatureValue, GatewayUnsupportedError, type HandleEventResult, MemoryPaymentStore, MemoryRecurringStore, MemorySubscriptionStore, MemoryUsageStore, MemoryWebhookStore, type Meter, type NewPayment, NotSubscribedError, type PaymentApplyResult, type PaymentEvent, type PaymentGateway, type PaymentInstruction, PaymentLedger, type PaymentLedgerOptions, type PaymentRecord, type PaymentRecordStatus, type PaymentRequest, type PaymentStore, type PlanDefinition, type Plans, type PortalInput, QuotaExceededError, type RecurringBillingOptions, type RecurringInterval, RecurringReferenceBilling, type RecurringStatus, type RecurringStore, type RecurringSubscription, type RedisLike, RedisUsageStore, type RedisUsageStoreOptions, type RedisWebhookClient, RedisWebhookStore, type RedisWebhookStoreOptions, SUBSCRIPTIONS, StripeBillingGateway, type StripeGatewayOptions, StripeRequestError, type SubscribeInput, type SubscriptionRecord, type SubscriptionStatus, type SubscriptionStore, Subscriptions, type SubscriptionsOptions, type SubscriptionsPluginOptions, type SwapInput, UnknownPlanError, type UsageConsumeResult, type UsageStore, type WebhookEvent, WebhookInvalidError, type WebhookStore, addInterval, assertMinorUnits, billingRoutes, billingWebhookRoute, currencyDecimals, definePlans, featureLimit, formatMoney, isMeter, isMinorUnits, meter, planPrice, subscriptionsPlugin, toMajor, toMinor };

package/dist/index.js

@@ -419,6 +419,52 @@ var RecurringReferenceBilling = class {
   }
 };
 
+// src/money.ts
+var CURRENCY_DECIMALS = {
+  AOA: 2,
+  USD: 2,
+  EUR: 2,
+  GBP: 2,
+  BRL: 2,
+  ZAR: 2,
+  MZN: 2,
+  CVE: 2,
+  NGN: 2,
+  KES: 2,
+  JPY: 0,
+  XOF: 0,
+  XAF: 0,
+  CLP: 0
+};
+var DEFAULT_DECIMALS = 2;
+function currencyDecimals(currency) {
+  return CURRENCY_DECIMALS[currency.toUpperCase()] ?? DEFAULT_DECIMALS;
+}
+function toMinor(major, currency) {
+  return Math.round(major * 10 ** currencyDecimals(currency));
+}
+function toMajor(minor, currency) {
+  return minor / 10 ** currencyDecimals(currency);
+}
+function formatMoney(minor, currency, locale = "en-US") {
+  const major = toMajor(minor, currency);
+  try {
+    return new Intl.NumberFormat(locale, { style: "currency", currency }).format(major);
+  } catch {
+    return `${major.toFixed(currencyDecimals(currency))} ${currency.toUpperCase()}`;
+  }
+}
+function isMinorUnits(amount) {
+  return Number.isInteger(amount) && amount >= 0;
+}
+function assertMinorUnits(amount, label = "amount") {
+  if (!isMinorUnits(amount)) {
+    throw new RangeError(
+      `${label} must be a non-negative integer in minor units (e.g. cents), got ${amount}`
+    );
+  }
+}
+
 // src/drivers/stripe.ts
 import { createHmac, timingSafeEqual } from "crypto";
 import { BasaltError as BasaltError3 } from "@basaltkit/core";
@@ -939,12 +985,18 @@ export {
   UnknownPlanError,
   WebhookInvalidError,
   addInterval,
+  assertMinorUnits,
   billingRoutes,
   billingWebhookRoute,
+  currencyDecimals,
   definePlans,
   featureLimit,
+  formatMoney,
   isMeter,
+  isMinorUnits,
   meter,
   planPrice,
-  subscriptionsPlugin
+  subscriptionsPlugin,
+  toMajor,
+  toMinor
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/subscriptions",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Billing for Basalt, Cashier/Soulbscription-style: declarative plans, subscriptions with trials, feature flags, usage limits, gateway drivers and idempotent webhooks.",
   "license": "MIT",
   "type": "module",