@usebillow/sdk 0.10.0 → 0.12.0

package/dist/config.d.cts

@@ -1,10 +1,10 @@
 import { Billow } from './index.cjs';
-import { F as FeatureKind, M as MeterConfig, C as CreateProductInput, a as CreateCouponInput } from './billing-8ug1Gw05.cjs';
-import './index.d-DSEYhV2c.cjs';
+import { F as FeatureKind, M as MeterConfig, C as CreateProductInput, a as CreateCouponInput } from './billing-CDEO8Jqv.cjs';
+import './index.d-D5v2ETKF.cjs';
 import 'zod';
 import './billing-status-DZkB0VPK.cjs';
 import './status.cjs';
-import './hosted-domains-Ci6jeNAe.cjs';
+import './hosted-domains-Cuk3j04R.cjs';
 
 /**
  * Code-as-config sync (ARCHITECTURE §12 "code-as-config sync"). Keep your catalog

package/dist/config.d.ts

@@ -1,10 +1,10 @@
 import { Billow } from './index.js';
-import { F as FeatureKind, M as MeterConfig, C as CreateProductInput, a as CreateCouponInput } from './billing-Bs10EcjR.js';
-import './index.d-DSEYhV2c.js';
+import { F as FeatureKind, M as MeterConfig, C as CreateProductInput, a as CreateCouponInput } from './billing-BEbVLGe9.js';
+import './index.d-D5v2ETKF.js';
 import 'zod';
 import './billing-status-DZkB0VPK.js';
 import './status.js';
-import './hosted-domains-DSs5Iw9U.js';
+import './hosted-domains-DMgokjiv.js';
 
 /**
  * Code-as-config sync (ARCHITECTURE §12 "code-as-config sync"). Keep your catalog

package/dist/{hosted-domains-Ci6jeNAe.d.cts → hosted-domains-Cuk3j04R.d.cts}

@@ -1,4 +1,4 @@
-import { H as HostedDomainResponse } from './index.d-DSEYhV2c.cjs';
+import { H as HostedDomainResponse } from './index.d-D5v2ETKF.cjs';
 
 /**
  * Public SDK types for prepaid credits. Re-exported by ../types.ts.
@@ -67,6 +67,17 @@ interface CreateCreditGrantInput {
 }
 /** A Credit Account's status: `frozen` takes no new reservations; `closed` (erased) takes nothing. */
 type CreditAccountStatus = "active" | "frozen" | "closed";
