@billkit-eu/sdk 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -8,6 +8,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 Versioning is independent of the Python SDK; the two ship on their own cadence,
 so the numbers will diverge after this first release.
 
+## [0.4.0]
+
+### Added
+- **`creditNotes`** — `retrieve`, `list`, `iter` and `retrievePdf`. A credit
+  note is the document that reverses an issued invoice; one is created for you
+  when a refund settles, so there is no `create` here. `list` takes
+  `invoice_id` to answer "was this sale credited, and by how much".
+- **`invoices.void(id)`** — records that an invoice was never owed. It keeps
+  its number and stays readable; it just stops being a receivable.
+
+  A **paid** invoice is refused with a `ConflictError` whose `code` is
+  `"invoice_not_voidable"`. Once the money has moved, "never owed" is not
+  true — refund the payment instead, and a credit note is issued when the
+  refund settles. Voiding twice is a no-op.
+
+## [0.3.0]
+
+### Added
+- **Metered pricing below one minor unit.** `prices.create` takes
+  `unit_amount_decimal`: a per-unit rate in **minor units** with up to 12
+  decimal places, so `"0.02"` (0.02 cents, i.e. EUR 0.0002 per unit) is finally
+  expressible. `amount_cents` is an integer and could never say it. Metered
+  prices only.
+
+  It is typed as a `string`, so a `number` is a compile error. A number is also
+  refused at runtime with a `TypeError`, for the callers the type system cannot
+  reach — plain JavaScript, a value that came through `any`, a parsed JSON body.
+  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.
+- **Tiered pricing.** `prices.create({ billing_scheme: "tiered", tiers_mode,
+  tiers })`, with the new exported `PriceTier` type. `tiers_mode: "graduated"`
+  prices the units inside each band; `"volume"` lets the period total pick one
+  band which then prices every unit. The same table under the two modes is a
+  different bill, so the mode is required rather than defaulted. The last band
+  must be `up_to: "inf"`. Each band's `unit_amount_decimal` gets the same
+  string-only treatment.
+- **`identifier` on `subscriptions.createUsageRecord`**, for the retry an
+  `Idempotency-Key` cannot catch. The key covers a retry of one HTTP request;
+  `identifier` covers a retry of *your own* call — a job runner replaying a
+  task, a queue delivering twice — which arrives as a genuinely new request with
+  a new key. It is unique within the subscription, and a second report of the
+  same identifier returns the first record unchanged rather than billing twice.
+  If your reporting pipeline is at-least-once, this is the one that matters.
+- **`subscriptions.retrieveUsageSummary(id)`**, the money view of pending usage:
+  `pending_quantity`, `net_cents` / `tax_cents` / `gross_cents` computed through
+  the same rate or tier table the period close uses, and `will_charge`. Read
+  `will_charge` before promising a customer an amount: a period under
+  `minimum_charge_cents` (EUR 1.00) is **not** charged, because the provider
+  would refuse it, and the usage rolls into the next period instead. Previously
+  the only record of that decision was a server log line. `open_invoice_id`
+  names an earlier cycle still unsettled.
+- **`refund_on_cancel` on `prices.create`.** Server-side since the `0066`
+  migration and unreachable from this SDK until now. `"full"` or `"prorated"`
+  issues the refund a cancellation promised without anyone having to remember
+  to. Metered prices must leave it at `"none"`.
+
+### Changed
+- `CreatePriceParams.amount_cents` is now **optional**, because a price can be
+  priced by `unit_amount_decimal` or by `tiers` instead. Exactly one of the
+  three is required, and the server refuses a price with none of them. Existing
+  calls are unaffected.
+- `prices.create` is now `async`. It was already `Promise`-returning, but the
+  new rate guard throws, and a synchronous throw out of a method typed
+  `Promise<T>` escapes `.catch()` — so the throw is delivered as a rejection
+  instead, and one error path handles both.
+
 ## [0.2.1]
 
 ### Changed

package/README.md

@@ -97,7 +97,7 @@ The client exposes one accessor per resource family. Each mirrors the verbs from
 | `client.prices` | `create`, `retrieve`, `update` (archive with `active: false`, restore with `active: true`), `list`, `iter` |
 | `client.checkoutSessions` | `create`, `retrieve` |
 | `client.oneShotPayments` | `create`, `retrieve` |
