@billkit-eu/sdk 0.2.1 → 0.3.0

package/dist/index.js

@@ -35,6 +35,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;
@@ -98,6 +114,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);
   }
@@ -154,9 +180,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}`);
@@ -277,13 +317,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);
@@ -305,6 +348,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) {
@@ -731,7 +795,7 @@ function sleep(ms) {
 }
 
 // src/version.ts
-var VERSION = "0.2.1";
+var VERSION = "0.3.0";
 
 // src/transport.ts
 var DEFAULT_BASE_URL = "https://api.billkit.eu";