@billkit-eu/sdk 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -705,6 +705,21 @@ interface AuditLogsListParams extends BaseListParams {
     resource_type?: string;
     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.
+ */
+interface CreditNotesListParams extends BaseListParams {
+    invoice_id?: string;
+    customer_id?: string;
+}
+/** `invoices.void` params. `reason` is recorded on the audit row only. */
+interface VoidInvoiceParams extends IdempotencyOptions {
+    reason?: string;
+}
 interface CreateBillingPortalSessionParams extends IdempotencyOptions {
     subscription_id: string;
     return_url: string;
@@ -1010,6 +1025,18 @@ declare class WebhookEndpoints extends BaseResource {
         pageSize?: number;
     }): AsyncIterableIterator<T>;
     /** Fetch one delivery row for inspection before deciding to redeliver. */
+    retrieveDelivery<T = unknown>(endpointId: string, deliveryId: string): Promise<T>;
+    /**
+     * @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>;
     /**
      * Re-enqueue a delivery row for the dispatcher.
@@ -1131,6 +1158,47 @@ declare class Invoices extends BaseResource {
     iter<T = unknown>(options?: {
         pageSize?: number;
     }): AsyncIterableIterator<T>;
+    /**
+     * 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>;
+}
+/**
+ * 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.
+ */
+declare class CreditNotes extends BaseResource {
+    retrieve<T = unknown>(id: string): Promise<T>;
+    /**
+     * 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>;
+    list<T = unknown>(params?: CreditNotesListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+        invoice_id?: string;
+        customer_id?: string;
+    }): AsyncIterableIterator<T>;
 }
 /**
  * Read-only access to the per-tenant audit log.
@@ -1205,6 +1273,7 @@ declare class BillKit {
     readonly coupons: Coupons;
     readonly taxRates: TaxRates;
     readonly invoices: Invoices;
+    readonly creditNotes: CreditNotes;
     readonly auditLogs: AuditLogs;
     readonly payments: Payments;
     readonly billingPortalSessions: BillingPortalSessions;
@@ -1261,7 +1330,7 @@ declare class RateLimitError extends BillKitError {
     });
 }
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.5.0";
 
 /**
  * Verify `BillKit-Signature: t=<unix>,v1=<hex>` headers.
@@ -1293,4 +1362,4 @@ interface VerifyWebhookOptions {
 }
 declare function verifyWebhookSignature<T = unknown>(options: VerifyWebhookOptions): Promise<T>;
 
-export { APIConnectionError, APIError, type AuditLogsListParams, AuthenticationError, type BaseListParams, BillKit, BillKitError, type BillKitLogger, type BillKitOptions, ConflictError, type CreateBillingPortalSessionParams, type CreateCheckoutSessionParams, type CreateCouponParams, type CreateCustomerParams, type CreateOneShotPaymentParams, type CreatePriceParams, type CreateProductParams, type CreateRefundParams, type CreateTaxRateParams, type CreateUsageRecordParams, type CreateWebhookEndpointParams, DEFAULT_RETRY_POLICY, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, type EventsListParams, type IdempotencyOptions, InvalidRequestError, type ListParams, type ListResponseEnvelope, type LogContext, NOOP_LOGGER, type PaginateOptions, PermissionError, type PriceTier, type PricesListParams, RateLimitError, ResourceMissingError, type RetryPolicy, type RotateProviderCredentialParams, ServerError, type SetPortalBrandingParams, type SubscriptionsListParams, type UpdateCouponParams, type UpdateCustomerParams, type UpdateProductParams, type UpdateTaxRateParams, type UpdateWebhookEndpointParams, type UsageRecordsListParams, VERSION, type ValidateCouponParams, type VerifyWebhookOptions, WebhookVerificationError, paginate, verifyWebhookSignature };
+export { APIConnectionError, APIError, type AuditLogsListParams, AuthenticationError, type BaseListParams, BillKit, BillKitError, type BillKitLogger, type BillKitOptions, ConflictError, type CreateBillingPortalSessionParams, type CreateCheckoutSessionParams, type CreateCouponParams, type CreateCustomerParams, type CreateOneShotPaymentParams, type CreatePriceParams, type CreateProductParams, type CreateRefundParams, type CreateTaxRateParams, type CreateUsageRecordParams, type CreateWebhookEndpointParams, type CreditNotesListParams, type CustomerListParams, DEFAULT_RETRY_POLICY, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, type EventsListParams, type IdempotencyOptions, InvalidRequestError, type ListParams, type ListResponseEnvelope, type LogContext, NOOP_LOGGER, type PaginateOptions, PermissionError, type PriceTier, type PricesListParams, RateLimitError, ResourceMissingError, type RetryPolicy, type RotateProviderCredentialParams, ServerError, type SetPortalBrandingParams, type SubscriptionsListParams, type UpdateCouponParams, type UpdateCustomerParams, type UpdateProductParams, type UpdateTaxRateParams, type UpdateWebhookEndpointParams, type UsageRecordsListParams, VERSION, type ValidateCouponParams, type VerifyWebhookOptions, type VoidInvoiceParams, WebhookVerificationError, paginate, verifyWebhookSignature };

package/dist/index.d.ts

@@ -705,6 +705,21 @@ interface AuditLogsListParams extends BaseListParams {
     resource_type?: string;
     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.
+ */
+interface CreditNotesListParams extends BaseListParams {
+    invoice_id?: string;
+    customer_id?: string;
+}
+/** `invoices.void` params. `reason` is recorded on the audit row only. */
+interface VoidInvoiceParams extends IdempotencyOptions {
+    reason?: string;
+}
 interface CreateBillingPortalSessionParams extends IdempotencyOptions {
     subscription_id: string;
     return_url: string;
@@ -1010,6 +1025,18 @@ declare class WebhookEndpoints extends BaseResource {
         pageSize?: number;
     }): AsyncIterableIterator<T>;
     /** Fetch one delivery row for inspection before deciding to redeliver. */
+    retrieveDelivery<T = unknown>(endpointId: string, deliveryId: string): Promise<T>;
+    /**
+     * @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>;
     /**
      * Re-enqueue a delivery row for the dispatcher.
@@ -1131,6 +1158,47 @@ declare class Invoices extends BaseResource {
     iter<T = unknown>(options?: {
         pageSize?: number;
     }): AsyncIterableIterator<T>;
+    /**
+     * 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>;
+}
+/**
+ * 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.
+ */
+declare class CreditNotes extends BaseResource {
+    retrieve<T = unknown>(id: string): Promise<T>;
+    /**
+     * 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>;
+    list<T = unknown>(params?: CreditNotesListParams): Promise<ListResponseEnvelope<T>>;
+    iter<T = unknown>(options?: {
+        pageSize?: number;
+        invoice_id?: string;
+        customer_id?: string;
+    }): AsyncIterableIterator<T>;
 }
 /**
  * Read-only access to the per-tenant audit log.
@@ -1205,6 +1273,7 @@ declare class BillKit {
     readonly coupons: Coupons;
     readonly taxRates: TaxRates;
     readonly invoices: Invoices;
+    readonly creditNotes: CreditNotes;
     readonly auditLogs: AuditLogs;
     readonly payments: Payments;
     readonly billingPortalSessions: BillingPortalSessions;
@@ -1261,7 +1330,7 @@ declare class RateLimitError extends BillKitError {
     });
 }
 
-declare const VERSION = "0.3.0";
+declare const VERSION = "0.5.0";
 
 /**
  * Verify `BillKit-Signature: t=<unix>,v1=<hex>` headers.
@@ -1293,4 +1362,4 @@ interface VerifyWebhookOptions {
 }
 declare function verifyWebhookSignature<T = unknown>(options: VerifyWebhookOptions): Promise<T>;
 
-export { APIConnectionError, APIError, type AuditLogsListParams, AuthenticationError, type BaseListParams, BillKit, BillKitError, type BillKitLogger, type BillKitOptions, ConflictError, type CreateBillingPortalSessionParams, type CreateCheckoutSessionParams, type CreateCouponParams, type CreateCustomerParams, type CreateOneShotPaymentParams, type CreatePriceParams, type CreateProductParams, type CreateRefundParams, type CreateTaxRateParams, type CreateUsageRecordParams, type CreateWebhookEndpointParams, DEFAULT_RETRY_POLICY, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, type EventsListParams, type IdempotencyOptions, InvalidRequestError, type ListParams, type ListResponseEnvelope, type LogContext, NOOP_LOGGER, type PaginateOptions, PermissionError, type PriceTier, type PricesListParams, RateLimitError, ResourceMissingError, type RetryPolicy, type RotateProviderCredentialParams, ServerError, type SetPortalBrandingParams, type SubscriptionsListParams, type UpdateCouponParams, type UpdateCustomerParams, type UpdateProductParams, type UpdateTaxRateParams, type UpdateWebhookEndpointParams, type UsageRecordsListParams, VERSION, type ValidateCouponParams, type VerifyWebhookOptions, WebhookVerificationError, paginate, verifyWebhookSignature };
+export { APIConnectionError, APIError, type AuditLogsListParams, AuthenticationError, type BaseListParams, BillKit, BillKitError, type BillKitLogger, type BillKitOptions, ConflictError, type CreateBillingPortalSessionParams, type CreateCheckoutSessionParams, type CreateCouponParams, type CreateCustomerParams, type CreateOneShotPaymentParams, type CreatePriceParams, type CreateProductParams, type CreateRefundParams, type CreateTaxRateParams, type CreateUsageRecordParams, type CreateWebhookEndpointParams, type CreditNotesListParams, type CustomerListParams, DEFAULT_RETRY_POLICY, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, type EventsListParams, type IdempotencyOptions, InvalidRequestError, type ListParams, type ListResponseEnvelope, type LogContext, NOOP_LOGGER, type PaginateOptions, PermissionError, type PriceTier, type PricesListParams, RateLimitError, ResourceMissingError, type RetryPolicy, type RotateProviderCredentialParams, ServerError, type SetPortalBrandingParams, type SubscriptionsListParams, type UpdateCouponParams, type UpdateCustomerParams, type UpdateProductParams, type UpdateTaxRateParams, type UpdateWebhookEndpointParams, type UsageRecordsListParams, VERSION, type ValidateCouponParams, type VerifyWebhookOptions, type VoidInvoiceParams, WebhookVerificationError, paginate, verifyWebhookSignature };

package/dist/index.js

@@ -460,9 +460,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.
    *
@@ -618,6 +632,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) {
@@ -795,7 +849,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";
@@ -1029,6 +1083,7 @@ var BillKit = class {
   coupons;
   taxRates;
   invoices;
+  creditNotes;
   auditLogs;
   payments;
   billingPortalSessions;
@@ -1051,6 +1106,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);