@basaltkit/subscriptions 2.1.0 → 2.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @basaltkit/subscriptions
 
-Billing for the Basalt framework, in the style of Laravel Cashier/Soulbscription: declarative plans, subscriptions with a trial period, features with usage limits, Stripe integration, and idempotent webhooks. You need this module when your SaaS application charges monthly fees and limits features by plan.
+Billing for the Basalt framework, in the style of Laravel Cashier/Soulbscription: declarative plans, subscriptions with a trial period, features with usage limits, Stripe / Paddle / Lemon Squeezy integration, and idempotent webhooks. You need this module when your SaaS application charges monthly fees and limits features by plan.
 
 ## What this module solves
 
@@ -168,6 +168,39 @@ const gateway = new StripeBillingGateway({
 export const subscriptions = new Subscriptions({ plans, gateway, fallbackPlan: 'free' })
 ```
 
+### Paddle gateway
+
+`PaddleBillingGateway` targets **Paddle Billing** the same way (no SDK, injectable `fetch`), mapping plans to Paddle *Price IDs* (`pri_…`) and billables to *Customer IDs* (`ctm_…`). Paddle is checkout-first, so `createSubscription`/`createCheckoutSession` create a transaction and the durable subscription ref arrives on a `subscription.*` webhook.
+
+```ts
+import { PaddleBillingGateway, Subscriptions } from '@basaltkit/subscriptions'
+
+const gateway = new PaddleBillingGateway({
+  apiKey: process.env.PADDLE_API_KEY!,
+  webhookSecret: process.env.PADDLE_NOTIFICATION_SECRET!, // ntfset_...
+  priceId: (plan, period) => ({ pro: { monthly: 'pri_pro_m', yearly: 'pri_pro_y' } })[plan]![period],
+  customerId: async (billableId) => getOrCreatePaddleCustomer(billableId),
+})
+```
+
+Webhook signatures use Paddle's `Paddle-Signature` scheme (`ts=…;h1=…`, HMAC-SHA256 over `${ts}:${rawBody}`) — verified by the driver, with the same 5-minute timestamp tolerance as Stripe.
+
+### Lemon Squeezy gateway
+
+`LemonSqueezyBillingGateway` targets the Lemon Squeezy REST API (JSON:API, no SDK), mapping plans to *Variant IDs* and using your *Store ID* for checkouts. Also checkout-first; webhook signatures use the `X-Signature` header (a bare HMAC-SHA256 hex of the raw body — no timestamp).
+
+```ts
+import { LemonSqueezyBillingGateway, Subscriptions } from '@basaltkit/subscriptions'
+
+const gateway = new LemonSqueezyBillingGateway({
+  apiKey: process.env.LEMONSQUEEZY_API_KEY!,
+  webhookSecret: process.env.LEMONSQUEEZY_WEBHOOK_SECRET!,
+  storeId: process.env.LEMONSQUEEZY_STORE_ID!,
+  variantId: (plan, period) => ({ pro: { monthly: '111', yearly: '222' } })[plan]![period],
+  customerId: async (billableId) => getLemonSqueezyCustomer(billableId), // for the portal
+})
+```
+
 For development and testing there's `FakeBillingGateway`, which records all calls in arrays (`created`, `canceled`, `checkouts`, `portals`, `swaps`) and accepts the webhook signature `'valid'`.
 
 ### Gateway webhooks

package/dist/index.d.ts

@@ -161,6 +161,24 @@ declare class WebhookInvalidError extends BasaltError {
     readonly status = 400;
     constructor();
 }
+/**
+ * Thrown when a gateway is asked to verify a webhook but no signing secret is
+ * configured. Verification fails closed: an unauthenticated callback must never
+ * be trusted (anyone could forge a `payment.succeeded`).
+ */
+declare class WebhookSecretMissingError extends BasaltError {
+    readonly status = 500;
+    constructor(gateway: string);
+}
+/**
+ * Thrown when a confirmed payment's amount does not match the amount that was
+ * originally requested for that payment id — an underpayment, or a forged /
+ * mis-routed callback trying to settle an invoice for less.
+ */
+declare class PaymentAmountMismatchError extends BasaltError {
+    readonly status = 400;
+    constructor(paymentId: string, expected: number, actual: number);
+}
 /** Gateway-agnostic webhook event, already translated to domain terms. */
 interface WebhookEvent {
     /** Unique id at the gateway — used for idempotent processing. */
@@ -694,6 +712,127 @@ declare class StripeBillingGateway implements BillingGateway {
     private request;
 }
 
+declare class PaddleRequestError extends BasaltError {
+    readonly httpStatus: number;
+    constructor(httpStatus: number, message: string);
+}
+interface PaddleGatewayOptions {
+    /** Paddle API key (Bearer). */
+    apiKey: string;
+    /** Notification signing secret (`pdl_ntfset_…` / `ntfset_…`) used to verify webhooks. */
+    webhookSecret: string;
+    /** Resolves the Paddle Price ID (`pri_…`) for a plan + billing period. */
+    priceId: (plan: string, period: BillingPeriod) => string;
+    /** Resolves (or ensures) the Paddle Customer ID (`ctm_…`) for a billable entity. */
+    customerId: (billableId: string) => string | Promise<string>;
+    /**
+     * Extracts the billable id from a verified event. Default: reads
+     * `data.custom_data.billableId` — which the create/checkout calls set.
+     */
+    resolveBillableId?: (event: unknown) => string | undefined;
+    /** Webhook timestamp tolerance in seconds. Default: 300 (5 minutes). */
+    tolerance?: number;
+    /** Injected fetch (tests). Default: global fetch. */
+    fetch?: typeof fetch;
+    /** Clock in ms (tests). Default: Date.now. */
+    now?: () => number;
+    /** API base, for tests/mocks. Default: https://api.paddle.com */
+    apiBase?: string;
+}
+/**
+ * Paddle **Billing** gateway targeting the Paddle REST API directly — no SDK.
+ * HTTP goes through an injectable fetch; webhook signatures are verified with
+ * node:crypto using Paddle's `Paddle-Signature` scheme (`ts=…;h1=…`).
+ *
+ * Paddle is checkout-first: `createSubscription` and `createCheckoutSession`
+ * both create a **transaction** (the subscription materializes once the customer
+ * pays, and its id arrives on a `subscription.*` webhook via `gatewayRef`).
+ */
+declare class PaddleBillingGateway implements BillingGateway {
+    private readonly options;
+    readonly name = "paddle";
+    private readonly fetch;
+    private readonly now;
+    private readonly tolerance;
+    private readonly apiBase;
+    private readonly resolveBillableId;
+    constructor(options: PaddleGatewayOptions);
+    createSubscription(input: CreateSubscriptionInput): Promise<{
+        gatewayRef: string;
+    }>;
+    cancelSubscription(gatewayRef: string, options: {
+        atPeriodEnd: boolean;
+    }): Promise<void>;
+    createCheckoutSession(input: CheckoutInput): Promise<{
+        url: string;
+        id: string;
+    }>;
+    createPortalSession(input: PortalInput): Promise<{
+        url: string;
+    }>;
+    swapSubscription(gatewayRef: string, input: SwapInput): Promise<void>;
+    verifyWebhook(rawBody: string, signature: string | undefined): WebhookEvent | null;
+    private request;
+}
+
+declare class LemonSqueezyRequestError extends BasaltError {
+    readonly httpStatus: number;
+    constructor(httpStatus: number, message: string);
+}
+interface LemonSqueezyGatewayOptions {
+    /** Lemon Squeezy API key (Bearer). */
+    apiKey: string;
+    /** Webhook signing secret used to verify `X-Signature`. */
+    webhookSecret: string;
+    /** Lemon Squeezy Store ID (needed to create checkouts). */
+    storeId: string;
+    /** Resolves the Lemon Squeezy Variant ID for a plan + billing period. */
+    variantId: (plan: string, period: BillingPeriod) => string;
+    /** Resolves the Lemon Squeezy Customer ID for a billable — required for the portal. */
+    customerId?: (billableId: string) => string | Promise<string>;
+    /**
+     * Extracts the billable id from a verified event. Default: reads
+     * `meta.custom_data.billableId` — which the checkout call sets.
+     */
+    resolveBillableId?: (event: unknown) => string | undefined;
+    /** Injected fetch (tests). Default: global fetch. */
+    fetch?: typeof fetch;
+    /** API base, for tests/mocks. Default: https://api.lemonsqueezy.com/v1 */
+    apiBase?: string;
+}
+/**
+ * Lemon Squeezy billing gateway targeting the REST API directly (JSON:API) — no
+ * SDK. Lemon Squeezy is a merchant-of-record and checkout-first, so
+ * `createSubscription`/`createCheckoutSession` create a **checkout**; the durable
+ * subscription id arrives on a `subscription_*` webhook via `gatewayRef`. Webhook
+ * signatures use the `X-Signature` scheme (HMAC-SHA256 hex over the raw body).
+ */
+declare class LemonSqueezyBillingGateway implements BillingGateway {
+    private readonly options;
+    readonly name = "lemonsqueezy";
+    private readonly fetch;
+    private readonly apiBase;
+    private readonly resolveBillableId;
+    constructor(options: LemonSqueezyGatewayOptions);
+    createSubscription(input: CreateSubscriptionInput): Promise<{
+        gatewayRef: string;
+    }>;
+    createCheckoutSession(input: CheckoutInput): Promise<{
+        url: string;
+        id: string;
+    }>;
+    private checkout;
+    cancelSubscription(gatewayRef: string, _options: {
+        atPeriodEnd: boolean;
+    }): Promise<void>;
+    createPortalSession(input: PortalInput): Promise<{
+        url: string;
+    }>;
+    swapSubscription(gatewayRef: string, input: SwapInput): Promise<void>;
+    verifyWebhook(rawBody: string, signature: string | undefined): WebhookEvent | null;
+    private request;
+}
+
 declare class NotSubscribedError extends BasaltError {
     readonly status = 402;
     constructor();
@@ -847,4 +986,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 PaymentLedgerEvent, type PaymentLedgerEvents, type PaymentLedgerListener, 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 };
+export { type BillingGateway, type BillingPeriod, type BillingRoutesOptions, type CheckoutInput, type CreateSubscriptionInput, FakeBillingGateway, FakePaymentGateway, FeatureUnavailableError, type FeatureValue, GatewayUnsupportedError, type HandleEventResult, LemonSqueezyBillingGateway, type LemonSqueezyGatewayOptions, LemonSqueezyRequestError, MemoryPaymentStore, MemoryRecurringStore, MemorySubscriptionStore, MemoryUsageStore, MemoryWebhookStore, type Meter, type NewPayment, NotSubscribedError, PaddleBillingGateway, type PaddleGatewayOptions, PaddleRequestError, PaymentAmountMismatchError, type PaymentApplyResult, type PaymentEvent, type PaymentGateway, type PaymentInstruction, PaymentLedger, type PaymentLedgerEvent, type PaymentLedgerEvents, type PaymentLedgerListener, 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, WebhookSecretMissingError, type WebhookStore, addInterval, assertMinorUnits, billingRoutes, billingWebhookRoute, currencyDecimals, definePlans, featureLimit, formatMoney, isMeter, isMinorUnits, meter, planPrice, subscriptionsPlugin, toMajor, toMinor };

package/dist/index.js

@@ -160,6 +160,24 @@ var WebhookInvalidError = class extends BasaltError2 {
     super("BILLING_WEBHOOK_INVALID", "Webhook signature verification failed.");
   }
 };
+var WebhookSecretMissingError = class extends BasaltError2 {
+  status = 500;
+  constructor(gateway) {
+    super(
+      "BILLING_WEBHOOK_SECRET_MISSING",
+      `${gateway}: cannot verify a webhook without a configured signing secret \u2014 refusing to trust an unsigned callback.`
+    );
+  }
+};
+var PaymentAmountMismatchError = class extends BasaltError2 {
+  status = 400;
+  constructor(paymentId, expected, actual) {
+    super(
+      "BILLING_PAYMENT_AMOUNT_MISMATCH",
+      `Payment ${paymentId} was requested for ${expected} but the webhook confirmed ${actual} \u2014 refusing to mark it paid.`
+    );
+  }
+};
 var FakeBillingGateway = class {
   name = "fake";
   created = [];
@@ -303,6 +321,12 @@ var PaymentLedger = class {
     let record;
     try {
       const status = event.type === "payment.succeeded" ? "paid" : "failed";
+      if (status === "paid") {
+        const existing = await this.store.get(event.paymentId);
+        if (existing && existing.amount > 0 && event.amount !== existing.amount) {
+          throw new PaymentAmountMismatchError(event.paymentId, existing.amount, event.amount);
+        }
+      }
       await this.store.setStatus(event.paymentId, status, {
         amount: event.amount,
         ...event.raw !== void 0 ? { raw: event.raw } : {}
@@ -630,21 +654,264 @@ function formEncode(data) {
   return Object.entries(data).map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`).join("&");
 }
 
