@openrails/billing-ui 0.0.0-stage → 0.230.0

package/dist/types.d.ts

@@ -0,0 +1,191 @@
+import { z } from 'zod';
+export declare const amountSchema: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+export declare const unitDecimalsSchema: z.ZodNumber & z.ZodType<number, number, z.core.$ZodTypeInternals<number, number>>;
+export declare const checkoutSessionStatusSchema: z.ZodEnum<{
+    succeeded: "succeeded";
+    failed: "failed";
+    expired: "expired";
+    created: "created";
+    requires_action: "requires_action";
+    processing: "processing";
+    blocked: "blocked";
+    canceled: "canceled";
+}>;
+export type CheckoutSessionStatus = z.infer<typeof checkoutSessionStatusSchema>;
+export declare const paymentFailureSchema: z.ZodObject<{
+    reason: z.ZodString;
+    message: z.ZodString;
+    field: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type PaymentFailure = z.infer<typeof paymentFailureSchema>;
+export declare const checkoutOperationSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodString;
+}, z.core.$strip>;
+export declare const paymentRailOptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    rail: z.ZodString;
+    mode: z.ZodEnum<{
+        subscription: "subscription";
+        one_off: "one_off";
+    }>;
+    driver: z.ZodEnum<{
+        card: "card";
+        collect_js: "collect_js";
+        stripe_elements: "stripe_elements";
+        redirect: "redirect";
+        solana_pay: "solana_pay";
+    }>;
+    psp_key: z.ZodOptional<z.ZodString>;
+    public_config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export type PaymentRailOption = z.infer<typeof paymentRailOptionSchema>;
+export declare const savedPaymentMethodSchema: z.ZodObject<{
+    id: z.ZodString;
+    option_id: z.ZodString;
+    rail: z.ZodString;
+    brand: z.ZodOptional<z.ZodString>;
+    last_four: z.ZodOptional<z.ZodString>;
+    exp_month: z.ZodOptional<z.ZodNumber>;
+    exp_year: z.ZodOptional<z.ZodNumber>;
+    default: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type SavedPaymentMethod = z.infer<typeof savedPaymentMethodSchema>;
+export declare const checkoutLineItemSchema: z.ZodObject<{
+    label: z.ZodString;
+    sublabel: z.ZodOptional<z.ZodString>;
+    amount: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+}, z.core.$strip>;
+export type CheckoutLineItem = z.infer<typeof checkoutLineItemSchema>;
+export declare const checkoutPlanSchema: z.ZodObject<{
+    display_name: z.ZodString;
+    unit_amount: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    currency: z.ZodString;
+    unit_decimals: z.ZodNumber & z.ZodType<number, number, z.core.$ZodTypeInternals<number, number>>;
+    period_hours: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    automatically_renews: z.ZodBoolean;
+}, z.core.$strip>;
+export type CheckoutPlan = z.infer<typeof checkoutPlanSchema>;
+export declare const checkoutSessionSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodEnum<{
+        succeeded: "succeeded";
+        failed: "failed";
+        expired: "expired";
+        created: "created";
+        requires_action: "requires_action";
+        processing: "processing";
+        blocked: "blocked";
+        canceled: "canceled";
+    }>;
+    merchant: z.ZodObject<{
+        display_name: z.ZodString;
+    }, z.core.$strip>;
+    plan: z.ZodObject<{
+        display_name: z.ZodString;
+        unit_amount: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+        currency: z.ZodString;
+        unit_decimals: z.ZodNumber & z.ZodType<number, number, z.core.$ZodTypeInternals<number, number>>;
+        period_hours: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        automatically_renews: z.ZodBoolean;
+    }, z.core.$strip>;
+    line_items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        sublabel: z.ZodOptional<z.ZodString>;
+        amount: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    }, z.core.$strip>>>;
+    tax: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+    due_today: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+    rails: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        rail: z.ZodString;
+        mode: z.ZodEnum<{
+            subscription: "subscription";
+            one_off: "one_off";
+        }>;
+        driver: z.ZodEnum<{
+            card: "card";
+            collect_js: "collect_js";
+            stripe_elements: "stripe_elements";
+            redirect: "redirect";
+            solana_pay: "solana_pay";
+        }>;
+        psp_key: z.ZodOptional<z.ZodString>;
+        public_config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    saved_methods: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        option_id: z.ZodString;
+        rail: z.ZodString;
+        brand: z.ZodOptional<z.ZodString>;
+        last_four: z.ZodOptional<z.ZodString>;
+        exp_month: z.ZodOptional<z.ZodNumber>;
+        exp_year: z.ZodOptional<z.ZodNumber>;
+        default: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    transaction_url: z.ZodOptional<z.ZodString>;
+    payment_id: z.ZodOptional<z.ZodString>;
+    subscription_id: z.ZodOptional<z.ZodString>;
+    failure_message: z.ZodOptional<z.ZodString>;
+    failure: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        reason: z.ZodString;
+        message: z.ZodString;
+        field: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    operation: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodString;
+    }, z.core.$strip>>>;
+    success_url: z.ZodOptional<z.ZodString>;
+    embed_origin: z.ZodOptional<z.ZodString>;
+    expires_at: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type CheckoutSession = z.infer<typeof checkoutSessionSchema>;
+export declare const payRequestSchema: z.ZodObject<{
+    option_id: z.ZodString;
+    payment_token: z.ZodOptional<z.ZodString>;
+    payment_method_id: z.ZodOptional<z.ZodString>;
+    email: z.ZodOptional<z.ZodString>;
+    name_on_card: z.ZodOptional<z.ZodString>;
+    address1: z.ZodOptional<z.ZodString>;
+    city: z.ZodOptional<z.ZodString>;
+    state: z.ZodOptional<z.ZodString>;
+    zip: z.ZodOptional<z.ZodString>;
+    country: z.ZodOptional<z.ZodString>;
+    card: z.ZodOptional<z.ZodObject<{
+        number: z.ZodString;
+        exp_month: z.ZodNumber;
+        exp_year: z.ZodNumber;
+        cvc: z.ZodString;
+    }, z.core.$strip>>;
+    last_four: z.ZodOptional<z.ZodString>;
+    card_type: z.ZodOptional<z.ZodString>;
+    expiry_date: z.ZodOptional<z.ZodString>;
+    token_symbol: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PayRequest = z.infer<typeof payRequestSchema>;
+export declare const payResultSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        succeeded: "succeeded";
+        failed: "failed";
+        expired: "expired";
+        created: "created";
+        requires_action: "requires_action";
+        processing: "processing";
+        blocked: "blocked";
+        canceled: "canceled";
+    }>;
+    redirect_url: z.ZodOptional<z.ZodString>;
+    transaction_url: z.ZodOptional<z.ZodString>;
+    payment_id: z.ZodOptional<z.ZodString>;
+    subscription_id: z.ZodOptional<z.ZodString>;
+    failure_message: z.ZodOptional<z.ZodString>;
+    failure: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        reason: z.ZodString;
+        message: z.ZodString;
+        field: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    operation_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type PayResult = z.infer<typeof payResultSchema>;
+export type CheckoutPhase = "loading" | "ready" | "processing" | "succeeded" | "failed" | "blocked" | "expired" | "unavailable" | "error";

