@billkit-eu/sdk 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@billkit-eu/sdk",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Official Node.js SDK for BillKit: a Stripe-Billing-shape multi-tenant SaaS API on Mollie.",
   "type": "module",
   "main": "./dist/index.cjs",

package/src/client.ts

@@ -12,6 +12,7 @@ import {
   BillingPortalSessions,
   CheckoutSessions,
   Coupons,
+  CreditNotes,
   Customers,
   Disputes,
   Events,
@@ -58,6 +59,7 @@ export class BillKit {
   readonly coupons: Coupons;
   readonly taxRates: TaxRates;
   readonly invoices: Invoices;
+  readonly creditNotes: CreditNotes;
   readonly auditLogs: AuditLogs;
   readonly payments: Payments;
   readonly billingPortalSessions: BillingPortalSessions;
@@ -81,6 +83,7 @@ export class BillKit {
     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);

package/src/index.ts

@@ -81,6 +81,8 @@ export type {
   CreateTaxRateParams,
   CreateUsageRecordParams,
   CreateWebhookEndpointParams,
+  CreditNotesListParams,
+  CustomerListParams,
   EventsListParams,
   IdempotencyOptions,
   ListParams,
@@ -96,6 +98,7 @@ export type {
   UpdateWebhookEndpointParams,
   UsageRecordsListParams,
   ValidateCouponParams,
+  VoidInvoiceParams,
 } from "./resources.js";
 export { DEFAULT_RETRY_POLICY, type RetryPolicy } from "./retry.js";
 export { VERSION } from "./version.js";

package/src/resources.ts

@@ -566,6 +566,23 @@ export interface AuditLogsListParams extends BaseListParams {
   actor_id?: string;
 }
 
+/**
+ * `creditNotes.list` params.
+ *
+ * `invoice_id` answers "was this sale credited, and by how much", which is
+ * the question when reconciling one invoice; `customer_id` answers it for
+ * everything credited back to one buyer.
+ */
+export interface CreditNotesListParams extends BaseListParams {
+  invoice_id?: string;
+  customer_id?: string;
+}
+
+/** `invoices.void` params. `reason` is recorded on the audit row only. */
+export interface VoidInvoiceParams extends IdempotencyOptions {
+  reason?: string;
+}
+
 export interface CreateBillingPortalSessionParams extends IdempotencyOptions {
   subscription_id: string;
   return_url: string;
@@ -1150,10 +1167,25 @@ export class WebhookEndpoints extends BaseResource {
   }
 
   /** Fetch one delivery row for inspection before deciding to redeliver. */
-  getDelivery<T = unknown>(endpointId: string, deliveryId: string): Promise<T> {
+  retrieveDelivery<T = unknown>(endpointId: string, deliveryId: string): Promise<T> {
     return this.get<T>(`/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<T = unknown>(endpointId: string, deliveryId: string): Promise<T> {
+    return this.retrieveDelivery<T>(endpointId, deliveryId);
+  }
+
   /**
    * Re-enqueue a delivery row for the dispatcher.
    *
@@ -1354,6 +1386,63 @@ export class Invoices extends BaseResource {
   iter<T = unknown>(options: { pageSize?: number } = {}): AsyncIterableIterator<T> {
     return paginate<T>((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<T = unknown>(id: string, params: VoidInvoiceParams = {}): Promise<T> {
+    return this.post<T, VoidInvoiceParams>(`/v1/invoices/${id}/void`, params);
+  }
+}
+
+/**
+ * Read-only access to credit notes — the documents that reverse an
+ * issued invoice.
+ *
+ * There is no create: a credit note is issued for you when a refund
+ * settles, never on request, so that a numbered legal record is only
+ * minted once the money has actually moved. A refund that is still
+ * pending, one that fails, and a refund of a one-off charge that was
+ * never invoiced all produce none.
+ */
+export class CreditNotes extends BaseResource {
+  retrieve<T = unknown>(id: string): Promise<T> {
+    return this.get<T>(`/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: string): Promise<ArrayBuffer> {
+    return this.t.requestBinary({ method: "GET", path: `/v1/credit_notes/${id}/pdf` });
+  }
+
+  list<T = unknown>(params: CreditNotesListParams = {}): Promise<ListResponseEnvelope<T>> {
+    return this.get<ListResponseEnvelope<T>>("/v1/credit_notes", params);
+  }
+
+  iter<T = unknown>(
+    options: { pageSize?: number; invoice_id?: string; customer_id?: string } = {},
+  ): AsyncIterableIterator<T> {
+    return paginate<T>((p) => this.get("/v1/credit_notes", p), {
+      pageSize: options.pageSize,
+      filters: { invoice_id: options.invoice_id, customer_id: options.customer_id },
+    });
+  }
 }
 
 /**

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.3.0";
+export const VERSION = "0.5.0";