@billkit-eu/sdk 0.1.0 → 0.2.0

package/dist/index.js

@@ -85,6 +85,16 @@ var Customers = class extends BaseResource {
   update(id, params = {}) {
     return this.post(`/v1/customers/${id}`, params);
   }
+  /**
+   * Delete a customer. Resolves to `{ id, object: "customer", deleted:
+   * true }`, not the customer.
+   *
+   * The customer leaves the API: `retrieve()` 404s and they drop out of
+   * `list()`. Their payments, invoices and refunds are untouched, and so
+   * is their personal data — use {@link Customers.purge} for a GDPR
+   * erasure. Refused while they hold a subscription that can still
+   * charge them.
+   */
   delete(id, params = {}) {
     return this.del(`/v1/customers/${id}`, params);
   }
@@ -124,14 +134,18 @@ var Products = class extends BaseResource {
   retrieve(id) {
     return this.get(`/v1/products/${id}`);
   }
-  /** Patch mutable Product fields. */
+  /**
+   * Patch mutable Product fields, or archive it with `active: false`.
+   *
+   * Archiving is how you stop offering something. The product keeps its
+   * id and still comes back from `retrieve()` and `list()`, because what
+   * was sold under it has to stay readable, so there is no `delete()`.
+   * A checkout against any of its prices is refused from then on, and
+   * `active: true` un-archives.
+   */
   update(id, params) {
     return this.post(`/v1/products/${id}`, params);
   }
-  /** Archive a Product. */
-  delete(id, params = {}) {
-    return this.del(`/v1/products/${id}`, params);
-  }
   list(params = {}) {
     return this.get("/v1/products", params);
   }
@@ -147,6 +161,29 @@ var Prices = class extends BaseResource {
   retrieve(id) {
     return this.get(`/v1/prices/${id}`);
   }
+  /**
+   * Archive a Price so it stops selling, or put it back on sale.
+   *
+   * `update(id, { active: false })` archives. The price keeps its id and
+   * is still returned by `retrieve()` and by `list()`, because
+   * subscriptions renew against it by id and what they are charged has to
+   * stay readable. Subscriptions already on it keep renewing at it. What
+   * stops is new business: a checkout session against the price is
+   * refused and it is no longer offered as a plan change.
+   *
+   * `{ active: true }` undoes that. `active` is the only field because
+   * `amount_cents`, `currency` and `interval` are fixed at creation, and
+   * since none of them move here neither direction can change what a past
+   * charge was made under. To charge something different, create a new
+   * price.
+   *
+   * Sending the value a price already has returns it unchanged and emits
+   * no second event, so a retry is safe. Archiving emits
+   * `price.archived`; putting one back emits `price.updated`.
+   */
+  update(id, params) {
+    return this.post(`/v1/prices/${id}`, params);
+  }
   list(params = {}) {
     return this.get("/v1/prices", params);
   }
@@ -178,11 +215,23 @@ var Subscriptions = class extends BaseResource {
   retrieve(id) {
     return this.get(`/v1/subscriptions/${id}`);
   }
+  /**
+   * List subscriptions, newest first, optionally filtered.
+   *
+   * Reach for `renewal_state: "paused"` rather than `status: "paused"`
+   * to find paused subscriptions; see `SubscriptionsListParams`.
+   */
   list(params = {}) {
     return this.get("/v1/subscriptions", params);
   }
+  /**
+   * Walk every page of `list()`. Filters are carried onto each page
+   * request, so a filtered walk narrows server-side instead of paging
+   * the whole history and discarding rows client-side.
+   */
   iter(options = {}) {
-    return paginate((p) => this.get("/v1/subscriptions", p), { pageSize: options.pageSize });
+    const { pageSize, ...filter } = options;
+    return paginate((p) => this.get("/v1/subscriptions", { ...filter, ...p }), { pageSize });
   }
   cancel(id, params = {}) {
     return this.postEmpty(`/v1/subscriptions/${id}/cancel`, params);
@@ -223,6 +272,39 @@ var Subscriptions = class extends BaseResource {
       { idempotencyKey: params.idempotencyKey }
     );
   }
+  /**
+   * Report consumption against a metered subscription.
+   *
+   * 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.
+   *
+   * 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.
+   */
+  createUsageRecord(id, params) {
+    return this.post(`/v1/subscriptions/${id}/usage_records`, params);
+  }
+  /**
+   * List usage records for one subscription.
+   *
+   * Pass `invoice_id: "pending"` to reconcile what has been reported
+   * but not yet billed, or a concrete invoice id to see what that
+   * invoice charged for.
+   */
+  listUsageRecords(id, params = {}) {
+    return this.get(`/v1/subscriptions/${id}/usage_records`, params);
+  }
+  /** Walk every page of `listUsageRecords()` for one subscription. */
+  iterUsageRecords(id, options = {}) {
+    return paginate((p) => this.get(`/v1/subscriptions/${id}/usage_records`, p), {
+      pageSize: options.pageSize,
+      filters: { invoice_id: options.invoice_id }
+    });
+  }
 };
 var Refunds = class extends BaseResource {
   create(params) {
@@ -256,9 +338,28 @@ var WebhookEndpoints = class extends BaseResource {
   retrieve(id) {
     return this.get(`/v1/webhook_endpoints/${id}`);
   }
+  /**
+   * Update an endpoint, or stop delivery with `status: "disabled"`.
+   *
+   * Disabling keeps the endpoint, its signing secret and its delivery
+   * history, and `status: "enabled"` resumes. Use {@link
+   * WebhookEndpoints.delete} when the endpoint should not exist at all:
+   * disabling is reversible and deleting is not.
+   */
   update(id, params) {
     return this.post(`/v1/webhook_endpoints/${id}`, params);
   }
+  /**
+   * Delete an endpoint. Resolves to `{ id, object: "webhook_endpoint",
+   * deleted: true }`, not the endpoint.
+   *
+   * A URL registered by mistake should not be a permanent fixture of the
+   * account, so this removes it: `retrieve()` 404s afterwards and it is
+   * gone from `list()`. Its delivery attempts go with it, because they
+   * are readable only through the endpoint that owns them. The events
+   * themselves are untouched and still in `client.events`, so what you
+   * were sent stays on record.
+   */
   delete(id, params = {}) {
     return this.del(`/v1/webhook_endpoints/${id}`, params);
   }
@@ -367,12 +468,17 @@ var Coupons = class extends BaseResource {
   retrieve(id) {
     return this.get(`/v1/coupons/${id}`);
   }
+  /**
+   * Update a coupon's limits, or withdraw it with `active: false`.
+   *
+   * A withdrawn code is refused at checkout while the coupon stays
+   * readable and discounts already applied keep working out, so there is
+   * no `delete()`: a coupon that has been redeemed is part of what a
+   * customer was charged. `active: true` brings the campaign back.
+   */
   update(id, params) {
     return this.post(`/v1/coupons/${id}`, params);
   }
-  delete(id, params = {}) {
-    return this.del(`/v1/coupons/${id}`, params);
-  }
   /**
    * Server-side dry-run of a coupon redemption.
    *
@@ -399,12 +505,17 @@ var TaxRates = class extends BaseResource {
   retrieve(id) {
     return this.get(`/v1/tax_rates/${id}`);
   }
+  /**
+   * Correct a rate, retire it with `active: false`, or bring one back.
+   *
+   * Retiring is how you stop charging VAT in a country. The rate stays
+   * readable, because an invoice records the percentage it charged and
+   * you have to be able to point at the rate that produced it, so there
+   * is no `delete()`.
+   */
   update(id, params) {
     return this.post(`/v1/tax_rates/${id}`, params);
   }
-  delete(id, params = {}) {
-    return this.del(`/v1/tax_rates/${id}`, params);
-  }
   list(params = {}) {
     return this.get("/v1/tax_rates", params);
   }
@@ -416,6 +527,27 @@ var Invoices = class extends BaseResource {
   retrieve(id) {
     return this.get(`/v1/invoices/${id}`);
   }
+  /**
+   * Download the rendered invoice PDF as raw bytes.
+   *
+   * ```ts
+   * const pdf = await client.invoices.retrievePdf("inv_123");
+   * await writeFile("invoice.pdf", Buffer.from(pdf));
+   * ```
+   *
+   * Blob-backed deployments stream the bytes inline; S3-backed ones
+   * answer `302` to a presigned URL, which `fetch` follows for us under
+   * the SDK's own timeout and retry policy — so both storage adapters
+   * look identical from here.
+   *
+   * Deployments with `INVOICE_PDF_ENABLED=false` never render one and
+   * answer `501 rendering_pending`, which surfaces as a `ServerError`
+   * whose `code` is `"rendering_pending"`; `retrieve()` still returns the
+   * structured invoice for tenants who render their own.
+   */
+  retrievePdf(id) {
+    return this.t.requestBinary({ method: "GET", path: `/v1/invoices/${id}/pdf` });
+  }
   list(params = {}) {
     return this.get("/v1/invoices", params);
   }
@@ -521,19 +653,6 @@ var RateLimitError = class extends BillKitError {
     this.retryAfter = options.retryAfter;
   }
 };
-var TYPE_TO_CLASS = {
-  api_connection_error: APIConnectionError,
-  // ``api_error`` is the Stripe-convention type for 5xx, so surface it as
-  // ServerError (a subclass of APIError) so `catch (e instanceof
-  // ServerError)` works without false negatives.
-  api_error: ServerError,
-  authentication_error: AuthenticationError,
-  permission_error: PermissionError,
-  invalid_request_error: InvalidRequestError,
-  idempotency_error: ConflictError,
-  conflict: ConflictError,
-  rate_limit_error: RateLimitError
-};
 function fallbackType(status) {
   if (status === 401) return "authentication_error";
   if (status === 403) return "permission_error";
@@ -543,13 +662,13 @@ function fallbackType(status) {
   if (status >= 500) return "api_error";
   return "invalid_request_error";
 }
-function fallbackClass(status) {
+function classForStatus(status) {
+  if (status >= 500) return ServerError;
   if (status === 401) return AuthenticationError;
   if (status === 403) return PermissionError;
   if (status === 404) return ResourceMissingError;
   if (status === 409) return ConflictError;
   if (status === 429) return RateLimitError;
-  if (status >= 500) return ServerError;
   return InvalidRequestError;
 }
 function errorFromResponse(args) {
@@ -557,9 +676,7 @@ function errorFromResponse(args) {
   const envelope = typeof body === "object" && body !== null && "error" in body ? body.error ?? {} : {};
   const type = envelope.type ?? fallbackType(status);
   const message = envelope.message ?? `BillKit API returned HTTP ${status} with no error body.`;
-  let cls = TYPE_TO_CLASS[type] ?? fallbackClass(status);
-  if (status === 404 && cls === InvalidRequestError) cls = ResourceMissingError;
-  if (status === 409 && cls === InvalidRequestError) cls = ConflictError;
+  const cls = classForStatus(status);
   const options = {
     type,
     code: envelope.code,
@@ -598,9 +715,11 @@ function backoffForMs(attempt, policy) {
   const jittered = capped + (Math.random() * 2 - 1) * jitterRange;
   return Math.max(0, jittered);
 }
-function shouldRetry(status, attempt, policy, retryAfterMs) {
+var IN_PROGRESS_CODE = "idempotency_in_progress";
+function shouldRetry(status, attempt, policy, retryAfterMs, errorCode) {
   if (attempt >= policy.maxAttempts) return false;
   if (status === null) return true;
+  if (status === 409) return errorCode === IN_PROGRESS_CODE;
   if (status === 429) {
     if (retryAfterMs === void 0 || retryAfterMs < 0) return false;
     return policy.maxRetryAfterMs === void 0 || retryAfterMs <= policy.maxRetryAfterMs;
@@ -612,7 +731,7 @@ function sleep(ms) {
 }
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.0";
 
 // src/transport.ts
 var DEFAULT_BASE_URL = "https://api.billkit.eu";
@@ -662,8 +781,7 @@ function buildHeaders(apiKey, hasBody, idempotencyKey, extra) {
   }
   return headers;
 }
-async function parseJson(response) {
-  const text = await response.text();
+function parseJsonText(text) {
   if (!text) return null;
   try {
     return JSON.parse(text);
@@ -671,6 +789,17 @@ async function parseJson(response) {
     return null;
   }
 }
+async function parseJson(response) {
+  return parseJsonText(await response.text());
+}
+async function readBody(response, responseType) {
+  if (responseType !== "binary") {
+    return { parsed: await parseJson(response), binary: void 0 };
+  }
+  const buffer = await response.arrayBuffer();
+  if (response.ok) return { parsed: null, binary: buffer };
+  return { parsed: parseJsonText(new TextDecoder().decode(buffer)), binary: void 0 };
+}
 function parseRetryAfterMs(header) {
   if (!header) return void 0;
   const n = Number.parseFloat(header);
@@ -714,7 +843,21 @@ var Transport = class {
     }
     this.fetchFn = fetchFn.bind(globalThis);
   }
+  /**
+   * Fetch a binary document (currently only the invoice PDF).
+   *
+   * Same retry policy, same timeout, same typed errors as
+   * {@link Transport.request}; only the success-path decoding differs.
+   * `fetch` follows the storage adapter's `302` to the signed URL by
+   * itself, and the WHATWG spec drops the `Authorization` header on that
+   * cross-origin hop — which is correct, since a presigned URL carries
+   * its own credential and must not be handed BillKit's API key.
+   */
+  requestBinary(options) {
+    return this.request({ ...options, responseType: "binary" });
+  }
   async request(options) {
+    const responseType = options.responseType ?? "json";
     const idempotencyKey = autoIdempotencyKey(options.method, options.idempotencyKey);
     const url = buildUrl(this.baseUrl, options.path, options.query);
     const headers = buildHeaders(
@@ -736,6 +879,7 @@ var Transport = class {
       const startedAt = Date.now();
       let response;
       let parsedBody;
+      let binaryBody;
       try {
         const init = {
           method: options.method,
@@ -744,7 +888,7 @@ var Transport = class {
         };
         if (body !== void 0) init.body = body;
         response = await this.fetchFn(url, init);
-        parsedBody = await parseJson(response);
+        ({ parsed: parsedBody, binary: binaryBody } = await readBody(response, responseType));
       } catch (err) {
         lastError = connectionError(err, this.timeoutMs);
         if (!shouldRetry(null, attempt, this.retryPolicy)) throw lastError;
@@ -768,6 +912,7 @@ var Transport = class {
         requestId: requestId ?? null
       });
       if (response.ok) {
+        if (responseType === "binary") return binaryBody;
         return parsedBody ?? void 0;
       }
       const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
@@ -777,7 +922,7 @@ var Transport = class {
         requestId,
         retryAfter: retryAfterMs === void 0 ? void 0 : retryAfterMs / 1e3
       });
-      if (!shouldRetry(response.status, attempt, this.retryPolicy, retryAfterMs)) {
+      if (!shouldRetry(response.status, attempt, this.retryPolicy, retryAfterMs, error.code)) {
         throw error;
       }
       lastError = error;