package/docs/1055-nmi-host-integration.md

@@ -0,0 +1,28 @@
+# NMI host integration and pending checkout states
+
+Owner: `/root/astra_neutral_resume`.
+Worktree: `/home/fidika/cozy/.worktrees/billing-ui/1055-nmi-checkout-ui-20260923`.
+Branch: `feat/1055-nmi-checkout-ui-20260923`.
+Base: `05d6e27` from freshly fetched `origin/master`.
+
+The demo will reuse this package's existing Collect.js hosted fields through a
+custom CheckoutSource that invokes its admitted application checkout wrapper.
+It will not enable generic billing checkout creation or send raw card data to the
+application. Stripe remains available alongside the explicitly selected NMI PSP.
+Only public tokenization configuration reaches the browser.
+
+Bounded library changes:
+
+- Represent `processing` as nonterminal server truth. Poll the same source for
+  progress without repeating pay or tokenization, including after reload. Local
+  quote expiry must not turn an accepted unresolved payment into a failed sale.
+- Expose a tokenized-card form composed from the existing Collect.js driver and
+  billing fields, for a host's separately consented save-card step. Do not model
+  card setup as a zero-priced purchase or show a payment-success receipt for it.
+- Retain exact string money and existing callbacks. Tests belong to this library;
+  the demo uses build/lint and manual qualification only.
+
+The existing metadata rename PR15 and customer billing package PR13 remain
+separately owned. Publication uses the GitHub release tarball workflow after review
+and CI; no source checkout path ships in a host dependency manifest. Real NMI
+iframe/tokenization/provider qualification remains a separate browser gate.

package/docs/payment-form-contract.md

