@billkit-eu/sdk 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@billkit-eu/sdk",
-  "version": "0.7.0",
+  "version": "0.8.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/index.ts

@@ -90,6 +90,7 @@ export type {
   IdempotencyOptions,
   InvoicesListParams,
   ListParams,
+  OneShotPaymentsListParams,
   PaymentsListParams,
   PriceTier,
   PricesListParams,

package/src/resources.ts

@@ -71,6 +71,21 @@ export interface PaymentsListParams extends BaseListParams {
   expand?: string[];
 }
 
+/**
+ * `oneShotPayments.list` params. `payments.list` lists subscription
+ * payments only; one-off charges are listed here, newest first.
+ * Failed, expired and still-open charges are included, so check `status`
+ * before counting a row as revenue.
+ */
+export interface OneShotPaymentsListParams extends BaseListParams {
+  customer_id?: string;
+  /**
+   * One of `open`, `pending`, `authorized`, `paid`, `failed`, `expired`,
+   * `canceled`, `refunded`. Anything else is a `400` on `status`.
+   */
+  status?: string;
+}
+
 /**
  * `invoices.list` params. The three id filters each narrow to one row's
  * worth of invoices: `payment_id` answers "which invoice did this charge
@@ -152,7 +167,8 @@ export interface CreateCustomerParams extends IdempotencyOptions {
 
 export interface UpdateCustomerParams extends IdempotencyOptions {
   email?: string;
-  name?: string;
+  /** An explicit `null` **clears** it and is sent as a JSON null rather than pruned (only `undefined` is dropped); omit the field to leave it alone. */
+  name?: string | null;
   country_code?: string;
   metadata?: Record<string, string>;
 }
