@openrails/billing-ui 0.245.0 → 0.246.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## Low-balance lines
+
+- `getAccount()` answers `low_balance_lines`: the line each balance is judged
+  at, with its `source`. `setLowBalanceLine()` sets the customer's own.
+
 ## Embeddable billing administration
 
 - `@openrails/billing-ui/admin` exports `BillingAdmin`, `BillingCustomerSummary`,

package/dist/client/client.d.ts

@@ -1,5 +1,5 @@
 import { BillingError } from './errors';
-import { Account, CustomerConfig, CustomerLink, NetworkLinkChallenge, PublicConfig, CurrencyScales, ListPage, NewCard, CardCaptureReference, NextAction, Cart, Order, OrderPaymentInput, Page, Payment, PaymentMethod, Product, Subscription, SubscriptionChange, SubscriptionChangePreview, Usage } from './types';
+import { Account, CustomerConfig, CustomerLink, LowBalanceLine, NetworkLinkChallenge, PublicConfig, CurrencyScales, ListPage, NewCard, CardCaptureReference, NextAction, Cart, Order, OrderPaymentInput, Page, Payment, PaymentMethod, Product, Subscription, SubscriptionChange, SubscriptionChangePreview, Usage } from './types';
 export interface BillingClientOptions {
     /** OpenRails embedded mount. Default "/billing/v1". */
     baseUrl?: string;
@@ -228,9 +228,19 @@ export declare function createBillingClient(options?: BillingClientOptions): {
     }): Promise<ListPage<Payment>>;
     /**
      * The customer's summary: balance and amount owed per currency, the card
-     * that pays each currency, and unread notices.
+     * that pays each currency, and the low-balance line of each balance.
      */
     getAccount(signal?: AbortSignal): Promise<Account>;
