@openrails/billing-ui 0.238.0 → 0.239.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## Public products and staff route groups
+
+- Breaking: public `listProducts()` now reads `GET /products`. Catalog
+  management uses `/catalog`, merchant configuration `/merchant`, and metrics
+  `/metrics`; customer support stays under `/admin`.
+
+## Provider operations removed
+
+- Breaking: `OpenRailsErrorCode` and `OPENRAILS_ERROR_CODES` lose
+  `provider_operation_not_found`, `provider_operation_conflict`,
+  `provider_operation_not_open`, `provider_operation_has_billing_evidence`,
+  `provider_operation_refused`, `provider_operation_not_refused` and
+  `provider_billing_observation_conflict`.
+
+## Usage report
+
+- `getUsage({ currency, groupBy, from, to, limit, cursor })` reads a page of
+  the customer's usage (`GET /me/usage`): `Usage`, its `rows` by total
+  amount, largest first, and `next_cursor` (null on the last page). A page
+  holds at most 1,000 groups (default 100); a cursor reads only the report it
+  came from.
+
 ## Public reads name their merchant; token source
 
 - Breaking: `listProducts({ merchant, keys })`, `useProducts({ merchant, keys

package/README.md

@@ -180,7 +180,7 @@ no bearer.
 
 | Call                                                                                                | Route                                                           |
 | --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| `listProducts({ merchant, keys })`: the products `merchant` (its id) has on sale named by `keys` (1 to 100 product keys), each with its prices, in one page; `useProducts` reads the same | `GET /catalog/products` |
+| `listProducts({ merchant, keys })`: the products `merchant` (its id) has on sale named by `keys` (1 to 100 product keys), each with its prices, in one page; `useProducts` reads the same | `GET /products` |
 | `getConfig()` (capabilities, `currencies`, `captcha`; `client.currencies` is the pinned registry) | `GET /config` |
 | `getCustomerConfig()` (the customer's merchant: `payment` with PSPs, `solana.network` and tokens, and `merchant`, its name) | `GET /me/config` |
 | `previewSubscriptionChange(id, { priceId?, quantity? })`                                            | `POST /me/subscriptions/{id}/change/preview`                    |
@@ -288,3 +288,7 @@ pnpm contract:check  # fail if a generated contract file is stale
 `BILLING_UI_SCREENSHOTS=<dir>` to capture light, dark and mobile screenshots.
 Card deletion calls NMI, which the harness has no credentials for; jsdom tests
 cover it.
+
+## License
+
+MIT; see [LICENSE](LICENSE). Only this package is MIT: the rest of the OpenRails repository is under the Functional Source License (FSL-1.1-ALv2).

package/dist/client/client.d.ts

@@ -1,5 +1,5 @@
 import { BillingError } from './errors';
-import { Account, CustomerConfig, CustomerLink, NetworkLinkChallenge, PublicConfig, CurrencyScales, ListPage, NewCard, NextAction, Cart, Order, OrderPaymentInput, Page, Payment, PaymentMethod, Product, Subscription, SubscriptionChange, SubscriptionChangePreview } from './types';
+import { Account, CustomerConfig, CustomerLink, NetworkLinkChallenge, PublicConfig, CurrencyScales, ListPage, NewCard, 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;
@@ -53,6 +53,18 @@ export interface CursorOptions {
     cursor?: string | null;
     signal?: AbortSignal;
 }
+/**
+ * A page of the customer's usage report in `currency`, grouped by `groupBy`
+ * (event type by default). `from` and `to` are RFC 3339 or a date; left out,
+ * the month before now, or with `cursor` the window of the page it came from.
+ * `limit` is at most 1,000 groups (default 100).
+ */
+export interface UsageOptions extends CursorOptions {
+    currency: string;
+    groupBy?: "event_type" | "resource" | "invoker";
+    from?: string;
+    to?: string;
+}
 /**
  * Signs and submits a base64 transaction with the customer's wallet and
  * returns its signature. Throw `WalletRejectedError` when the user declines.
@@ -212,6 +224,11 @@ export declare function createBillingClient(options?: BillingClientOptions): {
      * that pays each currency, and unread notices.
      */
     getAccount(signal?: AbortSignal): Promise<Account>;
+    /**
+     * 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.
+     */
+    getUsage(opts: UsageOptions): Promise<Usage>;
     /**
      * The products `merchant` has on sale named by `keys`, each with its
      * current prices: a public read, the same signed in or out. No keys

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

@@ -1,4 +1,4 @@
-export type OpenRailsErrorCode = "admission_captured" | "admission_not_found" | "allowance_meter_not_found" | "allowance_source_in_use" | "allowance_source_invalid" | "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_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" | "default_rate_card_required" | "finding_action_failed" | "finding_not_actionable" | "hold_not_found" | "host_event_not_found" | "host_principal_invalid" | "hosted_checkout_unavailable" | "idempotency_key_in_progress" | "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_binding_mismatch" | "merchant_config_read_only" | "merchant_directory_unavailable" | "merchant_not_found" | "merchant_selector_invalid" | "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_not_found" | "product_tier_group_conflict" | "product_tier_group_in_use" | "provider_billing_observation_conflict" | "provider_cancel_held" | "provider_operation_conflict" | "provider_operation_has_billing_evidence" | "provider_operation_not_found" | "provider_operation_not_open" | "provider_operation_not_refused" | "provider_operation_refused" | "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_currency_mismatch" | "rate_card_has_overrides" | "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_rate_card_invalid" | "webhook_account_mismatch" | "webhook_invalid" | "widget_generation_invalid";
+export type OpenRailsErrorCode = "admission_captured" | "admission_not_found" | "allowance_meter_not_found" | "allowance_source_in_use" | "allowance_source_invalid" | "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_progress" | "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_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_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_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

@@ -241,7 +241,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly errorSets: readonly ["tier:customer"];
 }, {
     readonly method: "GET";
-    readonly path: "/v1/catalog/products";
+    readonly path: "/v1/products";
     readonly group: "checkout";
     readonly auth: "public";
     readonly permission: null;
@@ -436,7 +436,7 @@ export declare const OPENRAILS_ROUTES: readonly [{
     readonly responses: {
         readonly 200: "Usage";
     };
-    readonly errors: readonly ["currency_unsupported"];
+    readonly errors: readonly ["currency_unsupported", "invalid_cursor"];
     readonly errorSets: readonly ["tier:customer", "request"];
 }, {
     readonly method: "GET";
@@ -551,6 +551,34 @@ export declare const OPENRAILS_ROUTES: readonly [{
     };
     readonly errors: readonly ["invalid_param", "resource_not_found", "route_not_found"];
     readonly errorSets: readonly ["tier:customer"];
+}, {
+    readonly method: "GET";
+    readonly path: "/v1/me/agreements";
+    readonly group: "customer";
+    readonly auth: "customer";
+    readonly permission: null;
+    readonly sensitive: false;
+    readonly mountedWhen: null;
+    readonly request: null;
+    readonly responses: {
+        readonly 200: "ListPage<Agreement>";
+    };
+    readonly errors: readonly ["invalid_cursor"];
+    readonly errorSets: readonly ["tier:customer", "request"];
+}, {
+    readonly method: "POST";
+    readonly path: "/v1/me/agreements/{id}/revoke";
+    readonly group: "customer";
+    readonly auth: "customer";
+    readonly permission: null;
+    readonly sensitive: false;
+    readonly mountedWhen: null;
+    readonly request: null;
+    readonly responses: {
+        readonly 200: "AgreementRevocation";
+    };
+    readonly errors: readonly ["cancel_unsupported_on_rail", "customer_action_required", "invalid_param", "payment_in_progress", "provider_cancel_held", "resource_not_found", "service_unavailable", "subscription_not_active"];
+    readonly errorSets: readonly ["tier:customer"];
 }, {
     readonly method: "GET";
     readonly path: "/v1/me/notifications";

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

@@ -2,6 +2,29 @@ export type ListPage<T> = {
     data: T[];
     next_cursor: string | null;
 };
+export type Agreement = {
+    id: string;
+    kind: "card_on_file" | "recurring" | "unscheduled";
+    status: "active" | "ended" | "requires_reconsent" | "revoked";
+    currency: string;
+    payment_method_id: string | null;
+    card: CardDetails | null;
+    subscription: AgreementSubscription | null;
+    accepted_at: string;
+    ended_at: string | null;
+};
+export type AgreementRevocation = {
+    agreement: Agreement;
+    subscription: Subscription | null;
+    usage_order: Order | null;
+};
+export type AgreementSubscription = {
+    id: string;
+    product: string;
+    amount: string;
+    billing_interval_hours: number | null;
+    next_charge_at: string | null;
+};
 export type Balance = {
     customer_id: string;
     currency: string;
@@ -689,6 +712,7 @@ export type Usage = {
     to: string;
     group_by: "event_type" | "invoker" | "resource";
     rows: UsageRow[];
+    next_cursor: string | null;
 };
 export type UsageRow = {
     key: string;

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, } from './client';
+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, NextAction, Order, OrderLine, OrderLineRefusal, OrderPaymentInput, OrderPreviewLine, Page, Payment, PaymentMethod, PaymentRecovery, Price, Product, Subscription, SubscriptionDunning, SubscriptionProduct, SubscriptionStatus, SubscriptionChange, SubscriptionChangePreview, } from './types';
+export type { Account, Balance, CaptchaConfig, CardSummary, Cart, Currency, CurrencyScales, CustomerConfig, CustomerLink, PaymentConfig, PaymentFailure, PublicConfig, PublicMerchant, ListPage, NetworkLinkChallenge, NewCard, 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

@@ -35,7 +35,7 @@ export declare const pspLinkStateSchema: z.ZodObject<{
     sync_status: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 /**
- * A catalog price, embedded in a product (`GET /catalog/products`): `unit_amount` of
+ * A catalog price, embedded in a product (`GET /products`): `unit_amount` of
  * `currency` for `access_duration_hours` of access (null: for good),
  * charging every `billing_interval_hours` (null: one-time).
  */
@@ -717,6 +717,37 @@ export declare const accountSchema: z.ZodObject<{
     unread_notifications: z.ZodNumber;
 }, z.core.$strip>;
 export type Account = z.infer<typeof accountSchema>;
+/**
+ * One group of a usage report: its events and their total `amount`.
+ * `dimensions` are the summed event dimensions when grouped by event type.
+ */
+export declare const usageRowSchema: z.ZodObject<{
+    key: z.ZodString;
+    event_count: z.ZodNumber;
+    amount: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    dimensions: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodNumber>>>;
+}, z.core.$strip>;
+export type UsageRow = z.infer<typeof usageRowSchema>;
+/**
+ * One page of the customer's usage in `currency` over [`from`, `to`): its
+ * groups by total amount, largest first, then by key. `next_cursor` reads the
+ * next page; null on the last.
+ */
+export declare const usageSchema: z.ZodObject<{
+    customer_id: z.ZodString;
+    currency: z.ZodString;
+    from: z.ZodString;
+    to: z.ZodString;
+    group_by: z.ZodString;
+    rows: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        event_count: z.ZodNumber;
+        amount: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+        dimensions: z.ZodOptional<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodNumber>>>;
+    }, z.core.$strip>>;
+    next_cursor: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | null, string | null | undefined>>;
+}, z.core.$strip>;
+export type Usage = z.infer<typeof usageSchema>;
 /** Currency code (upper case) to its native-unit scale. */
 export type CurrencyScales = Readonly<Record<string, number>>;
 export declare const currencySchema: z.ZodObject<{