+// src/drivers/paddle.ts
+import { createHmac as createHmac2, timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { BasaltError as BasaltError4 } from "@basaltkit/core";
+var PaddleRequestError = class extends BasaltError4 {
+  constructor(httpStatus, message) {
+    super("BILLING_GATEWAY_ERROR", `Paddle request failed (${httpStatus}): ${message}`);
+    this.httpStatus = httpStatus;
+  }
+  httpStatus;
+};
+var EVENT_MAP2 = {
+  "subscription.canceled": "subscription.canceled",
+  "transaction.completed": "payment.succeeded",
+  "transaction.paid": "payment.succeeded",
+  "transaction.payment_failed": "payment.failed"
+};
+var PRORATION = {
+  create_prorations: "prorated_immediately",
+  none: "do_not_bill",
+  always_invoice: "full_immediately"
+};
+var PaddleBillingGateway = class {
+  constructor(options) {
+    this.options = options;
+    this.fetch = options.fetch ?? globalThis.fetch;
+    this.now = options.now ?? Date.now;
+    this.tolerance = options.tolerance ?? 300;
+    this.apiBase = options.apiBase ?? "https://api.paddle.com";
+    this.resolveBillableId = options.resolveBillableId ?? ((event) => event?.data?.custom_data?.["billableId"]);
+  }
+  options;
+  name = "paddle";
+  fetch;
+  now;
+  tolerance;
+  apiBase;
+  resolveBillableId;
+  async createSubscription(input) {
+    const customer = await this.options.customerId(input.billableId);
+    const created = await this.request("POST", "/transactions", {
+      items: [{ price_id: this.options.priceId(input.plan, input.period), quantity: 1 }],
+      customer_id: customer,
+      collection_mode: "automatic",
+      custom_data: { billableId: input.billableId }
+    });
+    return { gatewayRef: String(created.id) };
+  }
+  async cancelSubscription(gatewayRef, options) {
+    await this.request("POST", `/subscriptions/${gatewayRef}/cancel`, {
+      effective_from: options.atPeriodEnd ? "next_billing_period" : "immediately"
+    });
+  }
+  async createCheckoutSession(input) {
+    const customer = await this.options.customerId(input.billableId);
+    const created = await this.request("POST", "/transactions", {
+      items: [{ price_id: this.options.priceId(input.plan, input.period), quantity: 1 }],
+      customer_id: customer,
+      collection_mode: "automatic",
+      custom_data: { billableId: input.billableId },
+      checkout: { url: input.successUrl }
+    });
+    return { url: String(created.checkout?.url), id: String(created.id) };
+  }
+  async createPortalSession(input) {
+    const customer = await this.options.customerId(input.billableId);
+    const created = await this.request(
+      "POST",
+      `/customers/${customer}/portal-sessions`,
+      {}
+    );
+    return { url: String(created.urls?.general?.overview) };
+  }
+  async swapSubscription(gatewayRef, input) {
+    await this.request("PATCH", `/subscriptions/${gatewayRef}`, {
+      items: [{ price_id: this.options.priceId(input.plan, input.period), quantity: 1 }],
+      proration_billing_mode: PRORATION[input.prorationBehavior ?? "create_prorations"]
+    });
+  }
+  verifyWebhook(rawBody, signature) {
+    if (!signature) throw new WebhookInvalidError();
+    const parts = Object.fromEntries(
+      signature.split(";").map((pair) => {
+        const index = pair.indexOf("=");
+        return [pair.slice(0, index).trim(), pair.slice(index + 1)];
+      })
+    );
+    const timestamp = Number(parts.ts);
+    if (!Number.isFinite(timestamp) || !parts.h1) throw new WebhookInvalidError();
+    const expected = createHmac2("sha256", this.options.webhookSecret).update(`${parts.ts}:${rawBody}`).digest("hex");
+    const a = Buffer.from(expected);
+    const b = Buffer.from(parts.h1);
+    if (a.length !== b.length || !timingSafeEqual2(a, b)) throw new WebhookInvalidError();
+    if (Math.abs(this.now() / 1e3 - timestamp) > this.tolerance) throw new WebhookInvalidError();
+    let event;
+    try {
+      event = JSON.parse(rawBody);
+    } catch {
+      throw new WebhookInvalidError();
+    }
+    const type = event.event_type ? EVENT_MAP2[event.event_type] : void 0;
+    if (!type || !event.event_id) return null;
+    const billableId = this.resolveBillableId(event);
+    if (!billableId) return null;
+    const gatewayRef = event.data?.subscription_id ?? event.data?.id;
+    return { id: event.event_id, type, billableId, ...gatewayRef ? { gatewayRef } : {} };
+  }
+  async request(method, path, body) {
+    const response = await this.fetch(`${this.apiBase}${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${this.options.apiKey}`,
+        "content-type": "application/json"
+      },
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+    });
+    const text = await response.text();
+    const json = text ? JSON.parse(text) : {};
+    if (!response.ok) {
+      throw new PaddleRequestError(response.status, json.error?.detail ?? text ?? "unknown error");
+    }
+    return json.data ?? json;
+  }
+};
+
+// src/drivers/lemonsqueezy.ts
+import { createHmac as createHmac3, timingSafeEqual as timingSafeEqual3 } from "crypto";
+import { BasaltError as BasaltError5 } from "@basaltkit/core";
+var LemonSqueezyRequestError = class extends BasaltError5 {
+  constructor(httpStatus, message) {
+    super("BILLING_GATEWAY_ERROR", `Lemon Squeezy request failed (${httpStatus}): ${message}`);
+    this.httpStatus = httpStatus;
+  }
+  httpStatus;
+};
+var EVENT_MAP3 = {
+  subscription_cancelled: "subscription.canceled",
+  subscription_expired: "subscription.canceled",
+  subscription_payment_success: "payment.succeeded",
+  subscription_payment_failed: "payment.failed"
+};
+var JSON_API = "application/vnd.api+json";
+var LemonSqueezyBillingGateway = class {
+  constructor(options) {
+    this.options = options;
+    this.fetch = options.fetch ?? globalThis.fetch;
+    this.apiBase = options.apiBase ?? "https://api.lemonsqueezy.com/v1";
+    this.resolveBillableId = options.resolveBillableId ?? ((event) => event?.meta?.custom_data?.["billableId"]);
+  }
+  options;
+  name = "lemonsqueezy";
+  fetch;
+  apiBase;
+  resolveBillableId;
+  async createSubscription(input) {
+    const checkout = await this.checkout(input.billableId, input.plan, input.period);
+    return { gatewayRef: String(checkout.id) };
+  }
+  async createCheckoutSession(input) {
+    const checkout = await this.checkout(input.billableId, input.plan, input.period, input.successUrl);
+    return { url: String(checkout.attributes?.url), id: String(checkout.id) };
+  }
+  async checkout(billableId, plan, period, redirectUrl) {
+    const created = await this.request("POST", "/checkouts", {
+      data: {
+        type: "checkouts",
+        attributes: {
+          checkout_data: { custom: { billableId } },
+          ...redirectUrl ? { product_options: { redirect_url: redirectUrl } } : {}
+        },
+        relationships: {
+          store: { data: { type: "stores", id: this.options.storeId } },
+          variant: { data: { type: "variants", id: this.options.variantId(plan, period) } }
+        }
+      }
+    });
+    return created;
+  }
+  async cancelSubscription(gatewayRef, _options) {
+    await this.request("DELETE", `/subscriptions/${gatewayRef}`);
+  }
+  async createPortalSession(input) {
+    if (!this.options.customerId) {
+      throw new LemonSqueezyRequestError(500, "customerId resolver is required for the customer portal");
+    }
+    const customer = await this.options.customerId(input.billableId);
+    const found = await this.request("GET", `/customers/${customer}`);
+    return { url: String(found.attributes?.urls?.customer_portal) };
+  }
+  async swapSubscription(gatewayRef, input) {
+    const behavior = input.prorationBehavior ?? "create_prorations";
+    await this.request("PATCH", `/subscriptions/${gatewayRef}`, {
+      data: {
+        type: "subscriptions",
+        id: gatewayRef,
+        attributes: {
+          variant_id: this.options.variantId(input.plan, input.period),
+          disable_prorations: behavior === "none",
+          ...behavior === "always_invoice" ? { invoice_immediately: true } : {}
+        }
+      }
+    });
+  }
+  verifyWebhook(rawBody, signature) {
+    if (!signature) throw new WebhookInvalidError();
+    const expected = createHmac3("sha256", this.options.webhookSecret).update(rawBody).digest("hex");
+    const a = Buffer.from(expected);
+    const b = Buffer.from(signature);
+    if (a.length !== b.length || !timingSafeEqual3(a, b)) throw new WebhookInvalidError();
+    let event;
+    try {
+      event = JSON.parse(rawBody);
+    } catch {
+      throw new WebhookInvalidError();
+    }
+    const name = event.meta?.event_name;
+    const type = name ? EVENT_MAP3[name] : void 0;
+    if (!type) return null;
+    const billableId = this.resolveBillableId(event);
+    if (!billableId) return null;
+    const rawRef = event.data?.attributes?.subscription_id ?? event.data?.id;
+    const gatewayRef = rawRef !== void 0 ? String(rawRef) : void 0;
+    const id = `${name}:${gatewayRef ?? billableId}`;
+    return { id, type, billableId, ...gatewayRef ? { gatewayRef } : {} };
+  }
+  async request(method, path, body) {
+    const response = await this.fetch(`${this.apiBase}${path}`, {
+      method,
+      headers: {
+        authorization: `Bearer ${this.options.apiKey}`,
+        accept: JSON_API,
+        ...body !== void 0 ? { "content-type": JSON_API } : {}
+      },
+      ...body !== void 0 ? { body: JSON.stringify(body) } : {}
+    });
+    const text = await response.text();
+    const json = text ? JSON.parse(text) : {};
+    if (!response.ok) {
+      throw new LemonSqueezyRequestError(response.status, json.errors?.[0]?.detail ?? text ?? "unknown error");
+    }
+    return json.data ?? json;
+  }
+};
+
 // src/subscriptions.ts