@@ -170,7 +186,7 @@ export interface CustomerListParams extends BaseListParams {
 
 /** Query parameters accepted by `GET /v1/products`. */
 export interface ProductsListParams extends BaseListParams {
-  /** Expandable here: `prices`, `stats`. */
+  /** Expandable here: `prices`, `stats`, `default_price`. */
   expand?: string[];
 }
 
@@ -221,13 +237,22 @@ export interface CreateProductParams extends IdempotencyOptions {
 
 export interface UpdateProductParams extends IdempotencyOptions {
   name?: string;
-  description?: string;
+  /** An explicit `null` **clears** it and is sent as a JSON null rather than pruned (only `undefined` is dropped); omit the field to leave it alone. */
+  description?: string | null;
   marketing_features?: string[];
   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;
+  /**
+   * The price the billing portal offers on that price's interval. Must be
+   * an active price of this product; anything else is a 400 on
+   * `default_price_id`. An explicit `null` **clears** the default and is
+   * sent as a JSON null rather than pruned (only `undefined` is dropped);
+   * omit the field to leave the default alone.
+   */
+  default_price_id?: string | null;
 }
 
 /**
@@ -596,7 +621,8 @@ export interface CreateWebhookEndpointParams extends IdempotencyOptions {
 export interface UpdateWebhookEndpointParams extends IdempotencyOptions {
   url?: string;
   enabled_events?: string[];
-  description?: string;
+  /** An explicit `null` **clears** it and is sent as a JSON null rather than pruned (only `undefined` is dropped); omit the field to leave it alone. */
+  description?: string | null;
   status?: string;
 }
 
@@ -643,8 +669,10 @@ export interface CreateCouponParams extends IdempotencyOptions {
 
 export interface UpdateCouponParams extends IdempotencyOptions {
   active?: boolean;
-  max_redemptions?: number;
-  redeem_by?: number;
+  /** `null` removes the redemption cap. An explicit `null` **clears** it and is sent as a JSON null rather than pruned (only `undefined` is dropped); omit the field to leave it alone. */
+  max_redemptions?: number | null;
+  /** Epoch seconds. `null` removes the expiry. An explicit `null` **clears** it and is sent as a JSON null rather than pruned (only `undefined` is dropped); omit the field to leave it alone. */
+  redeem_by?: number | null;
   applies_to_price_ids?: string[];
   min_amount_cents?: number;
 }
@@ -674,7 +702,8 @@ export interface CreateTaxRateParams extends IdempotencyOptions {
 
 export interface UpdateTaxRateParams extends IdempotencyOptions {
   rate_basis_points?: number;
-  display_name?: string;
+  /** An explicit `null` **clears** it and is sent as a JSON null rather than pruned (only `undefined` is dropped); omit the field to leave it alone. */
+  display_name?: string | null;
   inclusive?: boolean;
   active?: boolean;
 }
@@ -711,15 +740,20 @@ export interface CreditNotesListParams extends BaseListParams {
  * VAT is decided against and that an invoice prints.
  *
  * `country_code` is required on every call: there is nothing to leave
- * alone about a jurisdiction. Every other field is partial-update: omit
- * it to leave the stored value alone, or pass an explicit `null` to
- * clear it, because ceasing to be VAT registered (or moving office) is a
- * real event.
+ * alone about a jurisdiction. The address fields and
+ * `registration_number` are partial-update: omit one to leave the stored
+ * value alone, or pass an explicit `null` to clear it, because moving
+ * office is a real event.
+ *
+ * `vat_id` can be set once. After that, a different value or `null` is
+ * refused with a 400 (`param: "vat_id"`, reason `vat_id_locked`) and the
+ * call writes nothing; re-sending the stored number is accepted. BillKit
+ * invoices you reverse-charged against it, so support changes it.
  */
 export interface SetTenantBillingProfileParams extends IdempotencyOptions {
   /** ISO-3166-1 alpha-2, e.g. `"NL"`. */
   country_code: string;
-  /** Your own EU VAT registration, or `null` to clear it. */
+  /** Your own EU VAT registration. Set once; support changes or clears it. */
   vat_id?: string | null;
   address_line1?: string | null;
   address_line2?: string | null;
@@ -963,7 +997,10 @@ export class Products extends BaseResource {
     return this.post<T, CreateProductParams>("/v1/products", params);
   }
 
-  /** Expandable: `prices` (every price on the product), `stats`. */
+  /**
+   * Expandable: `prices` (every price on the product), `stats`, and
+   * `default_price` (the price `default_price_id` names).
+   */
   retrieve<T = unknown>(id: string, options: ExpandOptions = {}): Promise<T> {
     return this.get<T>(`/v1/products/${p(id)}`, options);
   }
@@ -1080,6 +1117,20 @@ export class OneShotPayments extends BaseResource {
   retrieve<T = unknown>(id: string): Promise<T> {
     return this.get<T>(`/v1/checkout/one_shot/${p(id)}`);
   }
+
+  /** List one-off charges, newest first. Filter by `customer_id` and `status`. */
+  list<T = unknown>(params: OneShotPaymentsListParams = {}): Promise<ListResponseEnvelope<T>> {
+    return this.get<ListResponseEnvelope<T>>("/v1/checkout/one_shot", params);
+  }
+
+  iter<T = unknown>(
+    options: { pageSize?: number; customer_id?: string; status?: string } = {},
+  ): AsyncIterableIterator<T> {
+    return paginate<T>((page) => this.get("/v1/checkout/one_shot", page), {
+      pageSize: options.pageSize,
+      filters: { customer_id: options.customer_id, status: options.status },
+    });
+  }
 }
 
 export class Subscriptions extends BaseResource {
@@ -1764,7 +1815,20 @@ export class AuditLogs extends BaseResource {
  * refunds and disputes are separate flows.
  */
 export class Payments extends BaseResource {
-  /** Expandable: `customer`, `subscription`. */
+  /**
+   * Expandable: `customer`, `subscription`, `refund_eligibility`. The last
+   * is retrieve-only (`list` refuses it with a `400`) and attaches
+   * `refund_eligibility: { object: "refund_eligibility", eligible,
+   * amount_cents, currency, days_remaining, window_ends_at, reason }`:
+   * whether `refunds.create` for the remaining balance would succeed now,
+   * applying the refund window and the price's refund policy, which
+   * `amount_refundable_cents` does not. When `eligible` is false, `reason`
+   * is one of `not_paid`, `unrefundable_type`, `window_expired`,
+   * `fully_refunded`, `disputed`, `operation_pending` or
+   * `plan_change_pending` (a plan change is settling: the full balance
+   * cannot be refunded yet, a partial refund still can); treat any other
+   * value as "not refundable".
+   */
   retrieve<T = unknown>(id: string, options: ExpandOptions = {}): Promise<T> {
     return this.get<T>(`/v1/payments/${p(id)}`, options);
   }

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.7.0";
+export const VERSION = "0.8.0";