+/** A customer's Credit Account status, as `credits.accounts.freeze` and `.unfreeze` answer it. */
+interface CreditAccount {
+    /** The customer's external id. */
+    customerId: string;
+    status: CreditAccountStatus;
+    /**
+     * Whether this call moved the account to `status`, decided under the account's lock: false for a
+     * repeat (freezing a frozen account), so of two racing calls exactly one reports the change.
+     */
+    changed: boolean;
+}
 /** What current Included Credit Windows include, and where it stands. */
 interface IncludedCredits {
     /** What the windows include. */
@@ -157,8 +168,8 @@ interface CreditLedgerEntry {
     type: CreditTransactionType;
     /**
      * Why Billow posted it, as a system code (`api_grant`, `grant_expired`, `subscription_period`,
-     * `subscription_upgrade`, `subscription_canceled`, `subscription_charged_back`, ...); never free
-     * text.
+     * `subscription_upgrade`, `subscription_canceled`, `subscription_charged_back`, `sandbox_seed`,
+     * ...); never free text.
      */
     reason: string | null;
     /** How it moved the account's unheld credits (signed). */
@@ -168,6 +179,11 @@ interface CreditLedgerEntry {
     availableAfter: string;
     heldAfter: string;
     grantId: string | null;
+    /**
+     * The kind of `grantId`'s grant - a promotional grant and an adjustment both read `api_grant` as
+     * their `reason`; null when the transaction names no one grant (a hold, a commit, a reversal).
+     */
+    grantKind: CreditGrantKind | null;
     reservationId: string | null;
     topUpId: string | null;
     /** On a reversal: the consumption (its `consume` transaction) it gives back. */
@@ -446,6 +462,8 @@ interface CreditTopUp {
     /** The customer's external id. */
     customerId: string;
     packId: string;
+    /** The pack's name when it was bought (renaming the pack later changes no purchase). */
+    packName: string;
     status: CreditTopUpStatus;
     /** The terms bought: what success grants. */
     credits: string;
@@ -461,6 +479,12 @@ interface CreditTopUp {
     checkoutUrl: string | null;
     purchasedGrantId: string | null;
     bonusGrantId: string | null;
+    /**
+     * Microcredits of the credits it granted that the customer has spent (consumed, net of
+     * reversals). A refund can never take these back: refunding the whole payment leaves them as its
+     * `shortfall`.
+     */
+    consumed: string;
     /** Microcredits refunds and lost chargebacks of the payment have revoked so far. */
     revoked: string;
     /** Of the revoked credits, those already spent and not paid back since. */
@@ -534,4 +558,4 @@ interface HostedDomainDisabledData extends HostedDomainEventBase {
     reason: Extract<HostedDomainStatusReason, "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended">;
 }
 
-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 };
+export type { CreditMoney as A, CreditPackBreakdown as B, CreditGrantKind as C, CreditPackListItem as D, CreditTopUpStatus as E, CreditTransactionType as F, CreditUsageGroupBy as G, HostedDomainActivatedData as H, CreditWindowState as I, HostedDomainEventBase as J, HostedDomainStatus as K, HostedDomainStatusReason as L, IncludedCredits as M, IncludedPeriod as N, 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, CreditAccount as j, CreditPacks as k, CreateCreditPackInput as l, CreditPack as m, CreateCreditIncludedRuleInput as n, CreditIncludedRule as o, UpdateCreditIncludedRuleInput as p, CreditIncludedWindowListParams as q, CreateCreditTopUpInput as r, CreditTopUpRequestResult as s, CreditTopUpListParams as t, CreditBalance as u, CreditLedgerEntry as v, CreditUsageParams as w, CreditUsage as x, CreditAccountStatus as y, CreditAllocationInterval as z };

package/dist/{hosted-domains-DSs5Iw9U.d.ts → hosted-domains-DMgokjiv.d.ts}

@@ -1,4 +1,4 @@
-import { H as HostedDomainResponse } from './index.d-DSEYhV2c.js';
+import { H as HostedDomainResponse } from './index.d-D5v2ETKF.js';
 
 /**
  * Public SDK types for prepaid credits. Re-exported by ../types.ts.
@@ -67,6 +67,17 @@ interface CreateCreditGrantInput {
 }
 /** A Credit Account's status: `frozen` takes no new reservations; `closed` (erased) takes nothing. */
 type CreditAccountStatus = "active" | "frozen" | "closed";
+/** A customer's Credit Account status, as `credits.accounts.freeze` and `.unfreeze` answer it. */
+interface CreditAccount {
+    /** The customer's external id. */
+    customerId: string;
+    status: CreditAccountStatus;
+    /**
+     * Whether this call moved the account to `status`, decided under the account's lock: false for a
+     * repeat (freezing a frozen account), so of two racing calls exactly one reports the change.
+     */
+    changed: boolean;
+}
 /** What current Included Credit Windows include, and where it stands. */
 interface IncludedCredits {
     /** What the windows include. */
@@ -157,8 +168,8 @@ interface CreditLedgerEntry {
     type: CreditTransactionType;
     /**
      * Why Billow posted it, as a system code (`api_grant`, `grant_expired`, `subscription_period`,
-     * `subscription_upgrade`, `subscription_canceled`, `subscription_charged_back`, ...); never free
-     * text.
+     * `subscription_upgrade`, `subscription_canceled`, `subscription_charged_back`, `sandbox_seed`,
+     * ...); never free text.
      */
     reason: string | null;
     /** How it moved the account's unheld credits (signed). */
@@ -168,6 +179,11 @@ interface CreditLedgerEntry {
     availableAfter: string;
     heldAfter: string;
     grantId: string | null;
+    /**
+     * The kind of `grantId`'s grant - a promotional grant and an adjustment both read `api_grant` as
+     * their `reason`; null when the transaction names no one grant (a hold, a commit, a reversal).
+     */
+    grantKind: CreditGrantKind | null;
     reservationId: string | null;
     topUpId: string | null;
     /** On a reversal: the consumption (its `consume` transaction) it gives back. */
@@ -446,6 +462,8 @@ interface CreditTopUp {
     /** The customer's external id. */
     customerId: string;
     packId: string;
+    /** The pack's name when it was bought (renaming the pack later changes no purchase). */
+    packName: string;
     status: CreditTopUpStatus;
     /** The terms bought: what success grants. */
     credits: string;
@@ -461,6 +479,12 @@ interface CreditTopUp {
     checkoutUrl: string | null;
     purchasedGrantId: string | null;
     bonusGrantId: string | null;
+    /**
+     * Microcredits of the credits it granted that the customer has spent (consumed, net of
+     * reversals). A refund can never take these back: refunding the whole payment leaves them as its
+     * `shortfall`.
+     */
+    consumed: string;
     /** Microcredits refunds and lost chargebacks of the payment have revoked so far. */
     revoked: string;
     /** Of the revoked credits, those already spent and not paid back since. */
@@ -534,4 +558,4 @@ interface HostedDomainDisabledData extends HostedDomainEventBase {
     reason: Extract<HostedDomainStatusReason, "dns_lost" | "reassigned" | "entitlement_lapsed" | "suspended">;
 }
 
-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 };
+export type { CreditMoney as A, CreditPackBreakdown as B, CreditGrantKind as C, CreditPackListItem as D, CreditTopUpStatus as E, CreditTransactionType as F, CreditUsageGroupBy as G, HostedDomainActivatedData as H, CreditWindowState as I, HostedDomainEventBase as J, HostedDomainStatus as K, HostedDomainStatusReason as L, IncludedCredits as M, IncludedPeriod as N, 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, CreditAccount as j, CreditPacks as k, CreateCreditPackInput as l, CreditPack as m, CreateCreditIncludedRuleInput as n, CreditIncludedRule as o, UpdateCreditIncludedRuleInput as p, CreditIncludedWindowListParams as q, CreateCreditTopUpInput as r, CreditTopUpRequestResult as s, CreditTopUpListParams as t, CreditBalance as u, CreditLedgerEntry as v, CreditUsageParams as w, CreditUsage as x, CreditAccountStatus as y, CreditAllocationInterval as z };

package/dist/index.cjs

@@ -249,7 +249,9 @@ var BILLOW_ERROR_CODES = [
   "account_closed",
   "idempotency_conflict",
   "commit_exceeds_hold",
-  "reversal_exceeds_consumption"
+  "reversal_exceeds_consumption",
+  // Merchant custom domains (ADR-0039): a portal session asked for a host that cannot serve it.
+  "hosted_domain_unavailable"
 ];
 
 // src/money.ts
@@ -433,6 +435,16 @@ function createChargesResource(ctx) {
       `/v1/charges/${encodeURIComponent(chargeId)}/refunds/${encodeURIComponent(refundId)}/credit-note.pdf`,
       options
     ),
+    /**
+     * Download a credit note voided on a refund (one of its `voidedCreditNotes`), exactly as it was
+     * issued and badged VOID.
+     */
+    voidedCreditNote: (chargeId, refundId, creditNoteNumber, options) => apiRequestBinary(
+      ctx,
+      "GET",
+      `/v1/charges/${encodeURIComponent(chargeId)}/refunds/${encodeURIComponent(refundId)}/credit-note.pdf?number=${encodeURIComponent(creditNoteNumber)}`,
+      options
+    ),
     /**
      * Refund a succeeded charge: `{ amount }` (minor units) for a partial, `{}` for its whole
      * remaining balance. The `idempotencyKey` is required and must identify this one refund
@@ -476,7 +488,10 @@ function createChargesResource(ctx) {
     /**
      * Record the outcome you verified in the provider dashboard for a refund awaiting review
      * (`needsReview`): `succeeded` settles it with a credit note, `failed` releases its amount.
-     * A refund with a provider conflict (`providerConflictStatus`) resolves only as `succeeded`.
+     * A refund with a provider conflict (`providerConflictStatus`) recorded `failed` resolves only
+     * as `succeeded`; one recorded `succeeded` that the provider later reported failed (a reversal:
+     * the customer's bank returned the money) resolves either way, `failed` making its amount
+     * refundable again.
      */
     resolveRefund: (chargeId, refundId, input, options) => apiRequest(ctx, "POST", `${refundPath(chargeId, refundId)}/resolve`, input, options)
   };
@@ -519,6 +534,35 @@ function createCreditsResource(ctx) {
         return { ...data, replayed: status === 200 };
       }
     },
+    accounts: {
+      /**
+       * Freeze a customer's Credit Account (by external id): it takes no new reservations - a
+       * reserve throws `account_frozen` (423) - until unfrozen, while holds already made still
+       * commit and release, and grants, top-ups, reversals and included credits still fund it.
+       * Safe to retry: freezing a frozen account changes nothing and answers `changed: false`. A
+       * customer with no account yet gets one, frozen. Throws `account_closed` (409) for an erased
+       * customer.
+       */
+      freeze: (customer, options) => apiRequest(
+        ctx,
+        "POST",
+        "/v1/credits/accounts/freeze",
+        { customerId: customer },
+        options
+      ),
+      /**
+       * Unfreeze a customer's Credit Account (by external id): it takes reservations again. Safe to
+       * retry: unfreezing an account that is not frozen changes nothing and answers
+       * `changed: false`.
+       */
+      unfreeze: (customer, options) => apiRequest(
+        ctx,
+        "POST",
+        "/v1/credits/accounts/unfreeze",
+        { customerId: customer },
+        options
+      )
+    },
     packs: {
       /**
        * The Credit Packs a customer can buy in `currency` (ISO 4217), cheapest first: credits and
@@ -724,7 +768,8 @@ function createCreditsResource(ctx) {
       /**
        * Publish a new Rate Card version: what each Credit Action costs, as
        * `ceil(units * unitPrice / perUnits)` microcredits a line. Versions are immutable - a price
-       * change is a new version - and take effect in order, at `effectiveAt` (now when omitted).
+       * change is a new version - and take effect in order, at `effectiveAt` (now when omitted),
+       * unless retracted before then.
        */
       publish: (input, options) => apiRequest(ctx, "POST", "/v1/credits/rate-cards", input, options),
       /** The version in effect now (`not_found` before the first takes effect). */
@@ -743,6 +788,20 @@ function createCreditsResource(ctx) {
         void 0,
         options
       ),
+      /**
+       * Retract a version before it takes effect: it never does (`retractedAt` is set), and
+       * versions published after it take effect in order after the last one not retracted - so a
+       * scheduled price change no longer holds back an earlier correction. Safe to retry: a
+       * retracted version answers as retracted. A version already in effect, current or
+       * superseded, throws `conflict` (409, `details.reason: "already_effective"`).
+       */
+      retract: (version, options) => apiRequest(
+        ctx,
+        "POST",
+        `/v1/credits/rate-cards/${encodeURIComponent(String(version))}/retract`,
+        void 0,
+        options
+      ),
       /**
        * The published versions, newest first. Auto-paginating by cursor: `await` the first page,
        * `for await (…)` every version, or `.listAll()` to collect them.