@usebillow/sdk 0.6.0 → 0.8.0

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

@@ -218,13 +218,13 @@ interface CreateCreditPackInput {
 type UpdateCreditPackInput = Partial<CreateCreditPackInput> & {
     archived?: boolean;
 };
-/** A pack a customer can buy, with its derived price per credit and savings. */
+/** A pack a customer can buy, with its derived price per credit, savings and breakdown. */
 interface CreditPackListItem {
     id: string;
     name: string;
     credits: string;
     bonusCredits: string;
-    /** The catalog Price: what `pricePerCredit` and `savingsBps` are measured on. */
+    /** The catalog Price: what `pricePerCredit` is measured on. */
     price: CreditMoney;
     /**
      * The tax a top-up of the pack charges (the Price's treatment, else your project's default):
@@ -243,16 +243,89 @@ interface CreditPackListItem {
      */
     pricePerCredit: string;
     /**
-     * Basis points cheaper per credit than the currency's base pack (its highest per-credit price),
-     * rounded down; 0 for the base pack itself.
+     * Basis points cheaper per credit before tax than the currency's base pack (its highest pre-tax
+     * price per credit), rounded down; 0 for the base pack itself.
      */
     savingsBps: number;
+    /** Credits received, list value, discount and price paid, to show before payment. */
+    breakdown: CreditPackBreakdown;
+}
+/**
+ * What a pack gives and what it costs, ready to show before payment, so you never work out a
+ * discount yourself. Money is compared before tax, against the same base pack as `savingsBps`, so
+ * tax is never a discount: with the pack's `tax`, `listValue - discount + tax = pricePaid`.
+ */
+interface CreditPackBreakdown {
+    /** Microcredits the buyer receives: `credits` plus `bonusCredits`. */
+    creditsReceived: string;
+    /**
+     * What `creditsReceived` would cost before tax at the base pack's rate (the highest pre-tax
+     * price per credit in the currency), rounded down to the minor unit: never below the pack's own
+     * pre-tax price, and equal to it for the base pack.
+     */
+    listValue: CreditMoney;
+    /** The money saved: `listValue` less the pack's pre-tax price. Never negative; 0 for the base. */
+    discount: CreditMoney;
+    /** What a top-up of the pack charges, tax included: the same as `total`. */
+    pricePaid: CreditMoney;
 }
 /** The packs a customer can buy in one currency, cheapest first. */
 interface CreditPacks {
     currency: string;
     data: CreditPackListItem[];
 }
+/**
+ * How an Included Credit Rule allocates its credits: `billing_period` - the whole period is one
+ * window; `month` - each month of the period is its own window, refilled at its start and expiring
+ * at its end, with no rollover (only on a Price billed for longer than a month).
+ */
+type CreditAllocationInterval = "billing_period" | "month";
+/**
+ * An Included Credit Rule: the credits a subscription on a recurring base Price includes for each
+ * period Billow grants it. At most one live (not archived) rule per Price. A change takes effect
+ * from the next period granted, never on one already granted.
+ */
+interface CreditIncludedRule {
+    id: string;
+    /** The recurring base Price it applies to; never changes. */
+    priceId: string;
+    /** Microcredits each window includes: per billing period, or per month under `month`. */
+    credits: string;
+    /** Whether `credits` and `trialCredits` are multiplied by the base item's quantity (per seat). */
+    perUnit: boolean;
+    /** Microcredits a trial includes, as one window; "0" for none. */
+    trialCredits: string;
+    allocationInterval: CreditAllocationInterval;
+    /** An archived rule includes nothing for periods granted after it was archived. */
+    archived: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Configure an Included Credit Rule on a recurring base Price (`fixed_recurring` or `licensed`, of
+ * a product that is not an add-on).
+ */
+interface CreateCreditIncludedRuleInput {
+    priceId: string;
+    /** Whole microcredits each window includes, as a decimal string; positive. */
+    credits: string;
+    /**
+     * Required: `true` multiplies the credits by the base item's quantity (per-seat credits on a
+     * `licensed` Price); `false` includes them once per subscription whatever the quantity.
+     */
+    perUnit: boolean;
+    /** Whole microcredits a trial includes, as a decimal string; omit for none. */
+    trialCredits?: string;
+    /** `billing_period` when omitted; `month` only on a Price billed for longer than a month. */
+    allocationInterval?: CreditAllocationInterval;
+}
+/**
+ * Edit an Included Credit Rule: any of its terms, or `archived` (`false` brings it back while its
+ * Price has no other live rule). Its Price never changes.
+ */
+type UpdateCreditIncludedRuleInput = Partial<Omit<CreateCreditIncludedRuleInput, "priceId">> & {
+    archived?: boolean;
+};
 /**
  * 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
@@ -354,4 +427,4 @@ interface HostedDomainDisabledData extends HostedDomainEventBase {
     reason: Extract<HostedDomainStatusReason, "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended">;
 }
 
-export type { HostedDomainStatusReason as A, CreditGrantKind as C, 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, CreateCreditTopUpInput as l, CreditTopUpRequestResult as m, CreditTopUpListParams as n, CreditBalance as o, CreditLedgerEntry as p, CreditUsageParams as q, CreditUsage as r, CreditAccountStatus as s, CreditMoney as t, CreditPackListItem as u, CreditTopUpStatus as v, CreditTransactionType as w, CreditUsageGroupBy as x, HostedDomainEventBase as y, HostedDomainStatus as z };
+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 };

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

@@ -218,13 +218,13 @@ interface CreateCreditPackInput {
 type UpdateCreditPackInput = Partial<CreateCreditPackInput> & {
     archived?: boolean;
 };
-/** A pack a customer can buy, with its derived price per credit and savings. */
+/** A pack a customer can buy, with its derived price per credit, savings and breakdown. */
 interface CreditPackListItem {
     id: string;
     name: string;
     credits: string;
     bonusCredits: string;
-    /** The catalog Price: what `pricePerCredit` and `savingsBps` are measured on. */
+    /** The catalog Price: what `pricePerCredit` is measured on. */
     price: CreditMoney;
     /**
      * The tax a top-up of the pack charges (the Price's treatment, else your project's default):
@@ -243,16 +243,89 @@ interface CreditPackListItem {
      */
     pricePerCredit: string;
     /**
-     * Basis points cheaper per credit than the currency's base pack (its highest per-credit price),
-     * rounded down; 0 for the base pack itself.
+     * Basis points cheaper per credit before tax than the currency's base pack (its highest pre-tax
+     * price per credit), rounded down; 0 for the base pack itself.
      */
     savingsBps: number;
+    /** Credits received, list value, discount and price paid, to show before payment. */
+    breakdown: CreditPackBreakdown;
+}
+/**
+ * What a pack gives and what it costs, ready to show before payment, so you never work out a
+ * discount yourself. Money is compared before tax, against the same base pack as `savingsBps`, so
+ * tax is never a discount: with the pack's `tax`, `listValue - discount + tax = pricePaid`.
+ */
+interface CreditPackBreakdown {
+    /** Microcredits the buyer receives: `credits` plus `bonusCredits`. */
+    creditsReceived: string;
+    /**
+     * What `creditsReceived` would cost before tax at the base pack's rate (the highest pre-tax
+     * price per credit in the currency), rounded down to the minor unit: never below the pack's own
+     * pre-tax price, and equal to it for the base pack.
+     */
+    listValue: CreditMoney;
+    /** The money saved: `listValue` less the pack's pre-tax price. Never negative; 0 for the base. */
+    discount: CreditMoney;
+    /** What a top-up of the pack charges, tax included: the same as `total`. */
+    pricePaid: CreditMoney;
 }
 /** The packs a customer can buy in one currency, cheapest first. */
 interface CreditPacks {
     currency: string;
     data: CreditPackListItem[];
 }
+/**
+ * How an Included Credit Rule allocates its credits: `billing_period` - the whole period is one
+ * window; `month` - each month of the period is its own window, refilled at its start and expiring
+ * at its end, with no rollover (only on a Price billed for longer than a month).
+ */
+type CreditAllocationInterval = "billing_period" | "month";
+/**
+ * An Included Credit Rule: the credits a subscription on a recurring base Price includes for each
+ * period Billow grants it. At most one live (not archived) rule per Price. A change takes effect
+ * from the next period granted, never on one already granted.
+ */
+interface CreditIncludedRule {
+    id: string;
+    /** The recurring base Price it applies to; never changes. */
+    priceId: string;
+    /** Microcredits each window includes: per billing period, or per month under `month`. */
+    credits: string;
+    /** Whether `credits` and `trialCredits` are multiplied by the base item's quantity (per seat). */
+    perUnit: boolean;
+    /** Microcredits a trial includes, as one window; "0" for none. */
+    trialCredits: string;
+    allocationInterval: CreditAllocationInterval;
+    /** An archived rule includes nothing for periods granted after it was archived. */
+    archived: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Configure an Included Credit Rule on a recurring base Price (`fixed_recurring` or `licensed`, of
+ * a product that is not an add-on).
+ */
+interface CreateCreditIncludedRuleInput {
+    priceId: string;
+    /** Whole microcredits each window includes, as a decimal string; positive. */
+    credits: string;
+    /**
+     * Required: `true` multiplies the credits by the base item's quantity (per-seat credits on a
+     * `licensed` Price); `false` includes them once per subscription whatever the quantity.
+     */
+    perUnit: boolean;
+    /** Whole microcredits a trial includes, as a decimal string; omit for none. */
+    trialCredits?: string;
+    /** `billing_period` when omitted; `month` only on a Price billed for longer than a month. */
+    allocationInterval?: CreditAllocationInterval;
+}
+/**
+ * Edit an Included Credit Rule: any of its terms, or `archived` (`false` brings it back while its
+ * Price has no other live rule). Its Price never changes.
+ */
+type UpdateCreditIncludedRuleInput = Partial<Omit<CreateCreditIncludedRuleInput, "priceId">> & {
+    archived?: boolean;
+};
 /**
  * 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
@@ -354,4 +427,4 @@ interface HostedDomainDisabledData extends HostedDomainEventBase {
     reason: Extract<HostedDomainStatusReason, "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended">;
 }
 
-export type { HostedDomainStatusReason as A, CreditGrantKind as C, 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, CreateCreditTopUpInput as l, CreditTopUpRequestResult as m, CreditTopUpListParams as n, CreditBalance as o, CreditLedgerEntry as p, CreditUsageParams as q, CreditUsage as r, CreditAccountStatus as s, CreditMoney as t, CreditPackListItem as u, CreditTopUpStatus as v, CreditTransactionType as w, CreditUsageGroupBy as x, HostedDomainEventBase as y, HostedDomainStatus as z };
+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 };

package/dist/index.cjs

@@ -528,6 +528,54 @@ function createCreditsResource(ctx) {
         options
       )
     },
+    includedRules: {
+      /**
+       * Configure an Included Credit Rule on a recurring base Price: the credits a subscription on
+       * it includes for each period Billow grants it - per billing period, or per month of a Price
+       * billed for longer than a month - and for a trial. Configuration, so no idempotency key:
+       * a second live rule for the same Price throws `conflict` (409,
+       * `details.reason: "included_rule_exists"`, with the live rule's `ruleId`). Throws
+       * `validation_error` (422) with `details.reason: "not_a_base_price"` for a Price that is not
+       * a recurring base Price, or `"allocation_not_shorter_than_billing"` for a monthly
+       * allocation on a Price not billed for longer than a month.
+       */
+      create: (input, options) => apiRequest(ctx, "POST", "/v1/credits/included-rules", input, options),
+      /** A rule, archived or not. */
+      get: (ruleId, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/included-rules/${encodeURIComponent(ruleId)}`,
+        void 0,
+        options
+      ),
+      /**
+       * Every rule, archived ones included, newest first. Auto-paginating by cursor: `await` the
+       * first page, `for await (…)` every rule, or `.listAll()` to collect them.
+       */
+      list: (params = {}, options) => makeCursorListPromise(
+        (p) => apiRequest(
+          ctx,
+          "GET",
+          `/v1/credits/included-rules${toQuery(p)}`,
+          void 0,
+          options
+        ),
+        params
+      ),
+      /**
+       * Edit a rule's credits, per-seat choice, trial credits or allocation interval, or archive
+       * it (`archived: false` brings it back). It takes effect from the next period granted;
+       * periods already granted keep what they were granted. A rule left live is judged against
+       * its Price as it is now, with the same errors as `create`.
+       */
+      update: (ruleId, input, options) => apiRequest(
+        ctx,
+        "PATCH",
+        `/v1/credits/included-rules/${encodeURIComponent(ruleId)}`,
+        input,
+        options
+      )
+    },
     topUps: {
       /**
        * Buy a Credit Pack for a customer: answers the top-up with `checkoutUrl`, the hosted
@@ -708,6 +756,24 @@ function createCreditsResource(ctx) {
         void 0,
         options
       ),
+      /**
+       * Your project's reservations, oldest first, optionally of one `status`, one `customer` (by
+       * external id), or protected more than `protectedLongerThan` seconds ago - with
+       * `{ status: "protected", protectedLongerThan: page.protectedHoldMaxSeconds }`, the paid
+       * operations waiting past your maximum for a decision (commit or release each). Every page
+       * carries `protectedHoldMaxSeconds`. Auto-paginating by cursor: `await` the first page,
+       * `for await (…)` every reservation, or `.listAll()` to collect them.
+       */
+      list: (params = {}, options) => makeCursorListPromise(
+        (p) => apiRequest(
+          ctx,
+          "GET",
+          `/v1/credits/reservations${toQuery(p)}`,
+          void 0,
+          options
+        ),
+        params
+      ),
       /**
        * A customer's reservation (by external id) made with `operationKey` - how to find one whose
        * reply was lost. Throws `not_found` (404) when there is none.
@@ -1619,6 +1685,21 @@ var BillowPortal = class {
   session(options) {
     return apiRequest(this.#ctx, "GET", "/portal/session", void 0, options);
   }
+  /**
+   * The single-use entry exchange (ADR-0039): on a client built with a minted link's entry
+   * token, trade it for the session token to use from now on. Succeeds once per link, and
+   * afterwards only for the browser presenting that exchange's `sessionToken`; anything else is
+   * a 401. For a hosted surface; an integrator's own surface may keep using the entry token.
+   */
+  exchange(input, options) {
+    return apiRequest(
+      this.#ctx,
+      "POST",
+      "/portal/session/exchange",
+      input,
+      options
+    );
+  }
   /** The self-serve home payload: identity + subscriptions + usage + saved cards. */
   me(options) {
     return apiRequest(this.#ctx, "GET", "/portal/me", void 0, options);
@@ -1635,6 +1716,14 @@ var BillowPortal = class {
       ),
       params
     ),
+    /** One of the Customer's invoices, in the list's shape. */
+    get: (id, options) => apiRequest(
+      this.#ctx,
+      "GET",
+      `/portal/invoices/${encodeURIComponent(id)}`,
+      void 0,
+      options
+    ),
     /** Open or resume checkout for this customer's outstanding invoice. */
     pay: (id, input = {}, options) => apiRequest(
       this.#ctx,