@usebillow/sdk 0.5.0 → 0.7.0

package/dist/index.cjs

@@ -133,10 +133,10 @@ function resolveBaseUrl(explicit) {
   const fromEnv = typeof process !== "undefined" ? process.env?.["BILLOW_URL"] : void 0;
   return (explicit || fromEnv || DEFAULT_BASE_URL).replace(/\/$/, "");
 }
-async function apiRequest(ctx, method, path, body, options) {
-  return (await apiRequestWithStatus(ctx, method, path, body, options)).data;
+async function apiRequest(ctx, method, path2, body, options) {
+  return (await apiRequestWithStatus(ctx, method, path2, body, options)).data;
 }
-async function apiRequestWithStatus(ctx, method, path, body, options) {
+async function apiRequestWithStatus(ctx, method, path2, body, options) {
   const init = {
     method,
     headers: {
@@ -146,7 +146,7 @@ async function apiRequestWithStatus(ctx, method, path, body, options) {
     }
   };
   if (body) init.body = JSON.stringify(body);
-  const res = await sendWithResilience(ctx, `${ctx.baseUrl}${path}`, init, {
+  const res = await sendWithResilience(ctx, `${ctx.baseUrl}${path2}`, init, {
     timeoutMs: options?.timeoutMs ?? ctx.timeoutMs,
     safeToRepeat: safeToRepeat(method, !!options?.idempotencyKey),
     callerSignal: options?.signal
@@ -192,10 +192,10 @@ function errorFrom(res, data) {
     requestIdOf(res)
   );
 }
-async function apiRequestBinary(ctx, method, path, options) {
+async function apiRequestBinary(ctx, method, path2, options) {
   const res = await sendWithResilience(
     ctx,
-    `${ctx.baseUrl}${path}`,
+    `${ctx.baseUrl}${path2}`,
     { method, headers: { authorization: `Bearer ${ctx.bearer}` } },
     {
       timeoutMs: options?.timeoutMs ?? ctx.timeoutMs,
@@ -534,11 +534,14 @@ function createCreditsResource(ctx) {
        * checkout to send the buyer to. Credits are granted when the payment succeeds (listen for
        * `credit_top_up.succeeded`). The `idempotencyKey` is required and must identify this one
        * purchase: a retry under it answers the same top-up as it now stands (`replayed: true`) and
-       * buys nothing again; reusing it for another purchase throws `idempotency_conflict` (409).
-       * A retry can also throw `conflict` (409), with `details.reason`: `checkout_in_progress` -
-       * the first request is still opening the checkout, so retry the same key shortly - or
-       * `checkout_unavailable` - its checkout could not be opened and never will be, so buy again
-       * under a new key.
+       * buys nothing again - asking the payment provider again for a checkout the first attempt
+       * could not open, within its page's 40 minutes (Stripe only in the first 10, while 30
+       * remain: it answers a timed-out first attempt with the checkout it made, or makes one never
+       * made; Paymob only if the first attempt never made one); reusing it for another purchase
+       * throws `idempotency_conflict` (409). A retry can also throw `conflict` (409), with
+       * `details.reason`: `checkout_in_progress` - another request is still opening the
+       * checkout, so retry the same key shortly - or `checkout_unavailable` - its checkout could
+       * not be opened and never will be, so buy again under a new key.
        */
       create: async (input, options) => {
         const { status, data } = await apiRequestWithStatus(
@@ -620,6 +623,155 @@ function createCreditsResource(ctx) {
         void 0,
         options
       )
+    },
+    rateCards: {
+      /**
+       * 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).
+       */
+      publish: (input, options) => apiRequest(ctx, "POST", "/v1/credits/rate-cards", input, options),
+      /** The version in effect now (`not_found` before the first takes effect). */
+      current: (options) => apiRequest(
+        ctx,
+        "GET",
+        "/v1/credits/rate-cards/current",
+        void 0,
+        options
+      ),
+      /** One version, by its number. */
+      get: (version, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/rate-cards/${encodeURIComponent(String(version))}`,
+        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.
+       */
+      list: (params = {}, options) => makeCursorListPromise(
+        (p) => apiRequest(
+          ctx,
+          "GET",
+          `/v1/credits/rate-cards${toQuery(p)}`,
+          void 0,
+          options
+        ),
+        params
+      )
+    },
+    quotes: {
+      /**
+       * Price a customer's Credit Actions (all of one category) at the current Rate Card version
+       * and keep the price for 15 minutes: a reservation over the quote holds exactly its
+       * `amount`, and its commit prices at the version the quote pinned. A quote holds nothing.
+       */
+      create: (input, options) => apiRequest(ctx, "POST", "/v1/credits/quotes", input, options),
+      /** A quote as it was made. */
+      get: (quoteId, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/quotes/${encodeURIComponent(quoteId)}`,
+        void 0,
+        options
+      )
+    },
+    reservations: {
+      /**
+       * Hold credits for one operation: over a `quoteId`, or over `items` priced at the current
+       * Rate Card version. The `idempotencyKey` is required: a retry under it - after a lost
+       * reply, even once the quote expired - answers the same reservation (`replayed: true`) and
+       * holds nothing again. Reusing it for another request, or a new key with an `operationKey`
+       * the customer already used (`details.reason: "operation_key_used"`), throws
+       * `idempotency_conflict` (409). Throws `insufficient_credits` (402), `account_frozen`
+       * (423), `account_closed` (409), `conflict` (409, `details.reason: "quote_expired"`), or
+       * `validation_error` (422) - e.g. `details.reason: "zero_amount"` when the items cost nothing.
+       * The `operationKey` is an operation id, never personal data: erasure replaces it.
+       */
+      create: async (input, options) => {
+        const { status, data } = await apiRequestWithStatus(
+          ctx,
+          "POST",
+          "/v1/credits/reservations",
+          input,
+          options
+        );
+        return { ...data, replayed: status === 200 };
+      },
+      /** A reservation as it now stands. */
+      get: (reservationId, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/reservations/${encodeURIComponent(reservationId)}`,
+        void 0,
+        options
+      ),
+      /**
+       * 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.
+       */
+      findByOperationKey: (customer, operationKey, options) => apiRequest(
+        ctx,
+        "GET",
+        `/v1/credits/reservations${toQuery({ customer, operationKey })}`,
+        void 0,
+        options
+      ),
+      /**
+       * Commit what the operation used: lines priced at the reservation's Rate Card version,
+       * consuming at most what it holds (`commit_exceeds_hold`, 409) and releasing the rest; lines
+       * that cost nothing in all consume nothing (`consumed: "0"`, `consumptionId: null`). The
+       * same commit again answers it again, so it is safe to retry; anything else after it throws
+       * `invalid_state_transition` (409) with the reservation in `details` - with
+       * `details.reason: "reservation_expired"` once the hold is past its `expiresAt`.
+       */
+      commit: (reservationId, items, options) => apiRequest(
+        ctx,
+        "POST",
+        `/v1/credits/reservations/${encodeURIComponent(reservationId)}/commit`,
+        { items },
+        options
+      ),
+      /** Release the whole hold. Safe to retry; after a commit it throws (409). */
+      release: (reservationId, options) => apiRequest(
+        ctx,
+        "POST",
+        `/v1/credits/reservations/${encodeURIComponent(reservationId)}/release`,
+        void 0,
+        options
+      ),
+      /**
+       * Protect a held reservation whose operation was paid for and is still being fulfilled: it
+       * never expires (commit or release it when done). Safe to retry. A hold already past its
+       * `expiresAt` throws `invalid_state_transition` (409, `details.reason: "reservation_expired"`).
+       */
+      protect: (reservationId, options) => apiRequest(
+        ctx,
+        "POST",
+        `/v1/credits/reservations/${encodeURIComponent(reservationId)}/protect`,
+        void 0,
+        options
+      )
+    },
+    consumptions: {
+      /**
+       * Give back part or all of a commit's consumption (`consumptionId` on the committed
+       * reservation), never more than is left (`reversal_exceeds_consumption`, 409). The
+       * `idempotencyKey` is required: a retry under it answers the same reversal
+       * (`replayed: true`) and gives nothing back again.
+       */
+      reverse: async (consumptionId, input, options) => {
+        const { status, data } = await apiRequestWithStatus(
+          ctx,
+          "POST",
+          `/v1/credits/consumptions/${encodeURIComponent(consumptionId)}/reverse`,
+          input,
+          options
+        );
+        return { ...data, replayed: status === 200 };
+      }
     }
   };
 }
@@ -732,6 +884,33 @@ function createDeliverabilityResource(ctx) {
   };
 }
 
+// src/resources/hosted-domains.ts
+var path = (id, action = "") => `/v1/hosted-domains/${encodeURIComponent(id)}${action}`;
+function createHostedDomainsResource(ctx) {
+  return {
+    /** The Project's domains, and whether its plan allows adding more (`whiteLabel`). */
+    list: (options) => apiRequest(ctx, "GET", "/v1/hosted-domains", void 0, options),
+    /**
+     * Add a subdomain such as `billing.example.com`. Answers the domain with the TXT and CNAME
+     * `records` to create. Needs a plan with white-label branding (`permission_denied` otherwise).
+     */
+    create: (input, options) => apiRequest(ctx, "POST", "/v1/hosted-domains", input, options),
+    get: (id, options) => apiRequest(ctx, "GET", path(id), void 0, options),
+    /** Check the DNS records now (2 per minute per domain); answers the refreshed domain. */
+    verify: (id, options) => apiRequest(ctx, "POST", path(id, "/verify"), void 0, options),
+    /** Make an active domain the default host for new portal sessions. */
+    makePrimary: (id, options) => apiRequest(ctx, "POST", path(id, "/primary"), void 0, options),
+    /** Remove a domain; the portal sessions on it end immediately. */
+    remove: (id, options) => apiRequest(
+      ctx,
+      "DELETE",
+      path(id),
+      void 0,
+      options
+    )
+  };
+}
+
 // src/resources/invoices.ts
 function createInvoicesResource(ctx) {
   return {
@@ -1197,6 +1376,8 @@ var Billow = class {
   portalSessions;
   deliverability;
   marketplace;
+  /** Custom domains for the hosted customer portal (live keys, behind a rollout flag). */
+  hostedDomains;
   /**
    * Organization settings (Phase D3, F) — the configurable dunning schedule, usage settlement grace,
    * and the cross-currency reporting currency + FX-rate registry (ADR-0013).
@@ -1217,10 +1398,11 @@ var Billow = class {
     this.portalSessions = createPortalSessionsResource(this.#ctx);
     this.deliverability = createDeliverabilityResource(this.#ctx);
     this.marketplace = createMarketplaceResource(this.#ctx);
+    this.hostedDomains = createHostedDomainsResource(this.#ctx);
     this.settings = createSettingsResource(this.#ctx);
   }
-  #request(method, path, body, options) {
-    return apiRequest(this.#ctx, method, path, body, options);
+  #request(method, path2, body, options) {
+    return apiRequest(this.#ctx, method, path2, body, options);
   }
   coupons = {
     /** Define a coupon (a reusable discount template). */
@@ -1437,6 +1619,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);
@@ -1453,6 +1650,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,