@@ -0,0 +1,153 @@
+# Payment form contract
+
+`Checkout` renders one real `<form autocomplete="on">` and submits through its
+native submit event. Every host-owned billing field has a stable `id`, `name`,
+label, and standards-based autocomplete token.
+
+## Money
+
+The session document (`GET /billing/v1/checkout-sessions/{id}`) carries every amount
+as an exact signed int64 decimal string of `plan.currency`'s native unit, and
+`plan.unit_decimals` is that currency's registered scale:
+
+```json
+{
+  "plan": {
+    "display_name": "Premium Membership",
+    "unit_amount": "99000000",
+    "currency": "USD",
+    "unit_decimals": 6,
+    "period_hours": 720,
+    "automatically_renews": true
+  },
+  "line_items": [{ "label": "Premium Membership", "amount": "99000000" }],
+  "tax": "0",
+  "due_today": "99000000"
+}
+```
+
+`unit_amount`, `line_items[].amount`, `tax` and `due_today` share the plan's
+currency and scale. A JSON number, a decimal point, a value outside int64, or
+a missing `unit_decimals` fails schema validation and the session is
+unavailable; the package never assumes a scale. Hosts take the scale from
+OpenRails' currency registry (`billing.LookupCurrency`, the same table as
+`GET /v1/currencies`); OpenRails serves the session at
+`GET /v1/checkout-sessions/{id}`; the Go shape is
+`billing.HostedCheckoutSession` and its canonical fixture
+(`testdata/wire/hosted_checkout_session.json`) is decoded by this package's
+tests.
+
+Rendering scales with `BigInt` and hands Intl the exact major-unit decimal;
+`formatAmount`, `amountToDecimal` and `addAmounts` are exported for hosts that
+show the same figures outside the component. An amount the engine cannot show
+exactly is refused with a visible notice, never rounded. `due_today`, when
+absent, is the exact sum of the line items and `tax`.
+
+Version 0.3.0 replaces `unit_amount_micros`, `amount_micros`, `tax_micros` and
+`due_today_micros` (JSON numbers, assumed six decimals) with this contract.
+
+## NMI new cards
+
+The host collects only:
+
+- `name_on_card` — one visible “Name on card” input with `autocomplete="cc-name"`;
+- `country` — a native ISO-3166 country select with `autocomplete="billing country"`;
+- `zip` — a country-aware ZIP/postal input with `autocomplete="billing postal-code"`.
+
+Postal code is optional for the 53 ISO-3166 alpha-2 countries and territories
+in the Universal Postal Union's September 2025
+[list of countries which do not require postal codes](https://www.upu.int/UPU/media/upu/documents/PostCode/General-Addressing-Issues.pdf).
+The UI keeps a postal code when the customer supplies one. It does not collect
+street, city, or state for NMI.
+
+Card number, expiration, and CVC remain inside NMI Collect.js cross-origin
+iframes. NMI owns those inner inputs, including their browser-autofill behavior;
+host markup cannot assign `cc-number`, `cc-exp`, or `cc-csc` to them. The
+Collect.js configuration supplies the supported field titles and placeholders,
+and the outer host page provides stable labelled containers. Verify saved-card
+autofill against the real gateway in each supported browser because a DOM unit
+test cannot inspect or control the cross-origin fields.
+
+A PSP that takes cards on OpenRails itself (`card_entry: server`, driver
+`card`) gets plain inputs instead, with `autocomplete` `cc-number`, `cc-exp`
+and `cc-csc`, the same layout and field errors, and no gateway script. Its
+request carries `card: {number, exp_month, exp_year, cvc}` in place of
+`payment_token`; the inputs are cleared once the card is sent.
+
+A new-card payment request includes the one-time `payment_token` plus canonical
+`name_on_card`, uppercase ISO country in `country`, and `zip`. Paying with an
+existing saved method sends only `payment_method_id`; it does not overwrite the
+stored billing identity with empty form values.
+
+## CCBill
+
+For CCBill credit-card hand-off, the browser supplies only the same single
+`name_on_card`, country, and postal code. OpenRails binds the authenticated
+account's verified email and derives the customer's IP server-side; the browser
+cannot override either value. CCBill's FlexForms Address Fields are
+configurable for credit-card forms, so OpenRails does not collect street, city,
+or state in this flow. The checkout package never exposes separate first- and
+last-name inputs. OpenRails performs any provider-specific name projection at
+the CCBill boundary.
+
+Version 0.2.4 requires a checkout host whose pay endpoint accepts
+`name_on_card`. Legacy `first_name` and `last_name` are no longer emitted by
+this package.
+
+## Card subscriptions
+
+`Subscribe` is one action. The host's pay endpoint relays `payment_token` (or
+`payment_method_id`) to `CreateCheckoutSession` with `Confirm: true`; OpenRails
+saves a new card, accepts the displayed recurring terms and charges it. A
+decline answers `failed` and keeps no card; the next attempt uses a new key.
+
+## Solana Pay
+
+The package never assumes which token a Solana option settles in. OpenRails
+binds the token on the advertised option's `public_config` (hosts copy it):
+
+- `token_symbol` — required; the SPL mint symbol the price is bound to
+  (`USDC`, `USD1`, …). It is sent back verbatim (uppercased) as the pay
+  request's `token_symbol`. An option without it is not offered at all.
+- `token_name` — optional buyer-facing name (`USD Coin`), shown next to the
+  symbol in the method list.
+- `network` — optional Solana cluster (`mainnet-beta`, `devnet`, `testnet`).
+  Any network other than `mainnet-beta` is named in the method hint
+  (“USD Coin (USDC) on Solana devnet”) so a test-network payment is never
+  mistaken for a real one.
+
+Version 0.2.5 removes the former `USDC` default: a host that bound no token
+saw “USDC” before and sees no Solana option now.
+
+## Pending payment outcomes
+
+`processing` means an accepted outcome is unresolved. Checkout polls the same
+source's `getSession` without calling `pay` or Collect.js again. The optional
+`expires_at` may be null for an accepted pending attempt; a local display timer
+never releases or fails that attempt. The host must return verified terminal
+state, not infer payment from navigation or a timeout. A thrown error after
+`pay` starts is treated as unknown and remains pending, rather than enabling
+a fresh card token and payment. Tokenization/field validation errors before
+submission remain editable. Explicit `failed` results are definitive host
+responses; they must not represent an unknown provider result.
+
+A custom CheckoutSource may call an application-owned admission wrapper instead
+of the default hosted endpoints. It must retain its logical attempt identity
+and original request, use the same key for an authorized retry, and expose only
+the authorized buyer's state. `getSession` is a read, not another payment.
+
+## Separate NMI card setup
+
+`TokenizedCardForm` reuses the same hosted fields and emits `payment_token`,
+`name_on_card`, `country` and `zip` to its async `onTokenized` callback. The host
+provides explicit save-card consent and uses the callback to invoke its native
+authenticated save-card endpoint. Set `disabled` until consent is given. The
+form never creates a zero-dollar checkout or announces a completed payment.
+After token submission it locks the form; a failed/unknown save must be checked
+against the host's saved-method state before mounting a new attempt.
+
+Saving a card does not authorize a recurring charge. The host separately obtains
+and displays the immutable membership quote, then asks the signed-in customer
+to confirm that agreement.
+
+Hosts must key `TokenizedCardForm` by authenticated customer and provider identity. A customer change must unmount the old form. The form also discards an in-flight token if its tokenization configuration changes or save consent is withdrawn before dispatch.

