@billkit-eu/sdk 0.2.1 → 0.4.0

package/dist/index.d.cts

@@ -279,6 +279,14 @@ interface UpdateCustomerParams extends IdempotencyOptions {
     country_code?: string;
     metadata?: Record<string, string>;
 }
+/** Query parameters accepted by `GET /v1/customers`. */
+interface CustomerListParams extends BaseListParams {
+    /**
+     * `false` for customers who have paid, `true` for abandoned checkouts,
+     * omitted for both.
+     */
+    provisional?: boolean;
+}
 /**
  * Body for `POST /v1/customers/{id}/vat_number`. The VAT number is
  * sent through VIES server-side; the response carries
@@ -306,6 +314,16 @@ interface CreateProductParams extends IdempotencyOptions {
     marketing_features?: string[];
     /** Small string metadata map echoed back on the Product object. */
     metadata?: Record<string, string>;
+    /**
+     * Let a *buyer* type a coupon code at the embedded checkout for this
+     * product. Defaults to `false`. A coupon you apply yourself by passing
+     * `coupon_code` when you create a Checkout Session is unaffected — that
+     * is you discounting your own sale, and it has never needed this flag.
+     *
+     * The code is redeemed only once the payment settles, so a shopper who
+     * tries a single-use code and abandons the checkout does not use it up.
+     */
+    allow_promotion_codes?: boolean;
 }
 interface UpdateProductParams extends IdempotencyOptions {
     name?: string;
@@ -314,6 +332,8 @@ interface UpdateProductParams extends IdempotencyOptions {
     metadata?: Record<string, string>;
     /** Set false to stop selling a product without deleting history. */
     active?: boolean;
+    /** See {@link CreateProductParams.allow_promotion_codes}. */
+    allow_promotion_codes?: boolean;
 }
 /**
  * Body for `POST /v1/prices/{id}`. `active` is the only field a price
@@ -324,16 +344,93 @@ interface UpdateProductParams extends IdempotencyOptions {
 interface UpdatePriceParams extends IdempotencyOptions {
     active: boolean;
 }
+/**
+ * One band of a tiered price.
+ *
+ * `up_to` is inclusive, and the **last band must be `"inf"`** because a
+ * bounded top band cannot price the usage above it. Bands must strictly
+ * increase.
+ *
+ * A band names a unit rate (`unit_amount` in whole minor units, or
+ * `unit_amount_decimal` for a finer one), a `flat_amount` charged once for
+ * reaching the band, or both. Write a free band as `unit_amount: 0` rather
+ * than by omitting the rate, so "free" is something the price says instead
+ * of something it forgot.
+ */
+interface PriceTier {
+    up_to: number | "inf";
+    /** Whole minor units per unit in this band. */
+    unit_amount?: number;
+    /**
+     * A rate finer than one minor unit, **as a string** — see
+     * {@link CreatePriceParams.unit_amount_decimal} for why it is never a
+     * `number`.
+     */
+    unit_amount_decimal?: string;
+    /** Charged once when the usage reaches this band. Whole minor units. */
+    flat_amount?: number;
+}
 interface CreatePriceParams extends IdempotencyOptions {
     /** Existing Product id returned from `client.products.create`. */
     product_id: string;
-    amount_cents: number;
+    /**
+     * Whole minor units per period (licensed) or per unit (metered).
+     *
+     * Optional because a metered price can be priced by
+     * {@link CreatePriceParams.unit_amount_decimal} or by
+     * {@link CreatePriceParams.tiers} instead. Exactly one of the three; a
+     * price with none of them is refused server-side.
+     */
+    amount_cents?: number;
+    /**
+     * A per-unit rate smaller than one minor unit, in **minor units**, to 12
+     * decimal places. `"0.02"` is 0.02 cents, i.e. EUR 0.0002 per unit, which
+     * is the canonical per-API-call price and not expressible as an integer.
+     * Metered prices only.
+     *
+     * **It is a `string`, and that is load-bearing.** A JS `number` is an
+     * IEEE-754 double and cannot hold 0.0002 exactly, so the rate would be
+     * corrupted before it was ever multiplied by a quantity. The type forbids
+     * a number at compile time, and the SDK throws a `TypeError` if an
+     * untyped JavaScript caller passes one anyway.
+     *
+     * The period's whole quantity is multiplied by the rate and rounded
+     * **once**, at the invoice.
+     */
+    unit_amount_decimal?: string;
+    /**
+     * `"per_unit"` (the default) multiplies one rate by the quantity.
+     * `"tiered"` prices by bands and requires
+     * {@link CreatePriceParams.tiers} and
+     * {@link CreatePriceParams.tiers_mode}. Metered prices only.
+     */
+    billing_scheme?: "per_unit" | "tiered";
+    /**
+     * How a tier table is read, and there is **no default** because the same
+     * table means two different bills. `"graduated"` prices the units inside
+     * each band; `"volume"` lets the period total pick one band which then
+     * prices every unit. 1,500 units against "first 1,000 at EUR 0.01, then
+     * EUR 0.005" is EUR 12.50 graduated and EUR 7.50 by volume.
+     */
+    tiers_mode?: "graduated" | "volume";
+    /** The band table. Required when `billing_scheme` is `"tiered"`, refused otherwise. */
+    tiers?: PriceTier[];
     currency: string;
     interval: "month" | "year" | (string & {});
     metadata?: Record<string, string>;
     trial_days?: number;
     trial_verification_cents?: number;
-    payment_methods?: Array<"creditcard" | "directdebit" | (string & {})>;
+    payment_methods?: Array<"creditcard" | "directdebit" | "ideal" | "applepay" | (string & {})>;
+    /**
+     * What a cancellation refunds without being asked. `"none"` (the default)
+     * nothing; `"full"` the whole last charge; `"prorated"` the unused part
+     * of the current period. Both non-none modes also end access
+     * immediately, and both stay bounded by the refund window below.
+     *
+     * Metered prices must leave this at `"none"`: ending access mid-period
+     * would strand usage that has not been billed yet.
+     */
+    refund_on_cancel?: "none" | "full" | "prorated";
     /**
      * Per-Price refund-window override (`POST /v1/prices`). `undefined`
      * inherits the default policy table (7d / 30d initial, 3d renewal);
@@ -354,12 +451,15 @@ interface CreatePriceParams extends IdempotencyOptions {
     tax_behavior?: "inclusive" | "exclusive" | "unspecified";
     /**
      * `"licensed"` (the default when omitted) bills `amount_cents` per
-     * period regardless of consumption. `"metered"` bills
-     * `amount_cents` **per reported unit**: post consumption with
-     * `subscriptions.createUsageRecord` and the renewal invoice charges
-     * `amount_cents × sum(quantity)` for the period. Metered prices
-     * must be `interval: "month"`, carry `amount_cents > 0`, and cannot
-     * have `trial_days`.
+     * period regardless of consumption. `"metered"` bills **per reported
+     * unit**: post consumption with `subscriptions.createUsageRecord`, and
+     * at each period close BillKit invoices the period's total and charges
+     * the stored mandate.
+     *
+     * A metered unit is priced by `amount_cents`, by `unit_amount_decimal`,
+     * or by `tiers` — exactly one. Metered prices must be
+     * `interval: "month"`, cannot have `trial_days`, and cannot set
+     * `refund_on_cancel`.
      */
     usage_type?: "licensed" | "metered";
 }
@@ -377,6 +477,22 @@ interface CreateUsageRecordParams extends IdempotencyOptions {
      * the record must land in the period the usage occurred.
      */
     occurred_at?: number;
+    /**
+     * Your own id for the event being metered, unique within this
+     * subscription. This is the dedupe an `Idempotency-Key` cannot do.
+     *
+     * The key covers a retry of *one HTTP request*, including the SDK's own
+     * internal retries. `identifier` covers a retry of *your* call — a job
+     * runner replaying a task, a queue delivering twice, your code
+     * re-invoking after its own timeout — which arrives at the API as a
+     * genuinely new request with a new key. A second report of the same
+     * identifier returns the first record unchanged instead of billing
+     * twice.
+     *
+     * If your reporting pipeline is at-least-once, this is the one that
+     * matters.
+     */
+    identifier?: string;
     /** Small string metadata map echoed back on the record. */
     metadata?: Record<string, string>;
 }
@@ -416,7 +532,7 @@ interface CreateCheckoutSessionParams extends IdempotencyOptions {
      * the customer's available methods; when set, must be in the price's
      * `payment_methods` allowlist.
      */
-    method?: "creditcard" | "directdebit" | (string & {});
+    method?: "creditcard" | "directdebit" | "ideal" | "applepay" | (string & {});
     /** Optional coupon code applied at checkout; atomically claimed. */
     coupon_code?: string;
     /**
@@ -481,7 +597,7 @@ interface CreateOneShotPaymentParams extends IdempotencyOptions {
      * *request* type the server validates, so an SDK that lags a newly-added
      * method should not be the thing that blocks the call.
      */
-    method: "creditcard" | "directdebit" | "ideal" | "bancontact" | "eps" | (string & {});
+    method: "creditcard" | "directdebit" | "ideal" | "bancontact" | "eps" | "applepay" | (string & {});
     /** Where Mollie returns the payer after the hosted checkout. */
     success_url: string;
     /** Optional page for an abandoned/cancelled payment. */
@@ -589,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;
@@ -628,7 +759,17 @@ declare class Customers extends BaseResource {
      * charge them.
      */
     delete<T = unknown>(id: string, params?: IdempotencyOptions): Promise<T>;
-    list<T = unknown>(params?: BaseListParams): Promise<ListResponseEnvelope<T>>;
+    /**
+     * 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<T = unknown>(params?: CustomerListParams): Promise<ListResponseEnvelope<T>>;
     /** Walk every page of `list()` and yield each customer. */
     iter<T = unknown>(options?: {
         pageSize?: number;
@@ -669,7 +810,16 @@ declare class Products extends BaseResource {
     }): AsyncIterableIterator<T>;
 }
 declare class Prices extends BaseResource {
-    /** Create immutable billing terms for an existing Product. */
+    /**
+     * 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}.
+     */
     create<T = unknown>(params: CreatePriceParams): Promise<T>;
     retrieve<T = unknown>(id: string): Promise<T>;
     /**
@@ -763,13 +913,16 @@ declare class Subscriptions 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<T = unknown>(id: string, params: CreateUsageRecordParams): Promise<T>;
     /**
@@ -785,6 +938,25 @@ declare class Subscriptions extends BaseResource {
         pageSize?: number;
         invoice_id?: string;
     }): AsyncIterableIterator<T>;
+    /**
+     * 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<T = unknown>(id: string): Promise<T>;
 }
 declare class Refunds extends BaseResource {
     create<T = unknown>(params: CreateRefundParams): Promise<T>;
@@ -974,6 +1146,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.
@@ -1048,6 +1261,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;
@@ -1104,7 +1318,7 @@ declare class RateLimitError extends BillKitError {
     });
 }
 
-declare const VERSION = "0.2.1";
+declare const VERSION = "0.4.0";
 
 /**
  * Verify `BillKit-Signature: t=<unix>,v1=<hex>` headers.
@@ -1136,4 +1350,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 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, 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 };