-| `client.subscriptions` | `retrieve`, `list`, `iter` (filter by `customer_id`, `status`, `renewal_state`), `cancel`, `pause`, `resume`, `previewUpdate`, `update`, `reauthorizePaymentMethod` |
+| `client.subscriptions` | `retrieve`, `list`, `iter` (filter by `customer_id`, `status`, `renewal_state`), `cancel`, `pause`, `resume`, `reactivate`, `previewUpdate`, `update`, `reauthorizePaymentMethod`, `createUsageRecord`, `listUsageRecords`, `iterUsageRecords`, `retrieveUsageSummary` |
 | `client.refunds` | `create`, `retrieve`, `list`, `iter` |
 | `client.webhookEndpoints` | `create`, `retrieve`, `update` (stop delivery with `status: "disabled"`), `delete`, `rotateSecret`, `list`, `iter`, `listDeliveries`, `iterDeliveries`, `getDelivery`, `redeliver` |
 | `client.events` | `retrieve`, `list`, `iter` (filter by `type`) |
@@ -143,6 +143,73 @@ const paused = await client.subscriptions.list({ renewal_state: "paused" });
 
 `status: "paused"` is not an accepted value and comes back as `InvalidRequestError`. Both filters take a comma-separated list (`status: "active,past_due"`), and an unrecognised value is rejected rather than silently ignored.
 
