@billkit-eu/sdk 0.7.1 → 0.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@billkit-eu/sdk",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "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>;
 }
@@ -221,8 +237,11 @@ export interface CreateProductParams extends IdempotencyOptions {
 
 export interface UpdateProductParams extends IdempotencyOptions {
   name?: string;
-  description?: string;
-  marketing_features?: 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;
+  /** `null` empties the list. 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. */
+  marketing_features?: string[] | null;
+  /** Replaces the stored object whole; send `{}` to empty it. */
   metadata?: Record<string, string>;
   /** Set false to stop selling a product without deleting history. */
   active?: boolean;
@@ -254,6 +273,9 @@ export interface UpdateProductParams extends IdempotencyOptions {
  * the price is still `"unspecified"` and never changed again, because
  * flipping it would restate whether tax was inside or on top of an amount
  * somebody has already paid.
+ *
+ * Only the two refund windows accept `null`, which clears the price's
+ * override. The API refuses a `null` on any other field here with a 400.
  */
 export interface UpdatePriceParams extends IdempotencyOptions {
   /** `false` withdraws the price from sale, `true` puts it back. */
@@ -266,9 +288,13 @@ export interface UpdatePriceParams extends IdempotencyOptions {
     "creditcard" | "directdebit" | "ideal" | "eps" | "applepay" | "paypal" | (string & {})
   >;
   refund_on_cancel?: "none" | "full" | "prorated";
-  /** `0` disables refunds for that charge type; `N > 0` is an N-day window. */
-  refund_window_initial_days?: number;
-  refund_window_renewal_days?: number;
+  /**
+   * `0` disables refunds for that charge type; `N > 0` is an N-day window.
+   * `null` drops the price's override. 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.
+   */
+  refund_window_initial_days?: number | null;
+  /** As {@link UpdatePriceParams.refund_window_initial_days}, for renewals. */
+  refund_window_renewal_days?: number | null;
 }
 
 /**
@@ -604,7 +630,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;
 }
 
@@ -651,10 +678,14 @@ export interface CreateCouponParams extends IdempotencyOptions {
 
 export interface UpdateCouponParams extends IdempotencyOptions {
   active?: boolean;
-  max_redemptions?: number;
-  redeem_by?: number;
-  applies_to_price_ids?: string[];
-  min_amount_cents?: 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;
+  /** `null` lifts the price restriction. 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. */
+  applies_to_price_ids?: string[] | null;
+  /** `null` lifts the minimum. 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. */
+  min_amount_cents?: number | null;
 }
 
 export interface ValidateCouponParams {
@@ -682,7 +713,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;
 }
@@ -1096,6 +1128,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 {
@@ -1780,7 +1826,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.1";
+export const VERSION = "0.8.1";