@billkit-eu/sdk 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -8,7 +8,66 @@ 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.
 
-## [Unreleased]
+## [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
+- Documentation only. API keys are now `bk_live_…` / `bk_test_…` and webhook
+  signing secrets `bkwhsec_…`; every example here used the previous
+  Stripe-shaped `sk_`/`whsec_` spelling. No code in this package changed: it
+  never parsed the prefix, it forwards the key as a bearer token.
+
+## [0.2.0]
 
 ### Added
 - `client.prices.update(id, { active: false })` archives a price
@@ -71,7 +130,7 @@ First public release.
 - **Opt-in logging.** Pass a `logger` to see the request/retry lifecycle:
 
   ```ts
-  const client = new BillKit({ apiKey: "sk_test_...", logger: console });
+  const client = new BillKit({ apiKey: "bk_test_...", logger: console });
   ```
 
   Omitted (the default) the SDK is silent: it ships no logger, no transport

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.
@@ -193,7 +260,7 @@ for await (const row of client.auditLogs.iter({ actor_id: "act_1" })) {
 import { BillKit } from "@billkit-eu/sdk";
 
 const client = new BillKit({
-  apiKey: "sk_test_...",                  // or set BILLKIT_API_KEY
+  apiKey: "bk_test_...",                  // or set BILLKIT_API_KEY
   baseUrl: "https://api.billkit.eu",   // override for self-hosted
   timeoutMs: 30_000,
   retryPolicy: {
@@ -259,7 +326,7 @@ The status is the field the API cannot get wrong. Requests that never reach a ro
 The SDK is **silent by default**. It ships no logger, no transport and no destination, so it can't take over your application's output because it never picks one. Hand it a logger to opt in:
 
 ```ts
-const client = new BillKit({ apiKey: "sk_test_...", logger: console });
+const client = new BillKit({ apiKey: "bk_test_...", logger: console });
 ```
 
 ```
@@ -285,7 +352,7 @@ If your logger takes context first, wrap it:
 
 ```ts
 const client = new BillKit({
-  apiKey: "sk_test_...",
+  apiKey: "bk_test_...",
   logger: {
     debug: (m, c) => pino.debug(c, m),
     warn: (m, c) => pino.warn(c, m),

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) {
@@ -365,7 +429,7 @@ var WebhookEndpoints = class extends BaseResource {
   delete(id, params = {}) {
     return this.del(`/v1/webhook_endpoints/${id}`, params);
   }
-  /** Rotate the signing secret. The new `whsec_...` is returned once. */
+  /** Rotate the signing secret. The new `bkwhsec_...` is returned once. */
   rotateSecret(id, params = {}) {
     return this.postEmpty(`/v1/webhook_endpoints/${id}/rotate_secret`, params);
   }
@@ -733,7 +797,7 @@ function sleep(ms) {
 }
 
 // src/version.ts
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 
 // src/transport.ts
 var DEFAULT_BASE_URL = "https://api.billkit.eu";