@rio-pay/sdk 0.0.0-stage → 0.0.1-alpha.2

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# @rio-pay/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The SDK for Rio USDC payments: the checkout widget, shared types and the utilities an integrator's backend needs (webhook signature verification today). It is deliberately small: no route handlers and no framework glue (every integrator wants their own), and no response parsers yet (the API shapes may still change).
+
+**Status: 0.x, alpha.** Published to npm under the `next` tag only until the first stable release. Expect breaking changes until 1.0.
+
+## Entries
+
+| Import | What it is | Runs in |
+|---|---|---|
+| `@rio-pay/sdk` | Types only: `CreatedCharge`, `ChargeCreateResult`, `ChargeStatus`, `Confirmation`, `CheckoutCopy`, `PlatformChargeStatus`, `PostCreateChargeOptions`, `WebhookEvent`, `WebhookEventType`. No runtime code. | anywhere |
+| `@rio-pay/sdk/client` | `createRioClient({ apiKey })`: `charges.create` returns the charge as the widget takes it, `charges.retrieve` the status its poll takes; failures are `RioError`. Server-side only. | Node 18+, Bun, edge runtimes |
+| `@rio-pay/sdk/server` | `verifyWebhook`, `signWebhook` (for your own tests), `SIGNATURE_HEADER`, `DEFAULT_TOLERANCE_SECONDS`. Web Crypto only, no React. | Node 18+, Bun, edge runtimes |
+| `@rio-pay/sdk/checkout/react` | The widget: `CheckoutWidget` (a client module, `"use client"`), the optional `postCreateCharge` fetch adapter, and the prop types (`CheckoutWidgetProps`, `PostCreateChargeOptions`, `CheckoutCopy`, `CheckoutState`, `CheckoutError`). React is an optional peer dependency (`^18.2 \|\| ^19`); you only need it for this entry. | browsers, React |
+
+## Verify a webhook
+
+```ts
+import type { WebhookEvent } from "@rio-pay/sdk";
+import { verifyWebhook, SIGNATURE_HEADER } from "@rio-pay/sdk/server";
+
+export async function POST(req: Request) {
+  const body = await req.text(); // the RAW body: re-serializing parsed JSON changes the bytes and breaks the signature
+  const ok = await verifyWebhook({
+    secret: process.env.WEBHOOK_SECRET!,
+    header: req.headers.get(SIGNATURE_HEADER) ?? "",
+    body,
+  });
+  if (!ok) return new Response("bad signature", { status: 400 });
+
+  const event = JSON.parse(body) as WebhookEvent;
+  // Delivery is at-least-once: dedupe on event.id before acting.
+  return new Response("ok");
+}
+```
+
+`verifyWebhook` returns `false` (never throws) for a malformed header, a timestamp more than 300 seconds from your clock (`toleranceSeconds` to change it), or a signature that does not match. Several `v1` values in one header (a secret rotation) are fine: any match passes. The comparison is constant time. The service's `service/src/core/crypto.ts` is the reference implementation; a parity test keeps the two byte-for-byte equal.
+
+## Checkout widget
+
+```tsx
+import { CheckoutWidget, postCreateCharge } from "@rio-pay/sdk/checkout/react";
+
+<CheckoutWidget
+  orderId={order.id}
+  merchantName="Moon Lantern"
+  // Calls YOUR route. The route decides the amount and creates the charge with your API key.
+  createCharge={() => postCreateCharge("/api/checkout", { orderId: order.id })}
+  // Your route that returns the authoritative status for a charge (a PlatformChargeStatus), or null to turn polling off.
+  statusUrl={(chargeId) => `/api/checkout/status?chargeId=${encodeURIComponent(chargeId)}&orderId=${encodeURIComponent(order.id)}`}
+  onPaid={(status) => { /* status.confirmation is "provisional", then "final" */ }}
+/>
+```
+
+It shows a "Pay with USDC" button, opens a modal, connects the buyer's wallet (EVM and Solana) and walks them through paying a charge. It has no styles to import (the CSS ships inside the component).
+
+`createCharge` and `statusUrl` are required: the widget has no default routes. The `statusUrl` route may return the service charge from `GET /v1/charges/:id` as is (`id`, `status`, `confirmed`, `confirmation`, `collected_amount`) or the same fields in camelCase (`chargeId`, `collectedAmount`). **Scope the status route to the buyer's own order.** It reads the charge with your API key, so it must not answer for a charge that is not theirs: send the order id along (as above), have the create route record which charge belongs to the order, and in the status route load the signed-in buyer's order and return 404 unless its charge id matches, before calling the client or `fetch`.
+
+### The create route and `postCreateCharge`
+
+Two shapes, kept apart. Your **HTTP route** answers a success (2xx) with the created charge as flat JSON (a `CreatedCharge`, not wrapped), and a failure with an error status and `{ error, code? }`. A **409** means the order already has a different charge (for example its amount changed): create a new order id. The **`createCharge` callback** resolves to a `ChargeCreateResult`: `{ ok: true, charge }` or `{ ok: false, status, error, code? }`.
+
+`postCreateCharge(url, body, options?)` is the adapter between the two, for the common case. It POSTs `body` (JSON-stringified unless it is already a string) to your route and never throws: a network error, an abort, a non-JSON body or a 2xx without an object charge resolve to `{ ok: false, status: 503 }`. Every option is optional:
+
+| Option | Default | What it does |
+|---|---|---|
+| `method` | `"POST"` | `"POST"`, `"PUT"` or `"PATCH"`. |
+| `headers` | none | Merged over the default `content-type: application/json` (so CSRF or auth headers work). A function is called on every request, sync or async, so it can read a token at call time. |
+| `credentials` | `fetch`'s default | Passed to `fetch` as is (for example `"include"`). |
+| `signal` | none | An `AbortSignal`. An abort resolves to a 503 result. |
+| `fetch` | the global `fetch` | A custom `fetch`, for tests or a wrapped client. Resolved at call time. |
+| `selectCharge(json)` | the body itself | Picks the charge out of a success body, for routes that answer `{ data: charge }` or `{ charge }`. |
+| `selectError(json)` | top-level `error` and `code` strings | Returns `{ error?, code? }` from a failure body. |
+
+```ts
+createCharge={() =>
+  postCreateCharge("/api/checkout", { orderId: order.id }, {
+    headers: () => ({ "x-csrf-token": readCsrfToken() }),
+    credentials: "include",
+    selectCharge: (json) => (json as { data: unknown }).data,
+  })
+}
+```
+
+You can also write your own `createCharge` that resolves to a `ChargeCreateResult` (any function will do). **The widget validates the charge either way**, so it does not matter how your route fetched it: an `http` service URL on a public host, a URL with embedded credentials, or a charge missing the client secret or another load-bearing field is treated as a failed create (status 503, the same controlled copy as any create failure) and the client secret is never sent anywhere.
+
+The widget never sends an amount and never holds your API key. Your server route calls `POST /v1/charges` (see `internal/docs/API.md`) and returns the charge as JSON with `chargeId`, `clientSecret`, `serviceUrl`, `amount`, `chain`, `chargeAddress`, `status`, `confirmed`, `confirmation` and `expiresAt`. The client secret stays in component state only. `serviceUrl` must be `https` (plain `http` is accepted only for `localhost`, `127.0.0.1` and `[::1]`), because the secret is sent there. After that the browser talks to the service directly, with per-charge CORS.
+
+Props worth knowing: `presentation` (`"modal"` or `"inline"`), `appearance` (`"auto" | "light" | "dark"`), `copy` (a `Partial<CheckoutCopy>` that overrides any string), `manualPayment`, `defaultOpen`, `successSlot`, `onStatusChange`, `onError`. Theme with the CSS variables `--sc-accent`, `--sc-radius`, `--sc-bg`, `--sc-fg`, `--sc-muted`, `--sc-border`, `--sc-success`, `--sc-danger`.
+
+## Design rules
+
+One thing to do: the buyer sees an amount, picks which USDC to pay with, connects a wallet and pays.
+
+- **One button, one modal.** The host page shows a single "Pay with USDC" button that opens a native `<dialog>` modal (`presentation="inline"` renders the same content in place for hosts that already sit inside their own dialog). The charge is created when the modal first opens, not on page load.
+- **The modal:** a fixed read-only amount; a token chip that says just "USDC" until a wallet is connected, then a dropdown of the connected wallet's options that hold USDC (USDC with the chain's logo and name as a small subscript: Sei Testnet / Base Sepolia / Solana, all service data, never hardcoded; a zero balance is not listed, a balance below the amount is listed but disabled, the best payable option is preselected, and a wallet with none shows the no-USDC screen); "Connect wallet" (with the dropdown empty until then, any installed wallet of either kind can connect: a list of all of them when both kinds are installed, "Switch wallet" included), then "Pay"; a decorator row above the amount that alternates the USDC balance and the gas balance; three stages (confirm in wallet, payment sent, payment confirmed, the last driven by the host's status route). "Pay another way" is hidden unless `manualPayment` is set.
+- **Pay another way (a plain transfer, e.g. from an exchange).** It offers the charge address only, under its USDC chip, with a copy button: a wallet or an exchange that sends USDC on the charge's network pays it as is. A warning above the address names the one network to choose when withdrawing and says only USDC is accepted, and the address and its copy button stay hidden until the buyer ticks "I'll send USDC on <network>". One calm line below points a buyer whose exchange cannot send on that network to withdraw to their own browser wallet first and pay with it in the modal (`manualOwnWallet`; it never names an exchange). The copy also says to make sure the full amount arrives because exchanges deduct their fee (anything short is collected and shown as a partial payment). It stays opt-in: one thing to do is still the default, and a transfer, an exchange withdrawal especially, can take longer than the charge lives, so a host that turns it on should give its charges a longer expiry.
+- **Other tokens** (when the service offers them) show the token's own symbol with the chain subscript and a required "You pay X TOKEN" line before the button, because the amount that leaves the wallet differs from the dollar price. If the price moves between the line and the click, nothing is signed.
+- **Vocabulary.** Buyer-facing copy never says "bridge", "route", "swap", "slippage", "quote", "authorization", "CCTP", "attestation", "Standard", "Fast" or "deliverable", and network names appear only in the dropdown subscript and, on "pay another way", in the chip, the warning and confirmation next to the address and the own-wallet line (the exchange's withdrawal screen asks for the network by name and a withdrawal on the wrong one is lost, so there the name is the one thing the buyer must get right); the word "network" itself is fine, it is what exchanges call the choice. Allowed: "Pay with USDC", "Connect wallet", "Pay $12.00", "Confirming payment...", "Payment confirmed". A unit test guards this.
+- **Failures are controlled copy.** Text that comes back from your route, the service or a wallet (`error`, `message`, thrown errors) is never shown to the buyer: status and code map to a `copy` string (`conflict`, `expired`, `createFailed`, `network`, `service`, `unknown`, ...). "Show details" holds only an HTTP status and a code from a fixed list. The raw text reaches you through `onError` as `error.cause` (never the client secret).
+- **Implementer settings** (server-side, per charge, never the buyer's): `speed` (`standard` default: no fee, no slippage) and `require_confirmation` (`provisional` default: the order may be fulfilled on a provisional confirmation, `final` waits for settlement). Fields: `confirmed` and `confirmation` (`pending`, `provisional`, `final`).
+- **Quality bar:** zero runtime dependencies besides React, theming through CSS variables, light and dark, accessible (focus trap, Escape, live regions, 44 px targets), safe when storage is blocked, secrets only in memory.
+
+## Develop
+
+```
+bun install
+bun run dev        # dev host on :3030: a stand-in storefront that mounts the widget from src (hot reload); needs the service, so prefer `bun dev` at the repo root
+bun run typecheck
+bun test           # unit tests, server-rendered component tests, and happy-dom interaction tests
+bun run build      # dist/: one ESM file per entry (index, server, client, checkout/react with the "use client" banner and react external) + .d.ts
+bun run test:dist  # checks the built package: every exports path exists and each subpath imports (needs a build first)
+bun pm pack --dry-run # exactly dist/, README.md and package.json ship
+```
+
+`dev/` is the dev host (page, server routes and the pure logic in `dev/host.ts`); it is not part of the package (`files` ships `dist` only) and is typechecked with the rest. `bun run dev` reads `PAYMENTS_SERVICE_URL`, `PAYMENTS_API_KEY`, `PAYMENTS_MERCHANT_ID`, `PAYMENTS_WEBHOOK_SECRET` and `PORT`; `bun dev` at the repo root supplies them.
+
+Layout: `src/index.ts` (types), `src/server.ts` (webhook utilities), `src/client.ts` (the API client) and `src/checkout/react.ts` (the widget) are the four entries; `src/entries.test.ts` enforces that none but the last reaches React or a component, that the server entry imports no `node:` module, and that no entry exports the copy table or a parser (`postCreateCharge` is exported from the client entry only). Everything else is internal. `src/lib/` holds the framework-free logic (options, pay plans, wallets, Solana, client, webhook signatures); `src/components/` holds the React components.
+
+## Releasing
+
+Publishing is manual and tag-driven: push a tag `sdk-vX.Y.Z` that equals the package version and points at a commit on main (a manual run of the `publish-sdk` workflow is always a dry run and stages nothing). The workflow typechecks, tests, builds, runs `bun pm pack --dry-run`, and runs `npm stage publish --access public` with the `NPM_TOKEN` secret. That only stages the version: a maintainer then approves it with 2FA (`npm stage list`, `npm stage approve <stage-id>`) and only then is it public. Nothing else can publish the package.
+
+## Before the first stable release
+
+- **Remove the Acoco copy.** The widget was extracted from the Acoco store template (`byoidea-v3`), which still carries its own copy. Make the template consume this package (or stop shipping the copy) so there is one implementation.
+- **Package metadata.** Real version, license, a changelog, and a first-release smoke test in a clean Next.js app. `sideEffects` is left out on purpose: `false` or an array makes `bun build` drop the entry's re-exports and emit a broken bundle.
+- **Bundle size.** 108 KB minified for the widget entry, 1.3 KB for `server`; check what a consumer's bundler can tree-shake.
+- **React 18.** `peerDependencies` allow it but only React 19 is tested; add a React 18 test matrix before the first release.
+- Cut `1.0.0` and tag it (see Releasing); alphas go out on the `next` tag only.

package/dist/brand.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The checkout widget's brand pack: the product name for the "powered by" line and the default colours.
+ * Hosts can still override every colour through the `--sc-*` custom properties; these are the defaults.
+ */
+export declare const brand: Readonly<{
+    name: "Rio";
+    poweredBy: "Powered by Rio";
+}>;
+/** The mark, as the path of a 80x80 stroke drawing. Uses currentColor. */
+export declare const MARK_PATH = "M 13 70 L 13 12 L 40 12 C 59 12 68 22 68 35 C 68 48 58 55 41 55 L 13 55 M 41 55 L 67 70";
+/** Default colour tokens: light, dark when `data-appearance="dark"`, and dark for `auto` when the browser prefers it. */
+export declare const THEME_CSS = ".sc-root{--scd-bg:#fff;--scd-surface:#f3f5f8;--scd-fg:#0b1220;--scd-muted:#5a6376;--scd-border:#dfe3e9;--scd-line:#8a92a0;--scd-accent:#315cff;--scd-on-accent:#fff;--scd-success:#15803d;--scd-danger:#b42318;--scd-warn:#a15c07;--scd-shadow:0 24px 64px rgba(15,23,42,.22),0 2px 8px rgba(15,23,42,.08);--scd-scrim:rgba(15,23,42,.42)}\n.sc-root[data-appearance=\"dark\"]{--scd-bg:#0b1220;--scd-surface:#141d31;--scd-fg:#f3f5f8;--scd-muted:#a9b3c7;--scd-border:#26314a;--scd-line:#6f7b94;--scd-accent:#7c97ff;--scd-on-accent:#0b1220;--scd-success:#4ade80;--scd-danger:#ff8f84;--scd-warn:#fbbf24;--scd-shadow:0 24px 64px rgba(0,0,0,.6),0 2px 8px rgba(0,0,0,.4);--scd-scrim:rgba(0,0,0,.62)}\n@media (prefers-color-scheme:dark){.sc-root[data-appearance=\"auto\"]{--scd-bg:#0b1220;--scd-surface:#141d31;--scd-fg:#f3f5f8;--scd-muted:#a9b3c7;--scd-border:#26314a;--scd-line:#6f7b94;--scd-accent:#7c97ff;--scd-on-accent:#0b1220;--scd-success:#4ade80;--scd-danger:#ff8f84;--scd-warn:#fbbf24;--scd-shadow:0 24px 64px rgba(0,0,0,.6),0 2px 8px rgba(0,0,0,.4);--scd-scrim:rgba(0,0,0,.62)}}";

package/dist/checkout/react.d.ts

@@ -0,0 +1,5 @@
+export { CheckoutWidget } from "../components/payments-checkout";
+export type { CheckoutWidgetProps, CheckoutCopy, CheckoutState, CheckoutError, } from "../components/payments-checkout";
+export { postCreateCharge } from "../lib/create-charge";
+export type { PostCreateChargeOptions } from "../lib/create-charge";
+export type { ChargeCreateResult, CreatedCharge, PlatformChargeStatus, Confirmation } from "../lib/payments";