@billkit-eu/sdk 0.2.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@billkit-eu/sdk",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Official Node.js SDK for BillKit: a Stripe-Billing-shape multi-tenant SaaS API on Mollie.",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/client.ts

@@ -12,6 +12,7 @@ import {
   BillingPortalSessions,
   CheckoutSessions,
   Coupons,
+  CreditNotes,
   Customers,
   Disputes,
   Events,
@@ -58,6 +59,7 @@ export class BillKit {
   readonly coupons: Coupons;
   readonly taxRates: TaxRates;
   readonly invoices: Invoices;
+  readonly creditNotes: CreditNotes;
   readonly auditLogs: AuditLogs;
   readonly payments: Payments;
   readonly billingPortalSessions: BillingPortalSessions;
@@ -81,6 +83,7 @@ export class BillKit {
     this.coupons = new Coupons(transport);
     this.taxRates = new TaxRates(transport);
     this.invoices = new Invoices(transport);
+    this.creditNotes = new CreditNotes(transport);
     this.auditLogs = new AuditLogs(transport);
     this.payments = new Payments(transport);
     this.billingPortalSessions = new BillingPortalSessions(transport);

package/src/index.ts

@@ -81,9 +81,11 @@ export type {
   CreateTaxRateParams,
   CreateUsageRecordParams,
   CreateWebhookEndpointParams,
+  CreditNotesListParams,
   EventsListParams,
   IdempotencyOptions,
   ListParams,
+  PriceTier,
   PricesListParams,
   RotateProviderCredentialParams,
   SetPortalBrandingParams,
@@ -95,6 +97,7 @@ export type {
   UpdateWebhookEndpointParams,
   UsageRecordsListParams,
   ValidateCouponParams,
+  VoidInvoiceParams,
 } from "./resources.js";
 export { DEFAULT_RETRY_POLICY, type RetryPolicy } from "./retry.js";
 export { VERSION } from "./version.js";

package/src/resources.ts

@@ -109,6 +109,15 @@ export interface UpdateCustomerParams extends IdempotencyOptions {
   metadata?: Record<string, string>;
 }
 
+/** Query parameters accepted by `GET /v1/customers`. */
+export interface CustomerListParams extends BaseListParams {
+  /**
+   * `false` for customers who have paid, `true` for abandoned checkouts,
+   * omitted for both.
+   */
+  provisional?: boolean;
+}
+
 /**
  * Body for `POST /v1/customers/{id}/vat_number`. The VAT number is
  * sent through VIES server-side; the response carries
@@ -138,6 +147,16 @@ export interface CreateProductParams extends IdempotencyOptions {
   marketing_features?: string[];
   /** Small string metadata map echoed back on the Product object. */
   metadata?: Record<string, string>;
+  /**
+   * Let a *buyer* type a coupon code at the embedded checkout for this
+   * product. Defaults to `false`. A coupon you apply yourself by passing
+   * `coupon_code` when you create a Checkout Session is unaffected — that
+   * is you discounting your own sale, and it has never needed this flag.
+   *
+   * The code is redeemed only once the payment settles, so a shopper who
+   * tries a single-use code and abandons the checkout does not use it up.
+   */
+  allow_promotion_codes?: boolean;
 }
 
 export interface UpdateProductParams extends IdempotencyOptions {
@@ -147,6 +166,8 @@ export interface UpdateProductParams extends IdempotencyOptions {
   metadata?: Record<string, string>;
   /** Set false to stop selling a product without deleting history. */
   active?: boolean;
+  /** See {@link CreateProductParams.allow_promotion_codes}. */
+  allow_promotion_codes?: boolean;
 }
 
 /**
@@ -159,16 +180,94 @@ export interface UpdatePriceParams extends IdempotencyOptions {
   active: boolean;
 }
 
+/**
+ * One band of a tiered price.
+ *
+ * `up_to` is inclusive, and the **last band must be `"inf"`** because a
+ * bounded top band cannot price the usage above it. Bands must strictly
+ * increase.
+ *
+ * A band names a unit rate (`unit_amount` in whole minor units, or
+ * `unit_amount_decimal` for a finer one), a `flat_amount` charged once for
+ * reaching the band, or both. Write a free band as `unit_amount: 0` rather
+ * than by omitting the rate, so "free" is something the price says instead
+ * of something it forgot.
+ */
+export interface PriceTier {
+  up_to: number | "inf";
+  /** Whole minor units per unit in this band. */
+  unit_amount?: number;
+  /**
+   * A rate finer than one minor unit, **as a string** — see
+   * {@link CreatePriceParams.unit_amount_decimal} for why it is never a
+   * `number`.
+   */
+  unit_amount_decimal?: string;
+  /** Charged once when the usage reaches this band. Whole minor units. */
+  flat_amount?: number;
+}
+
 export interface CreatePriceParams extends IdempotencyOptions {
   /** Existing Product id returned from `client.products.create`. */
   product_id: string;
-  amount_cents: number;
+  /**
+   * Whole minor units per period (licensed) or per unit (metered).
+   *
+   * Optional because a metered price can be priced by
+   * {@link CreatePriceParams.unit_amount_decimal} or by
+   * {@link CreatePriceParams.tiers} instead. Exactly one of the three; a
+   * price with none of them is refused server-side.
+   */
+  amount_cents?: number;
+  /**
+   * A per-unit rate smaller than one minor unit, in **minor units**, to 12
+   * decimal places. `"0.02"` is 0.02 cents, i.e. EUR 0.0002 per unit, which
+   * is the canonical per-API-call price and not expressible as an integer.
+   * Metered prices only.
+   *
+   * **It is a `string`, and that is load-bearing.** A JS `number` is an
+   * IEEE-754 double and cannot hold 0.0002 exactly, so the rate would be
+   * corrupted before it was ever multiplied by a quantity. The type forbids
+   * a number at compile time, and the SDK throws a `TypeError` if an
+   * untyped JavaScript caller passes one anyway.
+   *
+   * The period's whole quantity is multiplied by the rate and rounded
+   * **once**, at the invoice.
+   */
+  unit_amount_decimal?: string;
+  /**
+   * `"per_unit"` (the default) multiplies one rate by the quantity.
+   * `"tiered"` prices by bands and requires
+   * {@link CreatePriceParams.tiers} and
+   * {@link CreatePriceParams.tiers_mode}. Metered prices only.
+   */
+  billing_scheme?: "per_unit" | "tiered";
+  /**
+   * How a tier table is read, and there is **no default** because the same
+   * table means two different bills. `"graduated"` prices the units inside
+   * each band; `"volume"` lets the period total pick one band which then
+   * prices every unit. 1,500 units against "first 1,000 at EUR 0.01, then
+   * EUR 0.005" is EUR 12.50 graduated and EUR 7.50 by volume.
+   */
+  tiers_mode?: "graduated" | "volume";
+  /** The band table. Required when `billing_scheme` is `"tiered"`, refused otherwise. */
+  tiers?: PriceTier[];
   currency: string;
   interval: "month" | "year" | (string & {});
   metadata?: Record<string, string>;
   trial_days?: number;
   trial_verification_cents?: number;
-  payment_methods?: Array<"creditcard" | "directdebit" | (string & {})>;
+  payment_methods?: Array<"creditcard" | "directdebit" | "ideal" | "applepay" | (string & {})>;
+  /**
+   * What a cancellation refunds without being asked. `"none"` (the default)
+   * nothing; `"full"` the whole last charge; `"prorated"` the unused part
+   * of the current period. Both non-none modes also end access
+   * immediately, and both stay bounded by the refund window below.
+   *
+   * Metered prices must leave this at `"none"`: ending access mid-period
+   * would strand usage that has not been billed yet.
+   */
+  refund_on_cancel?: "none" | "full" | "prorated";
   /**
    * Per-Price refund-window override (`POST /v1/prices`). `undefined`
    * inherits the default policy table (7d / 30d initial, 3d renewal);
@@ -189,12 +288,15 @@ export interface CreatePriceParams extends IdempotencyOptions {
   tax_behavior?: "inclusive" | "exclusive" | "unspecified";
   /**
    * `"licensed"` (the default when omitted) bills `amount_cents` per
-   * period regardless of consumption. `"metered"` bills
-   * `amount_cents` **per reported unit**: post consumption with
-   * `subscriptions.createUsageRecord` and the renewal invoice charges
-   * `amount_cents × sum(quantity)` for the period. Metered prices
-   * must be `interval: "month"`, carry `amount_cents > 0`, and cannot
-   * have `trial_days`.
+   * period regardless of consumption. `"metered"` bills **per reported
+   * unit**: post consumption with `subscriptions.createUsageRecord`, and
+   * at each period close BillKit invoices the period's total and charges
+   * the stored mandate.
+   *
+   * A metered unit is priced by `amount_cents`, by `unit_amount_decimal`,
+   * or by `tiers` — exactly one. Metered prices must be
+   * `interval: "month"`, cannot have `trial_days`, and cannot set
+   * `refund_on_cancel`.
    */
   usage_type?: "licensed" | "metered";
 }
@@ -213,6 +315,22 @@ export interface CreateUsageRecordParams extends IdempotencyOptions {
    * the record must land in the period the usage occurred.
    */
   occurred_at?: number;
+  /**
+   * Your own id for the event being metered, unique within this
+   * subscription. This is the dedupe an `Idempotency-Key` cannot do.
+   *
+   * The key covers a retry of *one HTTP request*, including the SDK's own
+   * internal retries. `identifier` covers a retry of *your* call — a job
+   * runner replaying a task, a queue delivering twice, your code
+   * re-invoking after its own timeout — which arrives at the API as a
+   * genuinely new request with a new key. A second report of the same
+   * identifier returns the first record unchanged instead of billing
+   * twice.
+   *
+   * If your reporting pipeline is at-least-once, this is the one that
+   * matters.
+   */
+  identifier?: string;
   /** Small string metadata map echoed back on the record. */
   metadata?: Record<string, string>;
 }
@@ -254,7 +372,7 @@ export interface CreateCheckoutSessionParams extends IdempotencyOptions {
    * the customer's available methods; when set, must be in the price's
    * `payment_methods` allowlist.
    */
-  method?: "creditcard" | "directdebit" | (string & {});
+  method?: "creditcard" | "directdebit" | "ideal" | "applepay" | (string & {});
   /** Optional coupon code applied at checkout; atomically claimed. */
   coupon_code?: string;
   /**
@@ -321,7 +439,14 @@ export interface CreateOneShotPaymentParams extends IdempotencyOptions {
    * *request* type the server validates, so an SDK that lags a newly-added
    * method should not be the thing that blocks the call.
    */
-  method: "creditcard" | "directdebit" | "ideal" | "bancontact" | "eps" | (string & {});
+  method:
+    | "creditcard"
+    | "directdebit"
+    | "ideal"
+    | "bancontact"
+    | "eps"
+    | "applepay"
+    | (string & {});
   /** Where Mollie returns the payer after the hosted checkout. */
   success_url: string;
   /** Optional page for an abandoned/cancelled payment. */
@@ -441,6 +566,23 @@ export interface AuditLogsListParams extends BaseListParams {
   actor_id?: string;
 }
 
+/**
+ * `creditNotes.list` params.
+ *
+ * `invoice_id` answers "was this sale credited, and by how much", which is
+ * the question when reconciling one invoice; `customer_id` answers it for
+ * everything credited back to one buyer.
+ */
+export interface CreditNotesListParams extends BaseListParams {
+  invoice_id?: string;
+  customer_id?: string;
+}
+
+/** `invoices.void` params. `reason` is recorded on the audit row only. */
+export interface VoidInvoiceParams extends IdempotencyOptions {
+  reason?: string;
+}
+
 export interface CreateBillingPortalSessionParams extends IdempotencyOptions {
   subscription_id: string;
   return_url: string;
@@ -468,6 +610,40 @@ function splitIdempotency<P extends IdempotencyOptions>(
   return { body: dropUndefined(rest as Record<string, unknown>), idempotencyKey };
 }
 
+/**
+ * Refuse a sub-minor-unit rate that arrived as a `number`.
+ *
+ * The type already forbids it, so this exists for the callers the type
+ * system cannot reach: plain JavaScript, a value that came through `any`,
+ * a body parsed from JSON. A double cannot hold 0.0002 exactly, so
+ * accepting one would work for the rates that happen to round-trip and
+ * silently mis-price the ones that do not — the worst of the three
+ * available behaviours, and the reason the field is a string in the first
+ * place.
+ */
+function assertDecimalRateIsString(value: unknown, field: string): void {
+  if (value === undefined || value === null || typeof value === "string") return;
+  throw new TypeError(
+    `${field} must be a string, not a ${typeof value}. A JavaScript number cannot ` +
+      "hold a rate like 0.0002 exactly, so it would be corrupted before it was ever " +
+      `multiplied by a quantity. Pass it as a string: "${String(value)}".`,
+  );
+}
+
+/** Same check at the price level and inside every band of a tier table. */
+function assertPriceRatesAreStrings(params: CreatePriceParams): CreatePriceParams {
+  assertDecimalRateIsString(params.unit_amount_decimal, "unit_amount_decimal");
+  // Inside a tier is where a rate is most likely to be typed as a bare
+  // literal, so the guard has to reach in there too.
+  (params.tiers ?? []).forEach((tier, index) => {
+    assertDecimalRateIsString(
+      (tier as PriceTier | undefined)?.unit_amount_decimal,
+      `tiers[${index}].unit_amount_decimal`,
+    );
+  });
+  return params;
+}
+
 /**
  * Shared transport wrapper. Resources subclass this so each method
  * reads as a single line, "verb to path with params", instead of
@@ -550,7 +726,17 @@ export class Customers extends BaseResource {
     return this.del<T>(`/v1/customers/${id}`, params);
   }
 
-  list<T = unknown>(params: BaseListParams = {}): Promise<ListResponseEnvelope<T>> {
+  /**
+   * List customers, newest first.
+   *
+   * `provisional` filters on whether the customer ever completed a
+   * payment. A checkout that captures an email commits its Customer
+   * before the charge, so a checkout nobody finished leaves a row behind:
+   * pass `false` for real customers only, `true` for the abandoned ones
+   * (the cart-recovery worklist), or omit for both. Abandoned rows are
+   * swept after the tenant's retention window.
+   */
+  list<T = unknown>(params: CustomerListParams = {}): Promise<ListResponseEnvelope<T>> {
     return this.get<ListResponseEnvelope<T>>("/v1/customers", params);
   }
 
@@ -615,9 +801,23 @@ export class Products extends BaseResource {
 }
 
 export class Prices extends BaseResource {
-  /** Create immutable billing terms for an existing Product. */
-  create<T = unknown>(params: CreatePriceParams): Promise<T> {
-    return this.post<T, CreatePriceParams>("/v1/prices", params);
+  /**
+   * Create immutable billing terms for an existing Product.
+   *
+   * A licensed price sends `amount_cents`. A metered price sends one of
+   * `amount_cents`, `unit_amount_decimal` (a rate finer than one minor
+   * unit, as a string) or `billing_scheme: "tiered"` with `tiers` and
+   * `tiers_mode`. Throws `TypeError` before any HTTP call if a decimal
+   * rate arrives as a number — see
+   * {@link CreatePriceParams.unit_amount_decimal}.
+   */
+  // `async` on purpose. The rate guard throws, and a synchronous throw out
+  // of a method typed `Promise<T>` escapes `.catch()` entirely — the caller
+  // would have to wrap the call site in try/catch as well, which nobody
+  // does for a promise-returning API. Marking it async turns the throw into
+  // a rejection, so one error path handles both.
+  async create<T = unknown>(params: CreatePriceParams): Promise<T> {
+    return this.post<T, CreatePriceParams>("/v1/prices", assertPriceRatesAreStrings(params));
   }
 
   retrieve<T = unknown>(id: string): Promise<T> {
@@ -783,13 +983,16 @@ export class Subscriptions extends BaseResource {
    *
    * Only valid when the subscription's price is `usage_type:
    * "metered"`; a licensed subscription is rejected with `400
-   * parameter_invalid`. Records accumulate until the renewal invoice
-   * rolls them up (`amount_cents × sum(quantity)`); the record's
-   * `invoice_id` stays `null` until then.
+   * parameter_invalid`. Records accumulate until the next period close
+   * rolls them into one invoice line; the record's `invoice_id` stays
+   * `null` until then. Records are immutable once written — they are the
+   * audit trail behind that line — so there is no update or delete.
    *
-   * Supports `Idempotency-Key` replay: retrying with the same key
-   * returns the same record instead of double-counting the usage,
-   * which is what makes at-least-once reporting pipelines safe.
+   * Two dedupe mechanisms, covering different failures. The
+   * `Idempotency-Key` the SDK sends covers a retry of this HTTP request,
+   * including its own internal retries. `params.identifier` covers a
+   * retry of *your* call, which arrives as a new request with a new key.
+   * See {@link CreateUsageRecordParams.identifier}.
    */
   createUsageRecord<T = unknown>(id: string, params: CreateUsageRecordParams): Promise<T> {
     return this.post<T, CreateUsageRecordParams>(`/v1/subscriptions/${id}/usage_records`, params);
@@ -819,6 +1022,28 @@ export class Subscriptions extends BaseResource {
       filters: { invoice_id: options.invoice_id },
     });
   }
+
+  /**
+   * Price the pending usage, before the period close bills it.
+   *
+   * `listUsageRecords({ invoice_id: "pending" })` gives the quantity; this
+   * gives the money. `net_cents` / `tax_cents` / `gross_cents` are
+   * computed through the same rate or tier table and the same VAT
+   * resolution the close itself uses, so it is a forecast of the real
+   * invoice rather than an estimate.
+   *
+   * **Read `will_charge` before promising a customer an amount.** A period
+   * whose total is under `minimum_charge_cents` (EUR 1.00) is not charged,
+   * because the payment provider would refuse it. The usage is not lost:
+   * it stays pending and rolls into the next period, which is then billed
+   * for both.
+   *
+   * `open_invoice_id` names an earlier cycle that is invoiced and still
+   * unsettled; while one is open, this period cannot be charged.
+   */
+  retrieveUsageSummary<T = unknown>(id: string): Promise<T> {
+    return this.get<T>(`/v1/subscriptions/${id}/usage_summary`);
+  }
 }
 
 export class Refunds extends BaseResource {
@@ -1146,6 +1371,63 @@ export class Invoices extends BaseResource {
   iter<T = unknown>(options: { pageSize?: number } = {}): AsyncIterableIterator<T> {
     return paginate<T>((p) => this.get("/v1/invoices", p), { pageSize: options.pageSize });
   }
+
+  /**
+   * Void an invoice: state that the sale was never owed.
+   *
+   * The invoice keeps its number and stays readable — a gapless series
+   * cannot lose a row — and stops being a receivable. Use it for an
+   * invoice that should not have been issued.
+   *
+   * A **paid** invoice is refused with a `ConflictError` whose `code` is
+   * `"invoice_not_voidable"`. That is deliberate rather than a
+   * limitation: once the money has moved, "never owed" is false, and the
+   * document that reverses a real sale is a credit note — refund the
+   * payment and one is issued when the refund settles.
+   *
+   * Idempotent: re-voiding an already-void invoice returns it unchanged.
+   */
+  void<T = unknown>(id: string, params: VoidInvoiceParams = {}): Promise<T> {
+    return this.post<T, VoidInvoiceParams>(`/v1/invoices/${id}/void`, params);
+  }
+}
+
+/**
+ * Read-only access to credit notes — the documents that reverse an
+ * issued invoice.
+ *
+ * There is no create: a credit note is issued for you when a refund
+ * settles, never on request, so that a numbered legal record is only
+ * minted once the money has actually moved. A refund that is still
+ * pending, one that fails, and a refund of a one-off charge that was
+ * never invoiced all produce none.
+ */
+export class CreditNotes extends BaseResource {
+  retrieve<T = unknown>(id: string): Promise<T> {
+    return this.get<T>(`/v1/credit_notes/${id}`);
+  }
+
+  /**
+   * Download the rendered credit note PDF as raw bytes. Same storage
+   * split as {@link Invoices.retrievePdf}: bytes inline or a followed
+   * `302`, and `501 rendering_pending` on a deployment with no renderer.
+   */
+  retrievePdf(id: string): Promise<ArrayBuffer> {
+    return this.t.requestBinary({ method: "GET", path: `/v1/credit_notes/${id}/pdf` });
+  }
+
+  list<T = unknown>(params: CreditNotesListParams = {}): Promise<ListResponseEnvelope<T>> {
+    return this.get<ListResponseEnvelope<T>>("/v1/credit_notes", params);
+  }
+
+  iter<T = unknown>(
+    options: { pageSize?: number; invoice_id?: string; customer_id?: string } = {},
+  ): AsyncIterableIterator<T> {
+    return paginate<T>((p) => this.get("/v1/credit_notes", p), {
+      pageSize: options.pageSize,
+      filters: { invoice_id: options.invoice_id, customer_id: options.customer_id },
+    });
+  }
 }
 
 /**

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.2.1";
+export const VERSION = "0.4.0";