@billkit-eu/sdk 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -8,6 +8,36 @@ 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.5.0] - 2026-09-22
+
+### Changed
+- `webhookEndpoints.getDelivery()` is now `retrieveDelivery()`. Every other
+  single-row fetch in every BillKit SDK is `retrieve`, and python and php
+  already spelled this one `retrieve_delivery` / `retrieveDelivery`, so node
+  was the outlier and the obvious name was a type error. `getDelivery` stays as
+  a deprecated alias — removing it would break callers over a naming
+  preference — and goes in the next major.
+
+### Fixed
+- `CustomerListParams` is exported from the package entry point. The interface
+  documented the `provisional` filter but could not be imported, so callers
+  building the params object ahead of the call had nothing to type it with.
+
+## [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

package/README.md

@@ -92,19 +92,21 @@ The client exposes one accessor per resource family. Each mirrors the verbs from
 
 | Accessor | Verbs |
 | --- | --- |
-| `client.customers` | `create`, `retrieve`, `update`, `delete`, `list`, `iter` |
+| `client.customers` | `create`, `retrieve`, `update`, `delete`, `list` (filter by `provisional`), `iter`, `setVatNumber`, `purge` |
 | `client.products` | `create`, `retrieve`, `update` (archive with `active: false`), `list`, `iter` |
 | `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`, `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.disputes` | `retrieve`, `list`, `iter` |
+| `client.webhookEndpoints` | `create`, `retrieve`, `update` (stop delivery with `status: "disabled"`), `delete`, `rotateSecret`, `list`, `iter`, `listDeliveries`, `iterDeliveries`, `retrieveDelivery`, `redeliver` |
 | `client.events` | `retrieve`, `list`, `iter` (filter by `type`) |
 | `client.tenant` | `capabilities`, `portalBranding`, `setPortalBranding`, `rotateProviderCredential` |
 | `client.coupons` | `create`, `retrieve`, `update` (withdraw with `active: false`), `validate`, `list`, `iter` |
 | `client.taxRates` | `create`, `retrieve`, `update` (retire with `active: false`), `list`, `iter` |
-| `client.invoices` | `retrieve`, `retrievePdf`, `list`, `iter` |
+| `client.invoices` | `retrieve`, `retrievePdf`, `list`, `iter`, `void` |
+| `client.creditNotes` | `retrieve`, `retrievePdf`, `list`, `iter` (filter by `invoice_id`, `customer_id`) |
 | `client.auditLogs` | `retrieve`, `list`, `iter` (filter by `action`, `resource_type`, `actor_id`) |
 | `client.payments` | `retrieve`, `list`, `iter` |
 | `client.billingPortalSessions` | `create`, `revoke` |
@@ -225,14 +227,16 @@ const session = await client.checkoutSessions.create<{ client_secret: string }>(
 });
 ```
 
-### Invoice PDFs
+### Invoice and credit-note PDFs
 
 ```ts
 const pdf = await client.invoices.retrievePdf("inv_123");
 await writeFile("invoice.pdf", Buffer.from(pdf));
+
+const credit = await client.creditNotes.retrievePdf("cn_123");
 ```
 
-Returns the raw bytes. S3-backed deployments answer with a redirect to a presigned URL, which is followed transparently under the SDK's own timeout and retry policy, so both storage adapters look the same from here. A deployment with PDF rendering disabled throws a `ServerError` with `code: "rendering_pending"`; `retrieve()` still gives you the structured invoice to render yourself.
+Returns the raw bytes. S3-backed deployments answer with a redirect to a presigned URL, which is followed transparently under the SDK's own timeout and retry policy, so both storage adapters look the same from here — and the API key is never sent to the storage host, because the presigned URL carries its own credential. A deployment with PDF rendering disabled throws a `ServerError` with `code: "rendering_pending"`; `retrieve()` still gives you the structured document to render yourself.
 
 ## Auto-pagination
 

package/dist/index.cjs

@@ -462,9 +462,23 @@ var WebhookEndpoints = class extends BaseResource {
     );
   }
   /** Fetch one delivery row for inspection before deciding to redeliver. */
-  getDelivery(endpointId, deliveryId) {
+  retrieveDelivery(endpointId, deliveryId) {
     return this.get(`/v1/webhook_endpoints/${endpointId}/deliveries/${deliveryId}`);
   }
+  /**
+   * @deprecated Renamed to {@link WebhookEndpoints.retrieveDelivery}.
+   *
+   * Every other single-row fetch in every BillKit SDK is `retrieve`; this
+   * one method was `get`, which meant reaching for the obvious name and
+   * getting a type error. The python and php clients already spell it
+   * `retrieve_delivery` / `retrieveDelivery`, so node was the outlier.
+   *
+   * Kept as an alias because removing it would break callers for a naming
+   * preference. It will go in the next major.
+   */
+  getDelivery(endpointId, deliveryId) {
+    return this.retrieveDelivery(endpointId, deliveryId);
+  }
   /**
    * Re-enqueue a delivery row for the dispatcher.
    *
@@ -620,6 +634,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) {
@@ -797,7 +851,7 @@ function sleep(ms) {
 }
 
 // src/version.ts
-var VERSION = "0.3.0";
+var VERSION = "0.5.0";
 
 // src/transport.ts
 var DEFAULT_BASE_URL = "https://api.billkit.eu";
@@ -1031,6 +1085,7 @@ var BillKit = class {
   coupons;
   taxRates;
   invoices;
+  creditNotes;
   auditLogs;
   payments;
   billingPortalSessions;
@@ -1053,6 +1108,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);