@usebillow/sdk 0.8.0 → 0.9.0

package/dist/{hosted-domains-BP91tg9P.d.ts → hosted-domains-DSTQ1GZz.d.ts}

@@ -1,4 +1,4 @@
-import { H as HostedDomainResponse } from './index.d-CKQAhQfJ.js';
+import { H as HostedDomainResponse } from './index.d-DSEYhV2c.js';
 
 /**
  * Public SDK types for prepaid credits. Re-exported by ../types.ts.
@@ -67,9 +67,33 @@ interface CreateCreditGrantInput {
 }
 /** A Credit Account's status: `frozen` takes no new reservations; `closed` (erased) takes nothing. */
 type CreditAccountStatus = "active" | "frozen" | "closed";
+/** What current Included Credit Windows include, and where it stands. */
+interface IncludedCredits {
+    /** What the windows include. */
+    granted: string;
+    /** Consumed from their credits, net of reversals. */
+    used: string;
+    held: string;
+    /** Unheld and spendable, credits recorded but not issued yet included. */
+    remaining: string;
+}
+/** One subscription's current Included Credit Window, in a customer's balance. */
+interface IncludedPeriod extends IncludedCredits {
+    subscriptionId: string;
+    /** The window (ISO 8601), half-open: its credits expire at `end`. */
+    start: string;
+    end: string;
+    /** The billing period it belongs to (a trial's is the trial). */
+    periodStart: string;
+    periodEnd: string;
+    /** The next window's start within the paid period (a monthly refill), or null. */
+    nextRefillAt: string | null;
+}
 /**
  * A customer's credit balance, true at `asOf`. A balance never grants spending authority - only a
- * reservation does. A customer with no credit account yet reads as zeros, `active`, `exhausted`.
+ * reservation does. A customer with no credit account yet reads as their subscriptions' recorded
+ * included credits alone (zeros without any), `active`, `exhausted` when nothing is spendable.
+ * Included credits count from the instant their window is current, before Billow issues them.
  */
 interface CreditBalance {
     /** The customer's external id. */
@@ -79,7 +103,10 @@ interface CreditBalance {
     spendable: string;
     /** Credits held by open reservations. */
     held: string;
-    /** Credits consumed since `periodStart`, net of reversals. */
+    /**
+     * Credits consumed since `periodStart`, net of their reversals: a reversal counts against the
+     * period of the consumption it reverses, so this is never negative.
+     */
     consumedThisPeriod: string;
     /** The current included period's start, else the first instant of the current UTC month. */
     periodStart: string;
@@ -99,22 +126,23 @@ interface CreditBalance {
         /** Spendable on a category not listed: the grants that pay for every category. */
         otherCategories: string;
     };
-    /** The active included grants (a subscription's period allowance); null when there are none. */
-    currentPeriod: {
-        granted: string;
-        /** Consumed from them, net of reversals. */
-        used: string;
-        held: string;
-        /** Unheld and spendable. */
-        remaining: string;
+    /**
+     * The current Included Credit Windows together - the billing period, or the current month under
+     * a monthly allocation - across the customer's subscriptions; null when none is current (between
+     * a period's end and the payment that grants the next).
+     */
+    currentPeriod: (IncludedCredits & {
+        /** The earliest current window's start. */
         start: string;
-        /** When they expire (the period end); null if one never does. */
-        end: string | null;
-    } | null;
+        /** The earliest current window's end: when the first of these credits stop. */
+        end: string;
+    }) | null;
+    /** Each subscription's current window, soonest end first (empty when none is current). */
+    includedPeriods: IncludedPeriod[];
     thresholds: {
         lowPercent: number;
         criticalPercent: number;
-        /** What the percentages apply to: the current period's credits, else the last top-up's. */
+        /** What the percentages apply to: the current windows' credits, else the last top-up's. */
         reference: string | null;
         level: CreditThresholdLevel;
     };
@@ -144,6 +172,8 @@ interface CreditLedgerEntry {
     callerReason: string | null;
     /** The metadata of the resource it belongs to: its reservation, reversal or top-up, else its grant. */
     metadata: Record<string, string> | null;
+    /** On an included grant's transaction: the subscription whose window issued the grant. */
+    subscriptionId: string | null;
     createdAt: string;
 }
 /** What `credits.usage.get` totals each row by. */
@@ -326,6 +356,69 @@ interface CreateCreditIncludedRuleInput {
 type UpdateCreditIncludedRuleInput = Partial<Omit<CreateCreditIncludedRuleInput, "priceId">> & {
     archived?: boolean;
 };
+/**
+ * Where an Included Credit Window stands: `scheduled` (a later window, not started), `pending`
+ * (current, waiting to be issued - Billow issues it within seconds), `blocked` (current, but its
+ * last issue attempt could not go through - see `blockedCause` - and Billow retries it with
+ * backoff), `issued`, `suspended` (held by a pause), `lapsed` (over without being issued: a period
+ * paid after it ended, or one that passed while paused), `ended` (ended early, with `endCause`),
+ * or `account_closed` (the customer was erased, so it never issues).
+ */
+type CreditWindowState = "scheduled" | "pending" | "blocked" | "issued" | "suspended" | "lapsed" | "ended" | "account_closed";
+/**
+ * An Included Credit Window: what one window of a period Billow granted a subscription includes -
+ * the whole billing period, one month of it under a monthly rule, or a trial - and how far its
+ * credits have been issued.
+ */
+interface CreditIncludedWindow {
+    id: string;
+    subscriptionId: string;
+    /** The customer's external id. */
+    customerId: string;
+    /** The window (ISO 8601), half-open: its credits expire at `end`. */
+    start: string;
+    end: string;
+    /** The billing period it belongs to (a trial's is the trial). */
+    periodStart: string;
+    periodEnd: string;
+    /** The next window's start within the period (a monthly refill), or null for its last window. */
+    nextRefillAt: string | null;
+    /** How the rule allocated the period when it was granted. */
+    allocation: CreditAllocationInterval;
+    /** The categories its credits may pay for; null = every category. */
+    eligibility: string[] | null;
+    /** Microcredits the window includes. */
+    entitled: string;
+    /** Microcredits issued to the customer for it so far. */
+    issued: string;
+    state: CreditWindowState;
+    /**
+     * For a `blocked` window: `capacity` (its credits would take the customer's balance past the
+     * largest total Billow holds) or `error` (an unexpected fault); null otherwise.
+     */
+    blockedCause: "capacity" | "error" | null;
+    /** For a `pending` or `blocked` window: since when it has been due. */
+    dueSince: string | null;
+    endedAt: string | null;
+    endCause: "canceled" | "charged_back" | null;
+    createdAt: string;
+}
+/**
+ * Whose Included Credit Windows to list: one or more subscriptions, or a customer (by external id)
+ * - exactly one of the two.
+ */
+type CreditIncludedWindowListParams = ({
+    subscription: string | string[];
+    customer?: never;
+} | {
+    customer: string;
+    subscription?: never;
+}) & {
+    /** Only each subscription's latest window that has started (what the subscription shows now). */
+    current?: boolean;
+    limit?: number;
+    cursor?: string;
+};
 /**
  * A top-up's state: `pending` until its payment settles; `succeeded` (credits granted) or
  * `failed` (a later payment on the same checkout still succeeds it); `unfulfilled` - paid after
@@ -427,4 +520,4 @@ interface HostedDomainDisabledData extends HostedDomainEventBase {
     reason: Extract<HostedDomainStatusReason, "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended">;
 }
 
-export type { CreditTopUpStatus as A, CreditTransactionType as B, CreditGrantKind as C, CreditUsageGroupBy as D, HostedDomainEventBase as E, HostedDomainStatus as F, HostedDomainStatusReason as G, HostedDomainActivatedData as H, UpdateCreditPackInput as U, CreditThresholdLevel as a, HostedDomainDnsFailingData as b, HostedDomainReassignmentPendingData as c, HostedDomainDisabledData as d, CreditGrant as e, CreditTopUp as f, CreateCreditGrantInput as g, CreditGrantRequestResult as h, CreditPacks as i, CreateCreditPackInput as j, CreditPack as k, CreateCreditIncludedRuleInput as l, CreditIncludedRule as m, UpdateCreditIncludedRuleInput as n, CreateCreditTopUpInput as o, CreditTopUpRequestResult as p, CreditTopUpListParams as q, CreditBalance as r, CreditLedgerEntry as s, CreditUsageParams as t, CreditUsage as u, CreditAccountStatus as v, CreditAllocationInterval as w, CreditMoney as x, CreditPackBreakdown as y, CreditPackListItem as z };
+export type { CreditPackBreakdown as A, CreditPackListItem as B, CreditGrantKind as C, CreditTopUpStatus as D, CreditTransactionType as E, CreditUsageGroupBy as F, CreditWindowState as G, HostedDomainActivatedData as H, HostedDomainEventBase as I, HostedDomainStatus as J, HostedDomainStatusReason as K, IncludedCredits as L, IncludedPeriod as M, UpdateCreditPackInput as U, CreditThresholdLevel as a, HostedDomainDnsFailingData as b, HostedDomainReassignmentPendingData as c, HostedDomainDisabledData as d, CreditGrant as e, CreditTopUp as f, CreditIncludedWindow as g, CreateCreditGrantInput as h, CreditGrantRequestResult as i, CreditPacks as j, CreateCreditPackInput as k, CreditPack as l, CreateCreditIncludedRuleInput as m, CreditIncludedRule as n, UpdateCreditIncludedRuleInput as o, CreditIncludedWindowListParams as p, CreateCreditTopUpInput as q, CreditTopUpRequestResult as r, CreditTopUpListParams as s, CreditBalance as t, CreditLedgerEntry as u, CreditUsageParams as v, CreditUsage as w, CreditAccountStatus as x, CreditAllocationInterval as y, CreditMoney as z };

package/dist/{hosted-domains-BbuyxnuH.d.cts → hosted-domains-DwakPG4J.d.cts}

@@ -1,4 +1,4 @@
-import { H as HostedDomainResponse } from './index.d-CKQAhQfJ.cjs';
+import { H as HostedDomainResponse } from './index.d-DSEYhV2c.cjs';
 
 /**
  * Public SDK types for prepaid credits. Re-exported by ../types.ts.
@@ -67,9 +67,33 @@ interface CreateCreditGrantInput {
 }
 /** A Credit Account's status: `frozen` takes no new reservations; `closed` (erased) takes nothing. */
 type CreditAccountStatus = "active" | "frozen" | "closed";
+/** What current Included Credit Windows include, and where it stands. */
+interface IncludedCredits {
+    /** What the windows include. */
+    granted: string;
+    /** Consumed from their credits, net of reversals. */
+    used: string;
+    held: string;
+    /** Unheld and spendable, credits recorded but not issued yet included. */
+    remaining: string;
+}
+/** One subscription's current Included Credit Window, in a customer's balance. */
+interface IncludedPeriod extends IncludedCredits {
+    subscriptionId: string;
+    /** The window (ISO 8601), half-open: its credits expire at `end`. */
+    start: string;
+    end: string;
+    /** The billing period it belongs to (a trial's is the trial). */
+    periodStart: string;
+    periodEnd: string;
+    /** The next window's start within the paid period (a monthly refill), or null. */
+    nextRefillAt: string | null;
+}
 /**
  * A customer's credit balance, true at `asOf`. A balance never grants spending authority - only a
- * reservation does. A customer with no credit account yet reads as zeros, `active`, `exhausted`.
+ * reservation does. A customer with no credit account yet reads as their subscriptions' recorded
+ * included credits alone (zeros without any), `active`, `exhausted` when nothing is spendable.
+ * Included credits count from the instant their window is current, before Billow issues them.
  */
 interface CreditBalance {
     /** The customer's external id. */
@@ -79,7 +103,10 @@ interface CreditBalance {
     spendable: string;
     /** Credits held by open reservations. */
     held: string;
-    /** Credits consumed since `periodStart`, net of reversals. */
+    /**
+     * Credits consumed since `periodStart`, net of their reversals: a reversal counts against the
+     * period of the consumption it reverses, so this is never negative.
+     */
     consumedThisPeriod: string;
     /** The current included period's start, else the first instant of the current UTC month. */
     periodStart: string;
@@ -99,22 +126,23 @@ interface CreditBalance {
         /** Spendable on a category not listed: the grants that pay for every category. */
         otherCategories: string;
     };
-    /** The active included grants (a subscription's period allowance); null when there are none. */
-    currentPeriod: {
-        granted: string;
-        /** Consumed from them, net of reversals. */
-        used: string;
-        held: string;
-        /** Unheld and spendable. */
-        remaining: string;
+    /**
+     * The current Included Credit Windows together - the billing period, or the current month under
+     * a monthly allocation - across the customer's subscriptions; null when none is current (between
+     * a period's end and the payment that grants the next).
+     */
+    currentPeriod: (IncludedCredits & {
+        /** The earliest current window's start. */
         start: string;
-        /** When they expire (the period end); null if one never does. */
-        end: string | null;
-    } | null;
+        /** The earliest current window's end: when the first of these credits stop. */
+        end: string;
+    }) | null;
+    /** Each subscription's current window, soonest end first (empty when none is current). */
+    includedPeriods: IncludedPeriod[];
     thresholds: {
         lowPercent: number;
         criticalPercent: number;
-        /** What the percentages apply to: the current period's credits, else the last top-up's. */
+        /** What the percentages apply to: the current windows' credits, else the last top-up's. */
         reference: string | null;
         level: CreditThresholdLevel;
     };
@@ -144,6 +172,8 @@ interface CreditLedgerEntry {
     callerReason: string | null;
     /** The metadata of the resource it belongs to: its reservation, reversal or top-up, else its grant. */
     metadata: Record<string, string> | null;
+    /** On an included grant's transaction: the subscription whose window issued the grant. */
+    subscriptionId: string | null;
     createdAt: string;
 }
 /** What `credits.usage.get` totals each row by. */
@@ -326,6 +356,69 @@ interface CreateCreditIncludedRuleInput {
 type UpdateCreditIncludedRuleInput = Partial<Omit<CreateCreditIncludedRuleInput, "priceId">> & {
     archived?: boolean;
 };
+/**
+ * Where an Included Credit Window stands: `scheduled` (a later window, not started), `pending`
+ * (current, waiting to be issued - Billow issues it within seconds), `blocked` (current, but its
+ * last issue attempt could not go through - see `blockedCause` - and Billow retries it with
+ * backoff), `issued`, `suspended` (held by a pause), `lapsed` (over without being issued: a period
+ * paid after it ended, or one that passed while paused), `ended` (ended early, with `endCause`),
+ * or `account_closed` (the customer was erased, so it never issues).
+ */
+type CreditWindowState = "scheduled" | "pending" | "blocked" | "issued" | "suspended" | "lapsed" | "ended" | "account_closed";
+/**
+ * An Included Credit Window: what one window of a period Billow granted a subscription includes -
+ * the whole billing period, one month of it under a monthly rule, or a trial - and how far its
+ * credits have been issued.
+ */
+interface CreditIncludedWindow {
+    id: string;
+    subscriptionId: string;
+    /** The customer's external id. */
+    customerId: string;
+    /** The window (ISO 8601), half-open: its credits expire at `end`. */
+    start: string;
+    end: string;
+    /** The billing period it belongs to (a trial's is the trial). */
+    periodStart: string;
+    periodEnd: string;
+    /** The next window's start within the period (a monthly refill), or null for its last window. */
+    nextRefillAt: string | null;
+    /** How the rule allocated the period when it was granted. */
+    allocation: CreditAllocationInterval;
+    /** The categories its credits may pay for; null = every category. */
+    eligibility: string[] | null;
+    /** Microcredits the window includes. */
+    entitled: string;
+    /** Microcredits issued to the customer for it so far. */
+    issued: string;
+    state: CreditWindowState;
+    /**
+     * For a `blocked` window: `capacity` (its credits would take the customer's balance past the
+     * largest total Billow holds) or `error` (an unexpected fault); null otherwise.
+     */
+    blockedCause: "capacity" | "error" | null;
+    /** For a `pending` or `blocked` window: since when it has been due. */
+    dueSince: string | null;
+    endedAt: string | null;
+    endCause: "canceled" | "charged_back" | null;
+    createdAt: string;
+}
+/**
+ * Whose Included Credit Windows to list: one or more subscriptions, or a customer (by external id)
+ * - exactly one of the two.
+ */
+type CreditIncludedWindowListParams = ({
+    subscription: string | string[];
+    customer?: never;
+} | {
+    customer: string;
+    subscription?: never;
+}) & {
+    /** Only each subscription's latest window that has started (what the subscription shows now). */
+    current?: boolean;
+    limit?: number;
+    cursor?: string;
+};
 /**
  * A top-up's state: `pending` until its payment settles; `succeeded` (credits granted) or
  * `failed` (a later payment on the same checkout still succeeds it); `unfulfilled` - paid after
@@ -427,4 +520,4 @@ interface HostedDomainDisabledData extends HostedDomainEventBase {
     reason: Extract<HostedDomainStatusReason, "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended">;
 }
 
-export type { CreditTopUpStatus as A, CreditTransactionType as B, CreditGrantKind as C, CreditUsageGroupBy as D, HostedDomainEventBase as E, HostedDomainStatus as F, HostedDomainStatusReason as G, HostedDomainActivatedData as H, UpdateCreditPackInput as U, CreditThresholdLevel as a, HostedDomainDnsFailingData as b, HostedDomainReassignmentPendingData as c, HostedDomainDisabledData as d, CreditGrant as e, CreditTopUp as f, CreateCreditGrantInput as g, CreditGrantRequestResult as h, CreditPacks as i, CreateCreditPackInput as j, CreditPack as k, CreateCreditIncludedRuleInput as l, CreditIncludedRule as m, UpdateCreditIncludedRuleInput as n, CreateCreditTopUpInput as o, CreditTopUpRequestResult as p, CreditTopUpListParams as q, CreditBalance as r, CreditLedgerEntry as s, CreditUsageParams as t, CreditUsage as u, CreditAccountStatus as v, CreditAllocationInterval as w, CreditMoney as x, CreditPackBreakdown as y, CreditPackListItem as z };
+export type { CreditPackBreakdown as A, CreditPackListItem as B, CreditGrantKind as C, CreditTopUpStatus as D, CreditTransactionType as E, CreditUsageGroupBy as F, CreditWindowState as G, HostedDomainActivatedData as H, HostedDomainEventBase as I, HostedDomainStatus as J, HostedDomainStatusReason as K, IncludedCredits as L, IncludedPeriod as M, UpdateCreditPackInput as U, CreditThresholdLevel as a, HostedDomainDnsFailingData as b, HostedDomainReassignmentPendingData as c, HostedDomainDisabledData as d, CreditGrant as e, CreditTopUp as f, CreditIncludedWindow as g, CreateCreditGrantInput as h, CreditGrantRequestResult as i, CreditPacks as j, CreateCreditPackInput as k, CreditPack as l, CreateCreditIncludedRuleInput as m, CreditIncludedRule as n, UpdateCreditIncludedRuleInput as o, CreditIncludedWindowListParams as p, CreateCreditTopUpInput as q, CreditTopUpRequestResult as r, CreditTopUpListParams as s, CreditBalance as t, CreditLedgerEntry as u, CreditUsageParams as v, CreditUsage as w, CreditAccountStatus as x, CreditAllocationInterval as y, CreditMoney as z };

package/dist/index.cjs

@@ -576,6 +576,31 @@ function createCreditsResource(ctx) {
         options
       )
     },
+    includedWindows: {
+      /**
+       * The Included Credit Windows of one or more subscriptions (`subscription`, an id or a list
+       * of up to 100), or of a customer (`customer`, by external id) - newest first: what each
+       * period Billow granted includes (the whole period, each month of it under a monthly rule,
+       * or a trial), how far it was issued, and its `state`. With `current: true`, only each
+       * subscription's latest window that has started - what it stands at now. Auto-paginating by
+       * cursor: `await` the first page, `for await (…)` every window, or `.listAll()` to collect
+       * them.
+       */
+      list: (params, options) => {
+        const { subscription, ...rest } = params;
+        const subscriptions = Array.isArray(subscription) ? subscription.join(",") : subscription;
+        return makeCursorListPromise(
+          (p) => apiRequest(
+            ctx,
+            "GET",
+            `/v1/credits/included-windows${toQuery({ ...p, subscription: subscriptions })}`,
+            void 0,
+            options
+          ),
+          rest
+        );
+      }
+    },
     topUps: {
       /**
        * Buy a Credit Pack for a customer: answers the top-up with `checkoutUrl`, the hosted
@@ -1323,7 +1348,18 @@ function createSubscriptionsResource(ctx) {
       "POST",
       `/v1/subscriptions/${encodeURIComponent(id)}/resume-cancellation`
     ),
+    /**
+     * Pause an active or trialing subscription: no renewals and no access until it is resumed.
+     * Refused while one of its invoices is still being collected.
+     */
     pause: (id) => apiRequest(ctx, "POST", `/v1/subscriptions/${encodeURIComponent(id)}/pause`),
+    /**
+     * Resume a paused subscription. Paused time is never billed: resumed before its paid period
+     * ends, it carries on and renews at `currentPeriodEnd`; resumed after, a fresh full period
+     * starts now and is charged at once like a renewal, with the ended period's usage (a decline
+     * returns it `past_due`). Usage recorded while paused is never billed. A paused trial resumes
+     * `trialing`. Duplicate calls are safe.
+     */
     resume: (id) => apiRequest(ctx, "POST", `/v1/subscriptions/${encodeURIComponent(id)}/resume`),
     /** Apply a coupon to an existing subscription. */
     applyCoupon: (id, code) => apiRequest(