+### Metered billing
+
+A metered price charges for what was consumed. You report usage; at each period close BillKit invoices the period's total and charges the stored mandate.
+
+There are three ways to price a unit, and a price uses exactly one of them.
+
+```ts
+// 1. Whole minor units: 5 cents per unit.
+await client.prices.create({
+  product_id: product.id, amount_cents: 5,
+  currency: "EUR", interval: "month", usage_type: "metered",
+});
+
+// 2. Finer than a minor unit. "0.02" is 0.02 CENTS, i.e. EUR 0.0002 per unit:
+//    the canonical per-API-call price, which no integer can express.
+await client.prices.create({
+  product_id: product.id, unit_amount_decimal: "0.02",
+  currency: "EUR", interval: "month", usage_type: "metered",
+});
+
+// 3. By bands. "graduated" prices the units inside each band; "volume" lets
+//    the period total pick one band which then prices every unit. The same
+//    table under the two modes is a different bill, so the mode is required.
+await client.prices.create({
+  product_id: product.id, currency: "EUR", interval: "month",
+  usage_type: "metered", billing_scheme: "tiered", tiers_mode: "graduated",
+  tiers: [
+    { up_to: 1000, unit_amount: 1 },                // first 1,000 at EUR 0.01
+    { up_to: "inf", unit_amount_decimal: "0.5" },   // then EUR 0.005
+  ],
+});
+```
+
+`amount_cents` is optional for that reason. Send none of the three and the server refuses the price.
+
+**`unit_amount_decimal` is a `string`, and a `number` will not compile.** A JS number is an IEEE-754 double and 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. A number that reaches it anyway (plain JavaScript, a value through `any`, a parsed body) is rejected with a `TypeError` before the request goes out. The same applies to a band's `unit_amount_decimal`.
+
+The rate is in **minor units**, so `"0.02"` is two hundredths of a cent, not two cents. The period's whole quantity is multiplied by the rate and rounded once, at the invoice, so a sub-cent rate loses nothing per record.
+
+The last band must be `up_to: "inf"`, because a bounded top band cannot price the usage above it. Write a free band as `unit_amount: 0`. Metered prices must use `interval: "month"`, cannot have `trial_days`, and cannot set `refund_on_cancel`.
+
+#### Reporting usage exactly once
+
+```ts
+await client.subscriptions.createUsageRecord(sub.id, {
+  quantity: 1200,
+  identifier: "job-2026-09-19T10:00Z", // your id for what you are metering
+});
+```
+
+Two dedupe mechanisms, and they cover different failures. The `Idempotency-Key` the SDK sends covers a retry of *that HTTP request*, including its 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 reaches the API as a genuinely new request with a new key. A second report of the same identifier returns the first record unchanged rather than billing twice. If your reporting pipeline is at-least-once, `identifier` is the one that matters.
+
+Records are immutable once written: they are the audit trail behind an invoice line, so there is no update or delete.
+
+#### Knowing what the next invoice will be
+
+```ts
+const summary = await client.subscriptions.retrieveUsageSummary<{
+  pending_quantity: number;
+  gross_cents: number;
+  will_charge: boolean;
+  minimum_charge_cents: number;
+}>(sub.id);
+```
+
+Check `will_charge` before you promise 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. `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 this is a forecast of the real invoice rather than an estimate. `open_invoice_id` names an earlier cycle that is invoiced and still unsettled; while one is open, this period cannot be charged.
+
 ### Embedded checkout
 
 Pass `ui_mode: "embedded"` and the session comes back with a `client_secret` instead of a `url`. Hand that to [`@billkit-eu/js`](https://www.npmjs.com/package/@billkit-eu/js) or [`@billkit-eu/react`](https://www.npmjs.com/package/@billkit-eu/react) and the card fields render on your own page, inside a cross-origin iframe. `cancel_url` is still required.

package/dist/index.cjs

@@ -37,6 +37,22 @@ function splitIdempotency(params) {
   const { idempotencyKey, ...rest } = params;
   return { body: dropUndefined(rest), idempotencyKey };
 }
+function assertDecimalRateIsString(value, field) {
+  if (value === void 0 || 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)}".`
+  );
+}
+function assertPriceRatesAreStrings(params) {
+  assertDecimalRateIsString(params.unit_amount_decimal, "unit_amount_decimal");
+  (params.tiers ?? []).forEach((tier, index) => {
+    assertDecimalRateIsString(
+      tier?.unit_amount_decimal,
+      `tiers[${index}].unit_amount_decimal`
+    );
+  });
+  return params;
+}
 var BaseResource = class {
   constructor(t) {
     this.t = t;
@@ -100,6 +116,16 @@ var Customers = class extends BaseResource {
   delete(id, params = {}) {
     return this.del(`/v1/customers/${id}`, params);
   }
+  /**
+   * 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(params = {}) {
     return this.get("/v1/customers", params);
   }
@@ -156,9 +182,23 @@ var Products = class extends BaseResource {
   }
 };
 var Prices = class extends BaseResource {
-  /** Create immutable billing terms for an existing Product. */
-  create(params) {
-    return this.post("/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(params) {
+    return this.post("/v1/prices", assertPriceRatesAreStrings(params));
   }
   retrieve(id) {
     return this.get(`/v1/prices/${id}`);
@@ -279,13 +319,16 @@ var Subscriptions = class 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(id, params) {
     return this.post(`/v1/subscriptions/${id}/usage_records`, params);
@@ -307,6 +350,27 @@ var Subscriptions = class 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(id) {
+    return this.get(`/v1/subscriptions/${id}/usage_summary`);
+  }
 };
 var Refunds = class extends BaseResource {
   create(params) {
@@ -556,6 +620,46 @@ var Invoices = class extends BaseResource {
   iter(options = {}) {
     return paginate((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(id, params = {}) {
+    return this.post(`/v1/invoices/${id}/void`, params);
+  }
+};
+var CreditNotes = class extends BaseResource {
+  retrieve(id) {
+    return this.get(`/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) {
+    return this.t.requestBinary({ method: "GET", path: `/v1/credit_notes/${id}/pdf` });
+  }
+  list(params = {}) {
+    return this.get("/v1/credit_notes", params);
+  }
+  iter(options = {}) {
+    return paginate((p) => this.get("/v1/credit_notes", p), {
+      pageSize: options.pageSize,
+      filters: { invoice_id: options.invoice_id, customer_id: options.customer_id }
+    });
+  }
 };
 var AuditLogs = class extends BaseResource {
   retrieve(id) {
@@ -733,7 +837,7 @@ function sleep(ms) {
 }
 
 // src/version.ts
-var VERSION = "0.2.1";
+var VERSION = "0.4.0";
 
 // src/transport.ts
 var DEFAULT_BASE_URL = "https://api.billkit.eu";
@@ -967,6 +1071,7 @@ var BillKit = class {
   coupons;
   taxRates;
   invoices;
+  creditNotes;
   auditLogs;
   payments;
   billingPortalSessions;
@@ -989,6 +1094,7 @@ var BillKit = class {
     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);