-import { BasaltError as BasaltError4, parseDuration } from "@basaltkit/core";
-var NotSubscribedError = class extends BasaltError4 {
+import { BasaltError as BasaltError6, parseDuration } from "@basaltkit/core";
+var NotSubscribedError = class extends BasaltError6 {
   status = 402;
   constructor() {
     super("BILLING_SUBSCRIPTION_REQUIRED", "An active subscription is required.");
   }
 };
-var FeatureUnavailableError = class extends BasaltError4 {
+var FeatureUnavailableError = class extends BasaltError6 {
   status = 403;
   constructor(feature) {
     super("BILLING_FEATURE_UNAVAILABLE", `The feature "${feature}" is not available on this plan.`);
   }
 };
-var QuotaExceededError = class extends BasaltError4 {
+var QuotaExceededError = class extends BasaltError6 {
   status = 402;
   constructor(feature, remaining) {
     super(
@@ -653,7 +920,7 @@ var QuotaExceededError = class extends BasaltError4 {
     );
   }
 };
-var GatewayUnsupportedError = class extends BasaltError4 {
+var GatewayUnsupportedError = class extends BasaltError6 {
   status = 501;
   constructor(capability) {
     super("BILLING_GATEWAY_UNSUPPORTED", `The billing gateway does not support "${capability}".`);
@@ -996,12 +1263,17 @@ export {
   FakePaymentGateway,
   FeatureUnavailableError,
   GatewayUnsupportedError,
+  LemonSqueezyBillingGateway,
+  LemonSqueezyRequestError,
   MemoryPaymentStore,
   MemoryRecurringStore,
   MemorySubscriptionStore,
   MemoryUsageStore,
   MemoryWebhookStore,
   NotSubscribedError,
+  PaddleBillingGateway,
+  PaddleRequestError,
+  PaymentAmountMismatchError,
   PaymentLedger,
   QuotaExceededError,
   RecurringReferenceBilling,
@@ -1013,6 +1285,7 @@ export {
   Subscriptions,
   UnknownPlanError,
   WebhookInvalidError,
+  WebhookSecretMissingError,
   addInterval,
   assertMinorUnits,
   billingRoutes,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/subscriptions",
-  "version": "2.1.0",
+  "version": "2.3.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",
@@ -14,8 +14,8 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/fastify": "^1.0.0",
-    "@basaltkit/core": "^1.0.0"
+    "@basaltkit/core": "^1.0.0",
+    "@basaltkit/fastify": "^1.4.0"
   },
   "peerDependencies": {
     "zod": "^3.24.0 || ^4.0.0"