package/package.json

@@ -1,6 +1,115 @@
 {
   "name": "@openrails/billing-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.230.0",
+  "description": "Embeddable OpenRails checkout and account-billing UI: client, React hooks and styled components.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-rails/openrails.git",
+    "directory": "sdk/billing-ui"
+  },
+  "homepage": "https://github.com/open-rails/openrails/tree/master/sdk/billing-ui#readme",
+  "bugs": {
+    "url": "https://github.com/open-rails/openrails/issues"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": [
+    "./dist/index.js",
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./locales/*": {
+      "types": "./dist/locales/*.d.ts",
+      "import": "./dist/locales/*.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "style": "./dist/styles.css",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "peerDependencies": {
+    "react": ">=19 <20",
+    "react-dom": ">=19 <20"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.7.0",
+    "@hugeicons/core-free-icons": "^4.2.3",
+    "@hugeicons/react": "^1.1.9",
+    "@stripe/stripe-js": "^9.17.0",
+    "class-variance-authority": "^0.7.1",
+    "cn": "0.4.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@microsoft/api-extractor": "^7.58.12",
+    "@playwright/test": "1.60.0",
+    "@solana/kit": "^6.10.0",
+    "@solana/pay": "^1.0.26",
+    "@solana/sysvars": "^5.5.1",
+    "@tailwindcss/vite": "^4.3.3",
+    "@testing-library/jest-dom": "^7.0.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^26.2.0",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "@vitejs/plugin-react": "^6.0.5",
+    "eslint": "^10.8.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.3",
+    "globals": "^17.9.0",
+    "jsdom": "^30.0.1",
+    "postcss": "8.5.26",
+    "prettier": "^3.9.6",
+    "prettier-plugin-tailwindcss": "^0.8.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tailwindcss": "^4.3.3",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.66.0",
+    "vite": "^8.2.1",
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^4.1.11"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:browser": "playwright test",
+    "test:e2e": "playwright test -c playwright.e2e.config.ts",
+    "contract": "node e2e/scripts/contract.ts",
+    "contract:check": "pnpm contract && git diff --exit-code -- src/client/generated && test -z \"$(git status --porcelain -- src/client/generated)\"",
+    "format": "prettier --write \"**/*.{css,ts,tsx,json,md}\"",
+    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm build"
+  }
 }