@usebillow/sdk 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @usebillow/sdk
 
+## 0.6.0
+
+### Minor Changes
+
+- a7dff2a: Prepaid credits can be spent. `credits.rateCards.publish`, `current`, `get(version)` and `list` manage immutable Rate Card versions that price each Credit Action as `ceil(units * unitPrice / perUnits)` microcredits. `credits.quotes.create` prices a customer's actions at the current version and pins it for 15 minutes; `credits.quotes.get` reads one back. `credits.reservations.create(input, { idempotencyKey })` holds credits over a quote or over items (answering `replayed` for a retry), `get` and `findByOperationKey(customer, operationKey)` read one, and `commit(id, items)`, `release(id)` and `protect(id)` settle it, the commit priced at the reservation's pinned version. `credits.consumptions.reverse(consumptionId, input, { idempotencyKey })` gives back part or all of a commit. Counts of units travel as decimal strings like credit quantities, and the customer data export types carry `quotes` and each reservation's `quoteId` and `rateCardVersion`.
+- d80455e: Custom domains for the hosted customer portal. `hostedDomains.create({ hostname })` adds a subdomain and answers the TXT and CNAME `records` to create; `hostedDomains.list()`, `get`, `verify` (check the DNS now), `makePrimary` and `remove` (which answers the removed hostname) manage them. They need a live secret key and a plan with white-label branding (a `permission_denied` refusal names the plan in its `details`). `me()` reports `hostedDomainsEnabled`. Webhook payload types cover the new `hosted_domain.activated`, `hosted_domain.dns_failing`, `hosted_domain.reassignment_pending` and `hosted_domain.disabled` events, grouped as `HOSTED_DOMAIN_EVENT_TYPES`.
+
+### Patch Changes
+
+- 4fe3a05: Document when retrying `credits.topUps.create` under the same `idempotencyKey` opens a checkout the first attempt could not: within the page's 40 minutes, Stripe only in the first 10 (while 30 remain), answering a timed-out first attempt with the checkout it made or making one never made, and Paymob only if the first attempt never made one. Otherwise the retry answers `checkout_unavailable`.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -88,6 +88,15 @@ for await (const entry of billow.credits.ledger.list(customerId)) {
 const usage = await billow.credits.usage.get(customerId, { groupBy: "category" });
 ```
 
+Serve the hosted customer portal on your own subdomain (live secret key, a plan with white-label
+branding): add the hostname, create the two DNS records it answers, and Billow verifies them.
+
+```ts
+const domain = await billow.hostedDomains.create({ hostname: "billing.example.com" });
+// domain.records: the _billow-challenge TXT record and the CNAME to create
+const checked = await billow.hostedDomains.verify(domain.id); // check now; read checked.status
+```
+
 ## Auto-metering (LLM tokens & any usage source)
 
 Stop hand-instrumenting usage. `@usebillow/sdk/ingestion` wraps your calls and reports

package/dist/billing-B-VyZCXV.d.cts

@@ -0,0 +1,371 @@
+import { A as ActivatedSubscriptionResponse, C as CreateSubscriptionResponse, P as PendingSubscriptionCheckoutResponse, a as ProductResponse, b as ProductEntitlementResponse, c as ProductPriceResponse, S as SubscriptionResponse, d as SubscriptionDetailResponse, e as SubscriptionItemResponse } from './index.d-CKQAhQfJ.cjs';
+import { C as ChargeStatus } from './billing-status-BZQN_gm7.cjs';
+
+/** Public SDK types for this domain. Re-exported by ../types.ts. */
+interface BillowOptions {
+    /**
+     * Base URL of the Billow API. Falls back to the `BILLOW_URL` env var, then to the hosted
+     * API at `https://api.usebillow.com`. Set it for local development (for example
+     * `http://localhost:4001`) or a self-hosted server.
+     */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    /**
+     * Hard per-request timeout in milliseconds; the request is aborted once it elapses.
+     * Defaults to 60_000. Set `0` to disable the timeout.
+     */
+    timeoutMs?: number;
+    /**
+     * How many times to retry a transient failure. Retries are **opt-in** — the default is
+     * `0`. Only requests that are safe to repeat are retried: every `GET`, plus **any** method
+     * on a `429` (a rate-limited request never executed). A write (`POST`/`PATCH`/`DELETE`) is
+     * never retried on a `5xx`/network error, since it may have already applied.
+     */
+    maxRetries?: number;
+    /**
+     * Base backoff in milliseconds between retries — exponential (`base × 2^attempt`), and a
+     * `Retry-After` response header takes precedence when present. Defaults to 500.
+     */
+    retryBackoffMs?: number;
+}
+/**
+ * Per-call overrides passed as the last argument to a resource method.
+ * - `signal` cancels the request (a caller abort is surfaced immediately and never retried).
+ * - `timeoutMs` overrides the client's default timeout for this call (applied per attempt).
+ * - `idempotencyKey` sends an `Idempotency-Key` and makes the write **safe to retry** — reused
+ *   verbatim on every attempt. Only exposed on writes the server replays (create/attach/track/refund).
+ */
+interface RequestOptions {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    idempotencyKey?: string;
+}
+/** Options for writes that require a stable idempotency key. */
+type IdempotentRequestOptions = RequestOptions & {
+    idempotencyKey: string;
+};
+/** Per-call overrides for reads and non-replayable writes — cancellation + timeout, no idempotency key. */
+type CallOptions = Omit<RequestOptions, "idempotencyKey">;
+interface Customer {
+    id: string;
+    externalId: string;
+    name?: string | null;
+    email?: string | null;
+    phone?: string | null;
+    /** The customer's tax / VAT registration number, recorded on their invoices. */
+    taxId?: string | null;
+}
+/** How a price's tax relates to its amount: added on top (`exclusive`) or contained (`inclusive`). */
+type TaxBehavior = "exclusive" | "inclusive";
+interface CheckResult {
+    feature: string;
+    allowed: boolean;
+    balance: number | null;
+}
+interface AttachResult {
+    /** Hosted checkout URL to redirect the customer to (null if none was minted). */
+    url: string | null;
+    /** Null until a paid first-cycle checkout succeeds and creates the subscription. */
+    subscriptionId: string | null;
+    checkoutSessionId: string | null;
+}
+type BillingInterval = "day" | "week" | "month" | "year";
+type FeatureKind = "boolean" | "metered";
+type MeterAggregation = "count" | "sum" | "max" | "latest" | "count_unique";
+type MeterRoundingMode = "none" | "round" | "ceil" | "floor";
+interface MeterFilter {
+    key: string;
+    values: string[];
+}
+/** A meter's measurement config (ADR-0011) — how a metered feature's usage aggregates. */
+interface MeterConfig {
+    aggregation: MeterAggregation;
+    eventProperty?: string | null;
+    filters?: MeterFilter[];
+    roundingMode?: MeterRoundingMode;
+    roundingScale?: number | null;
+    /**
+     * Reset window anchoring (plan 07). Omitted/`cycle` = subscription anniversary in UTC
+     * (default). `calendar` tiles windows on calendar months in `resetTz` and REQUIRES a
+     * canonical IANA `resetTz` (e.g. `"Africa/Cairo"`, `"UTC"`).
+     */
+    resetAnchor?: "cycle" | "calendar";
+    resetTz?: string | null;
+}
+/** How a usage price turns billable quantity into money. */
+type UsageModel = "graduated" | "volume" | "package" | "percentage" | "stairstep";
+/** A usage-pricing tier (`upTo: null` = the unbounded last tier). */
+interface UsageTier {
+    upTo: number | null;
+    unitAmount: number;
+    flatAmount?: number;
+}
+
+/** Public SDK types for this domain. Re-exported by ../types.ts. */
+
+interface PriceInput {
+    /** `licensed` = per-unit recurring, billed × the subscription item's quantity (seats). */
+    kind: "fixed_recurring" | "licensed" | "one_time" | "usage";
+    interval?: BillingInterval;
+    intervalCount?: number;
+    /** Amount in minor units (per unit for `usage` prices without tiers). */
+    amount: number;
+    currency: string;
+    /** For `usage` prices: the metered feature's slug. */
+    meterFeature?: string;
+    /** For `usage` prices: the pricing model (default graduated). */
+    usageModel?: UsageModel;
+    /** For `usage` prices: tiers for graduated/volume/stairstep (overrides flat `amount`). */
+    usageTiers?: UsageTier[];
+    /** For `package` pricing: units per package (each priced at `amount`). */
+    packageSize?: number;
+    /** For `percentage` pricing: basis points of the metered amount. */
+    rateBps?: number;
+    /** Tax rate override in basis points; omit to inherit the org default, 0 = zero-rated. */
+    taxRateBps?: number | null;
+    /** Tax behavior override; omit to inherit the org default. */
+    taxBehavior?: TaxBehavior | null;
+}
+interface EntitlementInput {
+    /** The feature's slug (must already exist). */
+    feature: string;
+    /** Included units; `null`/omitted = unlimited. */
+    allowance?: number | null;
+    /** How often the balance refills; omitted = only on renewal. */
+    resetInterval?: BillingInterval;
+    rollover?: boolean;
+}
+interface CreateProductInput {
+    slug: string;
+    name: string;
+    type: "recurring" | "one_time";
+    isAddOn?: boolean;
+    /** Free-form string map that round-trips on the product + on subscription.* webhooks. */
+    metadata?: Record<string, string>;
+    prices: PriceInput[];
+    entitlements?: EntitlementInput[];
+}
+/** A price in a product edit: carry `id` to update that row in place, omit it to add. */
+type UpdatePriceInput = PriceInput & {
+    id?: string;
+};
+/** The result of migrating a plan's subscribers to another plan (ADR-0015). */
+interface MigrationResult {
+    /** How many subscriptions were moved to the target plan. */
+    migrated: number;
+    /** Subscriptions that couldn't be moved, with the reason (wrong currency, not active, …). */
+    skipped: Array<{
+        subscriptionId: string;
+        reason: string;
+    }>;
+}
+/**
+ * Edit a product (ADR-0015): rename, archive, and/or replace its prices/entitlements
+ * in place. `prices`/`entitlements`, when given, reconcile the latest version's rows
+ * (existing subscribers re-price at their next renewal).
+ */
+interface UpdateProductInput {
+    name?: string;
+    archived?: boolean;
+    /** Replace the product's metadata map. */
+    metadata?: Record<string, string>;
+    prices?: UpdatePriceInput[];
+    entitlements?: EntitlementInput[];
+}
+interface Feature {
+    id: string;
+    slug: string;
+    name: string;
+    kind: FeatureKind;
+    /** Meter config for metered features (ADR-0011); null/absent for boolean. */
+    meter?: MeterConfig | null;
+}
+/**
+ * An in-place edit to a feature. `name` is always allowed; `meter` re-configures a
+ * metered feature's aggregation — but the server refuses a meter change once usage has
+ * been recorded (it would rewrite billed history). At least one field must be present.
+ */
+interface UpdateFeatureInput {
+    name?: string;
+    meter?: MeterConfig;
+}
+/** A usage-monitoring rule: a `threshold` Alert (notifies) or a `cap` (blocks). */
+type UsageAlertKind = "threshold" | "cap";
+/** How an alert threshold figure reads: absolute usage, percent used, or percent remaining. */
+type UsageAlertMetric = "absolute" | "percent_used" | "percent_remaining";
+/** A configured Alert / Spend cap on a metered feature (Phase C). */
+interface UsageAlert {
+    id: string;
+    kind: UsageAlertKind;
+    metric: UsageAlertMetric;
+    /** Threshold figures (units, or a percentage). One for a cap; one+ for an Alert. */
+    thresholds: number[];
+    /** Threshold Alerts: re-fire every N past the highest threshold; else null. */
+    recurringStep: number | null;
+    /** Threshold Alerts: also email the Customer (webhook always fires). */
+    notifyCustomer: boolean;
+    enabled: boolean;
+}
+interface CreateUsageAlertInput {
+    kind: UsageAlertKind;
+    metric: UsageAlertMetric;
+    thresholds: number[];
+    /** Threshold Alerts only: re-fire every N past the highest threshold. */
+    recurringStep?: number;
+    /** Threshold Alerts only: also email the Customer. */
+    notifyCustomer?: boolean;
+}
+interface TrackResult {
+    ok: true;
+    /** True when the idempotency key was already seen — the call was a no-op. */
+    deduplicated: boolean;
+    /** Remaining balance for the feature; `null` if unlimited. */
+    balance: number | null;
+}
+interface EntitlementView {
+    feature: string;
+    kind: FeatureKind;
+    allowed: boolean;
+    balance: number | null;
+}
+type ProductPrice = ProductPriceResponse;
+type ProductEntitlement = ProductEntitlementResponse;
+type Product = ProductResponse;
+type Subscription = SubscriptionResponse;
+/** A single fetched subscription (`subscriptions.get`) - {@link Subscription} plus the stable `customerExternalId` + `productSlug`. */
+type SubscriptionDetail = SubscriptionDetailResponse;
+/** A subscription line item — the base plan or an attached add-on (Phase D2). */
+type SubscriptionItem = SubscriptionItemResponse;
+interface CreateSubscriptionInput {
+    customerId: string;
+    /** The product slug to subscribe to. */
+    productId: string;
+    redirectionUrl?: string;
+    /** Optional coupon code to apply to the subscription. */
+    couponCode?: string;
+    /** Free-trial length in days (starts `trialing`, no charge until trial end). */
+    trialDays?: number;
+    /** For a trial, collect a card up front via tokenization (default true). */
+    collectCard?: boolean;
+    /** Units of the base price to bill (e.g. seats for a `licensed` plan); default 1. */
+    quantity?: number;
+    /** Limited term: total billing cycles before the subscription ends; omit = open-ended. */
+    cycles?: number;
+    /**
+     * The billing currency (Phase F, ADR-0013). Required only when the product has
+     * recurring prices in more than one currency; inferred when there's a single one.
+     */
+    currency?: string;
+}
+type CouponKind = "percent" | "fixed";
+type CouponDuration = "once" | "repeating" | "forever";
+interface CreateCouponInput {
+    code?: string;
+    kind: CouponKind;
+    /** percent: basis points (1% = 100 bps). fixed: minor units. */
+    value: number;
+    currency?: string;
+    duration: CouponDuration;
+    durationCycles?: number;
+    maxRedemptions?: number;
+    /** ISO-8601 timestamp. */
+    expiresAt?: string;
+    /** Product slugs the coupon is restricted to. */
+    productRestrictions?: string[];
+}
+interface Coupon {
+    id: string;
+    code: string | null;
+    kind: CouponKind;
+    value: number;
+    currency: string | null;
+    duration: CouponDuration;
+    durationCycles: number | null;
+    maxRedemptions: number | null;
+    redeemedCount: number;
+    expiresAt: string | null;
+    /** Set when an operator deactivated the coupon (it can no longer be applied). */
+    deactivatedAt?: string | null;
+    productRestrictions?: string[] | null;
+}
+type ActivatedSubscriptionResult = ActivatedSubscriptionResponse;
+type PendingSubscriptionCheckoutResult = PendingSubscriptionCheckoutResponse;
+type CreateSubscriptionResult = CreateSubscriptionResponse;
+/**
+ * Why a succeeded charge could not be applied to the invoice it paid, so its money awaits an
+ * Operator refund: `duplicate_payment` - another payment had already paid the invoice;
+ * `invoice_closed` - the invoice was voided or written off before this payment arrived.
+ */
+type UnappliedPaymentReason = "duplicate_payment" | "invoice_closed";
+interface Charge {
+    id: string;
+    status: ChargeStatus;
+    customerId: string;
+    customerExternalId: string;
+    invoiceId: string | null;
+    kind: "customer_present" | "mit";
+    subtotal: number;
+    tax: number;
+    total: number;
+    taxRateBps: number | null;
+    taxBehavior: "exclusive" | "inclusive" | null;
+    items: {
+        name: string;
+        amount: number;
+        quantity: number;
+        description?: string;
+    }[];
+    /** Backward-compatible alias of `total`, the amount sent to the provider. */
+    amount: number;
+    currency: string;
+    checkoutUrl: string | null;
+    specialReference: string;
+    providerTransactionId: string | null;
+    errorMessage: string | null;
+    /** Provider-reported dispute/chargeback (PRD-08), read-only. Null unless disputed. */
+    disputedAt: string | null;
+    disputeReason: string | null;
+    disputeId: string | null;
+    disputeAmount: number | null;
+    disputeState: "open" | "won" | "lost" | null;
+    /** Set when this payment could not be applied to its invoice; null otherwise. */
+    unappliedReason: UnappliedPaymentReason | null;
+    createdAt: string;
+}
+interface CreateChargeInput {
+    customerId: string;
+    /** Amount in minor units (e.g. piasters). */
+    amount: number;
+    currency: string;
+    /** Tax rate in basis points. When set, `taxBehavior` defaults to `exclusive`. */
+    taxRateBps?: number;
+    /** Whether `amount` excludes or includes tax. Requires `taxRateBps`. */
+    taxBehavior?: "exclusive" | "inclusive";
+    items?: {
+        name: string;
+        amount: number;
+        quantity: number;
+        description?: string;
+    }[];
+    /** Restrict the offered methods; omit to offer every method the merchant has configured. */
+    methods?: ("card" | "wallet" | "sympl" | "applepay")[];
+    saveCard?: boolean;
+    redirectionUrl?: string;
+}
+/** A standalone off-session charge against the customer's current saved card. */
+interface CreateMerchantInitiatedChargeInput {
+    customerId: string;
+    paymentMethodId: string;
+    amount: number;
+    currency: string;
+    items: {
+        name: string;
+        amount: number;
+        quantity: number;
+        description?: string;
+    }[];
+    taxRateBps?: number;
+    taxBehavior?: "exclusive" | "inclusive";
+}
+
+export type { AttachResult as A, BillowOptions as B, CreateProductInput as C, PriceInput as D, EntitlementView as E, FeatureKind as F, ProductEntitlement as G, ProductPrice as H, IdempotentRequestOptions as I, SubscriptionDetail as J, SubscriptionItem as K, UpdatePriceInput as L, MeterConfig as M, UsageAlertKind as N, UsageAlertMetric as O, Product as P, UsageModel as Q, RequestOptions as R, Subscription as S, TrackResult as T, UnappliedPaymentReason as U, UsageTier as V, CreateCouponInput as a, CheckResult as b, TaxBehavior as c, Customer as d, CreateChargeInput as e, Charge as f, CreateMerchantInitiatedChargeInput as g, CallOptions as h, UpdateProductInput as i, MigrationResult as j, CreateSubscriptionInput as k, Coupon as l, Feature as m, UpdateFeatureInput as n, UsageAlert as o, CreateUsageAlertInput as p, ActivatedSubscriptionResult as q, BillingInterval as r, CouponDuration as s, CouponKind as t, CreateSubscriptionResult as u, EntitlementInput as v, MeterAggregation as w, MeterFilter as x, MeterRoundingMode as y, PendingSubscriptionCheckoutResult as z };