+    /**
+     * Sets the customer's own low-balance line in one currency and answers
+     * the line its balance is judged at. `null` inherits the merchant's; 0
+     * turns that part off.
+     */
+    setLowBalanceLine(input: {
+        currency: string;
+        amount: string | null;
+        runwayHours: number | null;
+    }): Promise<LowBalanceLine>;
     /**
      * A page of the customer's usage: its groups by total amount, largest
      * first. Pass the answer's `next_cursor` as `cursor` for the next page.

package/dist/client/generated/error-codes.d.ts

@@ -1,4 +1,4 @@
-export type OpenRailsErrorCode = "admission_captured" | "admission_not_found" | "already_owned" | "application_required" | "as_of_required" | "authentication_required" | "authentication_unavailable" | "authorization_unavailable" | "billing_archive_integrity" | "billing_archive_invalid_artifact" | "billing_archive_merchant_mismatch" | "billing_archive_not_empty" | "billing_archive_unavailable" | "billing_archive_unsupported_state" | "billing_policy_not_found" | "cancel_unsupported_on_rail" | "captcha_invalid" | "captcha_required" | "card_attempts_blocked" | "card_declined" | "card_not_saved" | "card_requires_https" | "catalog_benefit_overlap" | "catalog_revision_conflict" | "checkout_attempt_closed" | "checkout_attempt_expired" | "checkout_attempts_exhausted" | "checkout_embed_origins_required" | "checkout_expired" | "checkout_not_found" | "credential_expired" | "credential_revoked" | "credit_grant_held" | "credit_grant_not_found" | "credit_grant_unavailable" | "csrf_origin_denied" | "currency_unsupported" | "custodian_capture_unavailable" | "customer_action_required" | "customer_email_required" | "customer_issuer_mismatch" | "customer_not_found" | "customer_payment_unsupported" | "customer_session_required" | "dashboard_invalid" | "database_busy" | "default_payment_method_invalid" | "default_payment_method_required" | "default_rate_card_not_found" | "finding_action_failed" | "finding_not_actionable" | "hold_not_found" | "host_event_not_found" | "host_principal_invalid" | "hosted_checkout_unavailable" | "idempotency_key_in_use" | "idempotency_key_required" | "idempotency_key_reused" | "insufficient_credits" | "insufficient_funds" | "internal_error" | "invalid_cursor" | "invalid_customer_id" | "invalid_host_event_request" | "invalid_param" | "invalid_payment_method" | "invalid_psp_reference" | "invalid_query" | "invalid_request_body" | "invalid_settlement_status_request" | "invoker_scoped_principal" | "merchant_config_read_only" | "merchant_mismatch" | "merchant_unresolved" | "meter_in_use" | "meter_rate_card_conflict" | "method_not_allowed" | "metrics_query_invalid" | "model_unavailable" | "network_account_linked" | "network_link_challenge_invalid" | "network_link_conflict" | "network_link_in_use" | "network_terms_required" | "order_action_not_allowed" | "order_has_recurring_line" | "order_line_unavailable" | "order_not_cancelable" | "order_not_payable" | "order_payment_in_progress" | "order_total_changed" | "payment_duplicate_refused" | "payment_exceeds_due" | "payment_failed" | "payment_idempotency_conflict" | "payment_in_progress" | "payment_method_delete_failed" | "payment_method_delete_unsupported" | "payment_method_not_psp_vaulted" | "payment_method_not_usable" | "payment_method_psp_mismatch" | "payment_method_required" | "payment_method_same_vault" | "payment_method_stale" | "payment_method_update_failed" | "payment_method_update_unsupported" | "payment_not_found" | "payment_not_refundable" | "payment_not_retryable" | "payment_option_unavailable" | "payment_provider_rejected" | "permission_required" | "price_change_currency_mismatch" | "price_change_target_archived" | "price_increase_notice_too_short" | "price_key_cadence_conflict" | "price_key_not_found" | "price_migration_not_found" | "price_not_found" | "price_not_sellable" | "product_in_use" | "product_not_found" | "product_tier_group_conflict" | "product_tier_group_in_use" | "provider_cancel_held" | "provider_outcome_unknown" | "psp_claim_requires_proof" | "psp_credentials_rejected" | "psp_exists" | "psp_key_taken" | "psp_last_active" | "psp_not_found" | "purchase_review_resolved" | "quantity_not_allowed" | "rate_card_product_not_found" | "rate_limit_exceeded" | "rebill_terms_committed" | "refund_failed" | "refund_rail_unavailable" | "refund_unsupported" | "request_body_too_large" | "resource_access_denied" | "resource_conflict" | "resource_not_found" | "revision_mismatch" | "route_not_found" | "running_charge_not_found" | "scheduled_change_exists" | "service_credential_customer_scope_denied" | "service_unavailable" | "solana_rpc_unavailable" | "solana_transaction_refused" | "step_up_required" | "step_up_unavailable" | "stored_credential_required" | "subscription_change_already_scheduled" | "subscription_change_cadence_unsupported" | "subscription_change_credit_exceeds_price" | "subscription_change_cycle_unknown" | "subscription_change_idempotency_conflict" | "subscription_change_idempotency_key_required" | "subscription_change_in_flight" | "subscription_change_period_unknown" | "subscription_change_provider_conflict" | "subscription_change_refused" | "subscription_change_renewal_due" | "subscription_change_requires_linked_plan" | "subscription_change_target_inactive" | "subscription_change_unsupported_on_rail" | "subscription_not_active" | "subscription_not_found" | "subscription_paid_through" | "subscription_resumable" | "trial_unsupported_on_rail" | "unknown_field" | "unsupported_media_type" | "usage_meter_invalid" | "usage_meter_not_found" | "usage_not_priced" | "usage_rate_card_invalid" | "webhook_account_mismatch" | "webhook_invalid";
+export type OpenRailsErrorCode = "admission_captured" | "admission_not_found" | "already_owned" | "application_required" | "as_of_required" | "authentication_required" | "authentication_unavailable" | "authorization_unavailable" | "billing_archive_integrity" | "billing_archive_invalid_artifact" | "billing_archive_merchant_mismatch" | "billing_archive_not_empty" | "billing_archive_unavailable" | "billing_archive_unsupported_state" | "billing_policy_not_found" | "cancel_unsupported_on_rail" | "captcha_invalid" | "captcha_required" | "card_attempts_blocked" | "card_declined" | "card_not_saved" | "card_requires_https" | "catalog_benefit_overlap" | "catalog_revision_conflict" | "checkout_attempt_closed" | "checkout_attempt_expired" | "checkout_attempts_exhausted" | "checkout_embed_origins_required" | "checkout_expired" | "checkout_not_found" | "credential_expired" | "credential_revoked" | "credit_grant_held" | "credit_grant_not_found" | "credit_grant_unavailable" | "csrf_origin_denied" | "currency_unsupported" | "custodian_capture_unavailable" | "customer_action_required" | "customer_email_required" | "customer_issuer_mismatch" | "customer_not_found" | "customer_payment_unsupported" | "customer_session_required" | "dashboard_invalid" | "database_busy" | "default_payment_method_invalid" | "default_payment_method_required" | "default_rate_card_not_found" | "destructive_actions_held" | "finding_action_failed" | "finding_not_actionable" | "finding_requires_merchant_config" | "hold_not_found" | "host_event_not_found" | "host_principal_invalid" | "hosted_checkout_unavailable" | "idempotency_key_in_use" | "idempotency_key_required" | "idempotency_key_reused" | "insufficient_credits" | "insufficient_funds" | "internal_error" | "invalid_cursor" | "invalid_customer_id" | "invalid_host_event_request" | "invalid_param" | "invalid_payment_method" | "invalid_psp_reference" | "invalid_query" | "invalid_request_body" | "invalid_settlement_status_request" | "invoker_scoped_principal" | "merchant_config_read_only" | "merchant_mismatch" | "merchant_unresolved" | "meter_in_use" | "meter_rate_card_conflict" | "method_not_allowed" | "metrics_query_invalid" | "model_unavailable" | "network_account_linked" | "network_link_challenge_invalid" | "network_link_conflict" | "network_link_in_use" | "network_terms_required" | "order_action_not_allowed" | "order_has_recurring_line" | "order_line_unavailable" | "order_not_cancelable" | "order_not_payable" | "order_payment_in_progress" | "order_total_changed" | "payment_duplicate_refused" | "payment_exceeds_due" | "payment_failed" | "payment_idempotency_conflict" | "payment_in_progress" | "payment_method_delete_failed" | "payment_method_delete_unsupported" | "payment_method_not_psp_vaulted" | "payment_method_not_usable" | "payment_method_psp_mismatch" | "payment_method_required" | "payment_method_same_vault" | "payment_method_stale" | "payment_method_update_failed" | "payment_method_update_unsupported" | "payment_not_found" | "payment_not_refundable" | "payment_not_retryable" | "payment_option_unavailable" | "payment_provider_rejected" | "permission_required" | "price_change_currency_mismatch" | "price_change_target_archived" | "price_increase_notice_too_short" | "price_key_cadence_conflict" | "price_key_not_found" | "price_migration_not_found" | "price_not_found" | "price_not_sellable" | "product_in_use" | "product_not_found" | "product_tier_group_conflict" | "product_tier_group_in_use" | "provider_cancel_held" | "provider_outcome_unknown" | "provider_writes_held" | "psp_claim_requires_proof" | "psp_credentials_rejected" | "psp_exists" | "psp_key_taken" | "psp_last_active" | "psp_not_found" | "purchase_review_resolved" | "quantity_not_allowed" | "rate_card_product_not_found" | "rate_limit_exceeded" | "rebill_terms_committed" | "refund_failed" | "refund_rail_unavailable" | "refund_unsupported" | "request_body_too_large" | "resource_access_denied" | "resource_conflict" | "resource_not_found" | "revision_mismatch" | "route_not_found" | "running_charge_not_found" | "scheduled_change_exists" | "service_credential_customer_scope_denied" | "service_unavailable" | "solana_rpc_unavailable" | "solana_transaction_refused" | "step_up_required" | "step_up_unavailable" | "stored_credential_required" | "subscription_change_already_scheduled" | "subscription_change_cadence_unsupported" | "subscription_change_credit_exceeds_price" | "subscription_change_cycle_unknown" | "subscription_change_idempotency_conflict" | "subscription_change_idempotency_key_required" | "subscription_change_in_flight" | "subscription_change_period_unknown" | "subscription_change_provider_conflict" | "subscription_change_refused" | "subscription_change_renewal_due" | "subscription_change_requires_linked_plan" | "subscription_change_target_inactive" | "subscription_change_unsupported_on_rail" | "subscription_not_active" | "subscription_not_found" | "subscription_paid_through" | "subscription_resumable" | "trial_unsupported_on_rail" | "unknown_field" | "unsupported_media_type" | "usage_meter_invalid" | "usage_meter_not_found" | "usage_not_priced" | "usage_rate_card_invalid" | "webhook_account_mismatch" | "webhook_invalid";
 export type OpenRailsErrorType = "api_error" | "authentication_error" | "authorization_error" | "card_error" | "invalid_request_error" | "rate_limit_error";
 export declare const OPENRAILS_ERROR_CODES: Readonly<Record<OpenRailsErrorCode, {
     status: number;

package/dist/client/generated/routes.d.ts

@@ -1231,6 +1231,20 @@ export declare const OPENRAILS_ROUTES: readonly [{
     };
     readonly errors: readonly [];
     readonly errorSets: readonly ["tier:customer"];
+}, {
+    readonly method: "PUT";
+    readonly path: "/v1/me/low-balance-lines/{currency}";
+    readonly group: "customer";
+    readonly auth: "customer";
+    readonly permission: null;
+    readonly sensitive: false;
+    readonly mountedWhen: null;
+    readonly request: "SetLowBalanceLineParams";
+    readonly responses: {
+        readonly 200: "EffectiveLowBalanceLine";
+    };
+    readonly errors: readonly ["currency_unsupported", "invalid_param"];
+    readonly errorSets: readonly ["tier:customer", "request"];
 }, {
     readonly method: "GET";
     readonly path: "/v1/me/balance/transactions";
@@ -2279,7 +2293,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly responses: {
         readonly 200: "FindingResolution";
     };
-    readonly errors: readonly ["finding_action_failed", "finding_not_actionable", "idempotency_key_reused", "invalid_param", "payment_not_found", "payment_not_refundable", "provider_cancel_held", "rebill_terms_committed", "refund_failed", "refund_rail_unavailable", "refund_unsupported", "resource_conflict", "resource_not_found", "service_unavailable"];
+    readonly errors: readonly ["finding_action_failed", "finding_not_actionable", "finding_requires_merchant_config", "idempotency_key_reused", "invalid_param", "payment_not_found", "payment_not_refundable", "provider_cancel_held", "rebill_terms_committed", "refund_failed", "refund_rail_unavailable", "refund_unsupported", "resource_conflict", "resource_not_found", "service_unavailable"];
     readonly errorSets: readonly ["tier:merchant", "request"];
 }, {
     readonly method: "GET";

package/dist/client/generated/wire.d.ts

@@ -171,8 +171,19 @@ export type BalanceHostEvent = {
     available_amount: string;
     owed_amount: string;
     accrual_rate_per_hour: string;
+    usage_rate_per_hour: string;
+    low_balance_amount: string;
     as_of: string;
-    depletes_at: string;
+    depletes_at: string | null;
+    runway_ends_at: string | null;
+};
+export type BalanceNoticeAmount = {
+    currency: string;
+    amount: string;
+};
+export type BalanceNoticeSettings = {
+    runway_hours?: number;
+    low_amounts?: BalanceNoticeAmount[];
 };
 export type BalanceTransaction = {
     id: string;
@@ -366,6 +377,24 @@ export type CatalogFieldConflict = {
     set_by: string;
     set_at: string;
 };
+export type ChangeBasis = {
+    row_version: number | null;
+    absent_rail_id: string | null;
+    card_version_id: string | null;
+};
+export type ChangeEffects = {
+    ends_access: boolean;
+    moves_money: boolean;
+    provider_write: boolean;
+};
+export type ChangeEvidence = {
+    read: string;
+    provider: Record<string, unknown> | null;
+};
+export type ChangeSubject = {
+    type: string;
+    id: string;
+};
 export type ChangeSubscriptionParams = {
     price_id?: string;
     quantity?: number;
@@ -570,6 +599,7 @@ export type CustomerAccount = {
     id: string;
     balances: Balance[];
     default_payment_methods: DefaultPaymentMethod[];
+    low_balance_lines: EffectiveLowBalanceLine[];
 };
 export type CustomerAmount = {
     min_amount: string;
@@ -625,6 +655,7 @@ export type CustomerNetworkHostEvent = {
 export type CustomerSettings = {
     credit_limits: CreditLimit[];
     trust_levels: TrustLevel[];
+    low_balance_lines: LowBalanceLine[];
     billing_policy: string | null;
     invoice_profile: InvoiceProfile | null;
 };
@@ -738,6 +769,12 @@ export type DunningTier = {
     max_cycle_hours?: number;
     retry_after_hours?: number[];
 };
+export type EffectiveLowBalanceLine = {
+    currency: string;
+    amount: string;
+    runway_hours: number;
+    source: "customer" | "default" | "merchant";
+};
 export type EntitlementChange = {
     product_id: string;
     product_key: string;
@@ -792,9 +829,23 @@ export type Finding = {
     resolution: string | null;
     resolved_by: string | null;
     operator_notes: string | null;
+    source: "pull" | "verification" | null;
+    change: FindingChange | null;
+    approval_run_id: string | null;
     created_at: string;
     updated_at: string;
 };
+export type FindingChange = {
+    kind: "adopt_subscription" | "cancel_provider_schedule" | "cancel_subscription" | "collect_skipped_renewal" | "create_subscription" | "record_charge" | "record_refund" | "refund_charge_after_cancel" | "revoke_access" | "update_card";
+    subject: ChangeSubject;
+    customer_id: string | null;
+    from: Record<string, unknown> | null;
+    to: Record<string, unknown> | null;
+    effects: ChangeEffects;
+    basis: ChangeBasis;
+    observed_at: string;
+    evidence: ChangeEvidence;
+};
 export type FindingRecommendation = {
     action: string;
     params: Record<string, unknown> | null;
@@ -843,6 +894,11 @@ export type InvoiceProfile = {
     billing_contacts: InvoiceContact[];
     memo: string;
 };
+export type LowBalanceLine = {
+    currency: string;
+    amount: string | null;
+    runway_hours: number | null;
+};
 export type Mandate = {
     id: string;
     customer_id: string;
@@ -906,6 +962,7 @@ export type MerchantSettings = {
     checkout_routing?: CheckoutRoutingRule[];
     dunning_policy?: DunningPolicy;
     checkout?: MerchantCheckoutSettings;
+    balance_notices?: BalanceNoticeSettings;
     billing_policies?: BillingPolicy[];
     billing_policy_bindings?: BillingPolicyBinding[];
     delegated_invoker_wasted_spend_limits?: BudgetWindow[];
@@ -1670,7 +1727,6 @@ export type RunningCharge = {
     posted_amount: string;
     as_of: string;
     overdraft_amount: string;
-    low_balance_amount: string;
     resource: string | null;
     created_at: string;
     updated_at: string;
@@ -1695,6 +1751,10 @@ export type SetDashboardParams = {
 export type SetDefaultPaymentMethodParams = {
     payment_method_id?: string;
 };
+export type SetLowBalanceLineParams = {
+    amount?: string | null;
+    runway_hours?: number | null;
+};
 export type SetMeterParams = {
     event_type?: string;
     value_property?: string;
@@ -1740,7 +1800,6 @@ export type StartRunningChargeParams = {
     started_at?: string;
     minimum_amount?: string;
     overdraft_amount?: string;
-    low_balance_amount?: string;
     resource?: string;
 };
 export type StopRunningChargeParams = {
@@ -1853,6 +1912,7 @@ export type UpdateAlertWebhookParams = {
 export type UpdateCustomerParams = {
     credit_limits?: CreditLimit[];
     trust_levels?: TrustLevel[];
+    low_balance_lines?: LowBalanceLine[];
     billing_policy?: string | null;
     invoice_profile?: InvoiceProfile | null;
 };

package/dist/client/index.d.ts

@@ -1,5 +1,5 @@
 export { CANCEL_REASON_MAX, CANCEL_REASON_MIN, createBillingClient, isWalletAction, isWalletRejection, RETRY_BUDGET_MS, signWalletAction, WalletRejectedError, type BillingClient, type BillingClientOptions, type ListOptions, type OrderResult, type ProductListOptions, type SendSolanaTransaction, type SubscriptionChangeInput, type UsageOptions, } from './client';
 export { redeemAssertion, tokenSource, type RedeemAssertionOptions, type TokenResponse, type TokenSource, type TokenSourceOptions, } from './token-source';
 export { BillingError, isBillingError, isServerError, readBillingError, toBillingError, type BillingErrorBody, } from './errors';
-export type { Account, Balance, CaptchaConfig, CardSummary, Cart, Currency, CurrencyScales, CustomerConfig, CustomerLink, PaymentConfig, PaymentFailure, PublicConfig, PublicMerchant, ListPage, NetworkLinkChallenge, NewCard, CardCaptureReference, NextAction, Order, OrderLine, OrderLineRefusal, OrderPaymentInput, OrderPreviewLine, Page, Payment, PaymentMethod, PaymentRecovery, Price, Product, Subscription, SubscriptionDunning, SubscriptionProduct, SubscriptionStatus, SubscriptionChange, SubscriptionChangePreview, Usage, UsageRow, } from './types';
+export type { Account, Balance, CaptchaConfig, CardSummary, Cart, Currency, CurrencyScales, CustomerConfig, CustomerLink, PaymentConfig, PaymentFailure, PublicConfig, PublicMerchant, ListPage, LowBalanceLine, NetworkLinkChallenge, NewCard, CardCaptureReference, NextAction, Order, OrderLine, OrderLineRefusal, OrderPaymentInput, OrderPreviewLine, Page, Payment, PaymentMethod, PaymentRecovery, Price, Product, Subscription, SubscriptionDunning, SubscriptionProduct, SubscriptionStatus, SubscriptionChange, SubscriptionChangePreview, Usage, UsageRow, } from './types';
 export { amountToDecimal, decimalToAmount, formatAmount, type Amount, } from '../lib/money';

package/dist/client/types.d.ts

@@ -694,9 +694,25 @@ export declare const balanceSchema: z.ZodObject<{
     depletes_at: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type Balance = z.infer<typeof balanceSchema>;
+/**
+ * The low-balance line a balance is judged at: the customer is told when what
+ * it may spend is under the larger of `amount` and its burn rate times
+ * `runway_hours`. `source` is `customer`, `merchant` or `default`.
+ */
+export declare const lowBalanceLineSchema: z.ZodObject<{
+    currency: z.ZodString;
+    amount: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    runway_hours: z.ZodNumber;
+    source: z.ZodEnum<{
+        customer: "customer";
+        default: "default";
+        merchant: "merchant";
+    }>;
+}, z.core.$strip>;
+export type LowBalanceLine = z.infer<typeof lowBalanceLineSchema>;
 /**
  * The signed-in customer's summary (`GET /me`): money per currency, the
- * default card of each currency, and how many notices are unread.
+ * default card of each currency, and the low-balance line of each balance.
  */
 export declare const accountSchema: z.ZodObject<{
     id: z.ZodString;
@@ -716,6 +732,16 @@ export declare const accountSchema: z.ZodObject<{
         currency: z.ZodString;
         payment_method_id: z.ZodString;
     }, z.core.$strip>>;
+    low_balance_lines: z.ZodArray<z.ZodObject<{
+        currency: z.ZodString;
+        amount: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+        runway_hours: z.ZodNumber;
+        source: z.ZodEnum<{
+            customer: "customer";
+            default: "default";
+            merchant: "merchant";
+        }>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Account = z.infer<typeof accountSchema>;
 /**