@boltclaw/referrals 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bolt Claw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,500 @@
-# Temporary Holding Version
-
-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.
+# @boltclaw/referrals
+
+Bolt Claw referrals for your own product. Call any referral operation through a typed client
+generated from the API's own specification; report signups (with both dates right), sales and
+refunds from your server; keep the referral code through Safari with a proxy for Next.js and
+Express that reads every query name your links use; verify Bolt
+Claw's webhooks; read the program's live setup status and send a test sale. Put an "invite a
+friend" panel in your app, mint the short-lived tokens it needs from your server, and read a
+referrer's numbers to draw a screen of your own. Welcome the friend who arrived through a link with
+their offer, apply the discount at Stripe Checkout from your server, and ask a new customer to share
+on your thank-you page. No runtime dependencies; ESM only; Node 20+, Deno, Bun, edge runtimes and
+modern browsers.
+
+```sh
+npm install @boltclaw/referrals
+```
+
+**0.4.0 is not on npm yet.** It is built and its tests pass; publishing it is the maintainers'
+step. Until then `npm install @boltclaw/referrals` answers 404, and every page of Bolt Claw's
+documentation that uses the package shows the same thing without it.
+
+React is an optional peer dependency, needed only for `@boltclaw/referrals/react`.
+`@boltclaw/referrals/server` holds the server half alone (the server class, the middleware and
+`verifyWebhook`), with nothing that touches a page: import that one in Next.js middleware.
+
+## How it fits together
+
+1. **Your server** holds an API key (scope `referrals:embed`) and mints an embed token for the
+   signed-in user: `ReferralsServer.createEmbedToken`.
+2. **Your page** gives that token to the panel, by script tag, React component or web component.
+3. The panel is an iframe served by Bolt Claw. It reads the token from the URL fragment, keeps it in
+   memory, and talks only to Bolt Claw.
+
+You also need the program's public **embed key** and the list of **origins** that may frame the
+panel (Dashboard, Referrals, In your app).
+
+## Ways in
+
+### 1. Script tag
+
+The hosted loader installs a global, with the same behaviour as this package's `mountPanel`:
+
+```html
+<div id="referrals"></div>
+<script src="https://boltclaw.ai/referrals/embed.js"></script>
+<script>
+  const panel = BoltClawReferrals.mount(document.getElementById("referrals"), {
+    token: "<token your server minted>",
+    embedKey: "<your embed key>",
+  });
+  panel.on("expired", async () => panel.update({ token: await fetchNewToken() }));
+</script>
+```
+
+The thank-you card is `mode: "thank-you"` in the options, or `data-mode="thank-you"` on the element
+you mount into (see [The thank-you card](#the-thank-you-card)).
+
+### 2. Modules (no framework)
+
+```js
+import { mountPanel, openPanel, closePanel } from "@boltclaw/referrals";
+
+const panel = mountPanel(document.getElementById("referrals"), { token, embedKey });
+panel.on("copied", () => console.log("link copied"));
+
+openPanel({ token, embedKey }); // a modal with a focus trap; Escape or the backdrop closes it
+closePanel();
+```
+
+`mountPanel` and `openPanel` return a handle: `update({ token })`, `refresh()`, `unmount()`,
+`on(type, fn)`, `off(type, fn)` and `iframe`. Options: `token`, `embedKey`, `origin` (default
+`https://boltclaw.ai`), `theme`, and `mode: "thank-you"` for the compact card (any other value is the
+whole panel). In a modal, "Not right now" on the card emits `dismissed` and then closes it.
+
+### 3. React
+
+```tsx
+import { ReferralPanel, useReferrer } from "@boltclaw/referrals/react";
+
+<ReferralPanel token={token} embedKey="ek_..." onEvent={(type, payload) => track(type)} />;
+
+// A modal:
+<ReferralPanel token={token} embedKey="ek_..." mode="modal" open={open} onClose={() => setOpen(false)} />;
+
+// The thank-you card, inline; hide it when they choose "Not right now":
+{ask && <ReferralPanel token={token} embedKey="ek_..." mode="thank-you" onDismiss={() => setAsk(false)} />}
+
+// Your own screen, from the same data the panel draws:
+const { view, error, loading, expired, refresh } = useReferrer(token, { refreshMs: 60_000 });
+```
+
+It renders on a server (nothing touches `window` outside an effect). A new `token` prop is passed to
+the running panel without re-creating it.
+
+### 4. Web component
+
+```html
+<script type="module">import "@boltclaw/referrals/element";</script>
+<boltclaw-referrals token="..." embed-key="ek_..." mode="inline"></boltclaw-referrals>
+<boltclaw-referrals token="..." embed-key="ek_..." mode="modal" open></boltclaw-referrals>
+```
+
+Attributes: `token`, `embed-key`, `mode` (`inline`, `modal` or `thank-you`), `origin`, `theme`, and
+`open` (modal).
+The loader's events are re-dispatched as DOM events with the same names; the payload is in `detail`.
+
+### 5. Headless (your own screen)
+
+In the browser, with a token:
+
+```js
+import { createPanelClient, isExpired } from "@boltclaw/referrals";
+
+const client = createPanelClient({ token });
+const view = await client.get(); // link, stats, rewards, history (with stable reasonCode), copy
+await client.share("whatsapp"); // counts a share
+await client.savePayoutDetails({ method: "paypal", email: "jane@example.com" });
+await client.dismiss(); // "Not right now": shouldAsk answers false for the program's days
+```
+
+`view` is the same View the panel draws, in camelCase. Translate history rows by `reasonCode`.
+`view.grants` lists the referrer's rewards that are not cash ("1 month free") with a `statusText`
+sentence; `view.ask.shouldAsk` and `view.thankYou` are what the thank-you card uses.
+
+## The friend's welcome
+
+A friend who arrives through a referral link carries a code your page's referral tag
+(`https://boltclaw.ai/referrals/v2.js`, or `v1.js`) keeps for them. Show them the offer:
+
+```tsx
+import { ReferralWelcome, useOffer } from "@boltclaw/referrals/react";
+
+// Reads BoltClawReferral.code() and the public offer; renders nothing when there is none.
+<ReferralWelcome className="my-welcome" />;
+
+// Or draw your own:
+const { offer, loading } = useOffer(); // or useOffer("jane-20")
+if (offer) console.log(offer.inviter ?? "A friend", offer.gift, offer.conditions, offer.disclosure);
+```
+
+`<ReferralWelcome />` is a `role="region"` labelled "Referral offer": "Jane invited you" (or "A
+friend invited you" when the inviter did not agree to their name being shown), the gift as its
+headline, the conditions, the disclosure whenever the inviter is rewarded (always show it), the
+program's call to action if it set one, and a Close button. It carries the program's accent and
+corner radius as `--bc-accent` and `--bc-radius` and otherwise leaves the styling to your
+`className`. Text only, no remote asset. Props: `offer` (draw one you already have), `code`,
+`origin`, `fetch`, `showCta`, `onClose`, `className`, `style`.
+
+`useOffer` reads the offer once per code, with no cookie and no credentials, from
+`https://boltclaw.ai/api/referrals/offer`. That read is for SHOWING the offer: the discount is
+decided by your server at checkout.
+
+## The discount at checkout
+
+The browser sends your server the code it has; your server asks Bolt Claw whether THIS customer may
+have the offer, and hands Stripe the discount:
+
+```ts
+app.post("/api/checkout", requireLogin, async (req, res) => {
+  const code = typeof req.body.referral === "string" ? req.body.referral : null; // BoltClawReferral.code()
+  const offer = code ? await referrals.getOffer(code, { customerId: req.user.id, newCustomer: !req.user.hasPaid }) : null;
+  const session = await stripe.checkout.sessions.create({
+    mode: "subscription",
+    line_items: [{ price: process.env.PRICE_ID, quantity: 1 }],
+    client_reference_id: code ?? undefined,
+    metadata: { boltclaw_customer_id: req.user.id, ...(code ? { boltclaw_ref: code } : {}) },
+    subscription_data: code ? { metadata: { boltclaw_ref: code } } : undefined,
+    discounts: offer?.discounts, // [{ promotion_code }] or [{ coupon }], or [] when not eligible
+    success_url: "https://example.com/thanks",
+    cancel_url: "https://example.com/pricing",
+  });
+  res.json({ url: session.url, notice: offer && !offer.eligible ? offer.reason : null });
+});
+```
+
+`discounts` is the promotion code Bolt Claw knows in your Stripe when there is one (the friend's
+code shows on the receipt), else the coupon, else nothing, and always nothing when the customer is
+not eligible. `reasonCode` says why: `unknown_code`, `program_paused`, `self_referral`,
+`already_referred` or `not_new`; `reason` is a sentence your checkout can show instead of an error.
+With any other billing system, pass `offer.discount.code` the way it expects.
+
+## The thank-you card
+
+After a friend's first payment, Bolt Claw can make them a referrer of their own (the program's
+"invite after purchase"). On your page after a purchase, ask them to share, at the right moment and
+not every time:
+
+```ts
+// Your server, on the thank-you page:
+if (await referrals.shouldAsk(user.id)) {
+  const { token } = await referrals.createEmbedToken({ externalId: user.id, name: user.firstName });
+  // render <ReferralPanel mode="thank-you" token={token} ... />
+}
+```
+
+The card shows "Now give your friends 20% off", their link with a Copy button, the share buttons,
+and "Not right now". After a share or a copy it says what happens next ("You get 1 month free once
+they make their first payment."). "Not right now" is recorded through the token, on Bolt Claw's
+side with no cookie, and fires `dismissed`; `shouldAsk` then answers false for the program's days
+(30 by default).
+
+
+## Server helpers
+
+Run these on your server only.
+
+```ts
+import { ReferralsServer } from "@boltclaw/referrals";
+
+const referrals = new ReferralsServer({
+  apiKey: process.env.BOLTCLAW_API_KEY!, // never in a browser
+  programId: process.env.BOLTCLAW_PROGRAM_ID!,
+});
+
+const { token, expiresAt } = await referrals.createEmbedToken({ externalId: user.id, name: user.firstName });
+```
+
+Express:
+
+```ts
+app.get("/api/referral-token", requireLogin, async (req, res) => {
+  const { token } = await referrals.createEmbedToken({ externalId: req.user.id, name: req.user.firstName });
+  res.set("Cache-Control", "no-store").json({ token });
+});
+```
+
+Next.js server action:
+
+```ts
+"use server";
+export async function referralToken() {
+  const user = await currentUser();
+  return (await referrals.createEmbedToken({ externalId: user.id, name: user.firstName })).token;
+}
+```
+
+| Method | What it does |
+| --- | --- |
+| `createEmbedToken({ externalId, name?, email?, code?, ttlSeconds?, mode? })` | Mints a token and creates the referrer if new. `mode: "preview"` needs no referrer and shows sample data. Returns `{ token, expiresAt, referrer }`. |
+| `upsertReferrer({ externalId, name?, email?, code? })` | `{ referrer, created }`. A `code` can only be chosen when created. |
+| `getReferrer(externalId)` | Exactly what the panel shows this referrer. |
+| `listReferrers({ status?, search?, limit?, cursor? })` | `{ data, nextCursor }`. |
+| `updateReferrerStatus(referrerId, "approved" \| "banned")` | Needs `referrals:write`. |
+| `eraseReferrer(referrerId, { approvalId? })` | Anonymises the referrer, keeps earned commissions. A key held by an assistant gets a 428 with `approvalUrl` first. |
+| `getOffer(code, { customerId?, newCustomer? })` | The friend's offer and whether this customer may have it: `{ offer, eligible, reasonCode, reason, coupon, discounts }`. `discounts` goes straight to Stripe Checkout. |
+| `getCustomerReferral(externalId)` | Who invited one of your customers: `{ invitedBy, invitedAt, via }` (`via` is `link` or `discount_code`). A customer the program never saw is a 404. |
+| `shouldAsk(externalId)` | Whether to show the thank-you card now. False after "Not right now" (for the program's days), for a referrer that does not exist, a banned one, and while the program is paused. Any other failure throws. |
+| `recordSignup({ user: { id, createdAt, email? }, code?, occurredAt?, eventId?, test? })` | A signup with both dates right: `customer.created_at` from your user record, `occurred_at` from now. Refuses the two equal to the second (when you set `occurredAt`) or the wrong way round. |
+| `claimGrant(grantId)`, `markRewardsSeen(externalId, { through? })` | A person's claim of a claimable free month; your own screen showed their new rewards. |
+| `recordLead({ customerId, eventId, email?, customerCreatedAt?, referralCode?, discountCode?, occurredAt?, test?, idempotencyKey? })` | A signup. `{ conversion, created }`; a repeated `eventId` is `created: false` and changes nothing. Needs `conversions:write`. |
+| `recordSale({ customerId, eventId, amount, currency, referralCode?, discountCode?, discountApplied?, items?, test? })` | A paid sale in minor units. `items` (each with an `amount`) must add up to `amount`. |
+| `recordRefund({ eventId, refundOf, amount, currency?, test? })` | This refund alone; `refundOf` is the sale's `eventId`. |
+| `recordDispute({ eventId, refundOf, amount?, currency?, test? })` | A chargeback: the sale's commission is reversed in full. |
+| `recordClick({ code, ip?, userAgent?, referrer?, country?, landingPath? })` | A click your own server saw on a partner's link. Hashed and classed by Bolt Claw, never stored; earns nothing by itself. `{ recorded, reason, programId }`. |
+| `getIntegrationStatus()` | The live setup status: each part (`tag`, `billing`, `signups`, `sales`, `codes`, `panel`, `welcome`) `connected`, `warnings` or `not_connected`, with the fix. Needs `referrals:read`. |
+| `sendTestSale({ idempotencyKey? })` | A whole TEST sale through the program, step by step. Needs `referrals:write`. |
+| `listGrants({ status?, type?, recipient?, limit?, cursor? })`, `getGrant(id)` | The program's rewards that are not cash. |
+
+Constructor options: `apiKey`, `programId`, `baseUrl` (default `https://api.boltclaw.ai/v1`; https
+only, except localhost and 127.0.0.1), `fetch` (inject your own), `dangerouslyAllowBrowser`.
+Nothing is retried for you.
+
+## The typed client (generated)
+
+`BoltClawClient` is compiled from Bolt Claw's OpenAPI specification (`npm run client:gen` in Bolt
+Claw's repository): a type for every schema, with the wire's own snake_case names, and a method for
+every referral operation and `ping`. Each method is one `fetch`: the key as a Bearer header, no
+redirect followed, an `Idempotency-Key` only where the operation takes one. `ReferralsServer` below
+calls it underneath, and exposes it as `server.api` for anything it has no method for.
+
+```ts
+import { BoltClawApiError, BoltClawClient } from "@boltclaw/referrals/server";
+import type { ProgramStats } from "@boltclaw/referrals/api"; // every schema's type
+
+const api = new BoltClawClient({ apiKey: process.env.BOLTCLAW_API_KEY! });
+const stats: ProgramStats = await api.getReferralProgramStats({ id: programId, bucket: "month" });
+console.log(stats.totals.sales, stats.rewards.given, stats.rewards.claimable_now);
+
+try {
+  await api.deleteReferralReward({ id: ruleId });
+} catch (error) {
+  if (error instanceof BoltClawApiError && error.needsApproval) {
+    // An AI assistant's key: show error.approval.url to a person, then send the identical request again.
+    await error.retry();
+  } else throw error;
+}
+```
+
+`error.code` is one of the API's stable codes (`ErrorCode`, a union) or the client's own
+`network_error` and `invalid_response`; branch on it, never on the sentence. `client.send(operationId,
+input)` reaches any operation by its id and answers `{ status, data, requestId }`. It refuses to start
+where `window` exists (an API key must never reach a browser), and imports nothing: Node 18+, Deno
+and edge runtimes.
+
+## Your program's numbers in your own admin
+
+A key with the **Reporting (read-only)** preset holds `referrals:read` only, and the key form has
+you pick the programs it may read. `getReferralProgramStats({ id })` answers clicks, signups, sales,
+revenue and commission, and `rewards`: the rewards that are not cash given, claimed, claimable (and
+`claimable_now`), expired, cancelled, reversed and refused, in total, per type and per bucket, live
+data only (`rewards.test` counts test data apart).
+
+## Reporting conversions from your server
+
+```ts
+const referrals = new ReferralsServer({ apiKey: process.env.BOLTCLAW_API_KEY!, programId: process.env.BOLTCLAW_PROGRAM_ID! });
+
+// At signup: your user record, and the code your server kept (the bc_ref cookie).
+await referrals.recordSignup({ user: { id: user.id, createdAt: user.createdAt }, code: req.cookies.bc_ref });
+
+// At payment, if your billing system is not connected to Bolt Claw directly:
+await referrals.recordSale({ customerId: user.id, eventId: invoice.id, amount: 4900, currency: "USD" });
+await referrals.recordRefund({ eventId: refund.id, refundOf: invoice.id, amount: 1000 });
+```
+
+`recordSignup()` sets `customer.created_at` from your user record and `occurred_at` from now (or the
+`occurredAt` you give, for a code entered later), under the event id `signup:<user id>`. It refuses,
+before sending anything, a call whose two dates are equal to the second when you set `occurredAt`,
+or whose `occurredAt` is before the account existed: the dates the wrong way round make every
+account look new to the program's new-customer window.
+
+`eventId` is YOUR id for the event and the idempotency key: retry with the same one, never a new
+one. A key with the single scope `conversions:write` does nothing else, so it can sit in a checkout
+server.
+
+## Inside an AI assistant (your own MCP server)
+
+`assistantTools()` gives your own MCP server two tools: `get_my_invite` (the person's code, link,
+a message to share, their friends and rewards, as plain sentences in their language) and
+`use_invite_code` (checks a code or a pasted link, says what it gives, and saves it only once the
+person agreed). Each comes as a definition (`name`, `title`, `description`, `inputSchema`,
+`outputSchema`, `annotations`) with a `handler`, plain objects any MCP library takes; the package
+has no MCP dependency.
+
+```ts
+import { assistantTools } from "@boltclaw/referrals/server";
+
+const kit = assistantTools({
+  apiKey: process.env.BOLTCLAW_API_KEY!, // referrals:read and conversions:write, limited to the program
+  programId: process.env.BOLTCLAW_PROGRAM_ID!,
+  // The person from YOUR MCP server's own sign-in, never from a tool argument.
+  customerOf: (ctx) => ctx.user && { id: ctx.user.id, locale: ctx.user.locale, createdAt: ctx.user.createdAt },
+  // What YOUR sign-in page saw when they signed in; never this request's address.
+  signInAddressOf: (ctx) => ctx.user?.signIn ?? null,
+  // MCP elicitation, when the client supports it; null otherwise (then `confirm: true` is needed).
+  elicit: (ctx, request) => (ctx.canElicit ? ctx.elicit(request) : null),
+});
+
+// tools/list: kit.definitions()   tools/call: kit.call(name, args, ctx)
+```
+
+The descriptions tell the assistant to run a tool only when the person asks, and `use_invite_code`
+never saves a code a document, a page or another tool put in the conversation without the person's
+own yes. The whole guide, with both tools mounted with the official TypeScript and Python SDKs, the
+store rules and the defences against prompt injection:
+https://boltclaw.ai/docs/referral-ai-assistants
+
+## Keeping the referral code through Safari
+
+Safari deletes a cookie a script created once the visitor has gone 7 days of browsing without
+using your site, whatever your program's window is, and keeps one only 24 hours on a page reached
+through a tracking link. A first-party cookie set by your own server keeps the lifetime it was given,
+unless the response comes through a third party's CNAME or IP address, which Safari caps at 7 days
+(https://webkit.org/tracking-prevention/, read 2026-10-23). The
+middleware reads `?via=<code>` on your server and sets the same `bc_ref` cookie the website tag
+reads, so the two always agree.
+
+Next.js 16 (`proxy.ts`; on Next.js 15 and earlier the same in `middleware.ts`):
+
+```ts
+import { NextResponse, type NextFetchEvent, type NextRequest } from "next/server";
+import { nextReferralsProxy } from "@boltclaw/referrals/server";
+
+const referrals = nextReferralsProxy({
+  cookieDays: 30, // your program's cookie window
+  attribution: "last_click", // or "first_click"
+  params: ["via", "ref"], // every query name your links use
+  programs: { friend: process.env.BOLTCLAW_FRIEND_PROGRAM_ID! }, // a name that belongs to one program
+  // Optional: count each visit as a click (a key with conversions:write). Never delays the response.
+  reportClicks: { apiKey: process.env.BOLTCLAW_API_KEY! },
+});
+
+export function proxy(request: NextRequest, event: NextFetchEvent) {
+  const response = NextResponse.next();
+  referrals(request, response, event); // event.waitUntil keeps the click report alive
+  return response;
+}
+```
+
+`params` lists every query name your links use, read in that order. A name in `programs` belongs
+to one program when one product runs several: its code is kept in a cookie of its own,
+`bc_ref_<name>` (with `bc_sub_<name>`), so a friend's code never replaces a partner's, and
+`referralCodeFor(cookieHeader, programId, { programs })` reads it back on your server. Each code a
+request carries is recorded once, as a click, with the visitor's address taken from the LAST
+`X-Forwarded-For` entry past your own private proxies (Vercel overwrites the header and Cloudflare
+appends to it), never the first, which the visitor writes; or from a header your host overwrites,
+when you name it (`ipHeader: "x-real-ip"`, `"cf-connecting-ip"`, `"fly-client-ip"`). No header is
+believed unless you name it. A code kept for a program is the code as it arrived: Bolt Claw credits
+it only in the program it belongs to, so send its conversions with that program's id.
+
+Express:
+
+```ts
+import { expressReferralsMiddleware } from "@boltclaw/referrals/server";
+
+app.set("trust proxy", true); // behind a proxy, so req.ip is the visitor's
+app.use(expressReferralsMiddleware({ cookieDays: 30, params: ["via"] }));
+// res.locals.boltclawReferral.current is the code that counts after this request.
+```
+
+The cookie is `bc_ref=<code>; Path=/; Max-Age=<days>; SameSite=Lax`, plus `Secure` on https. It is
+not HttpOnly, on purpose: the tag reads it. Without `params`, `param` and `acceptParams: ["ref",
+"fpr"]` read the parameters the tag's `data-param` and `data-accept-params` name, as before. `bc_click` and
+`bc_sub` are handed back on the result and stored nowhere. Any other framework:
+`referralsMiddleware(options)({ url, cookie, secure, ip?, userAgent?, referrer?, country? })` returns
+the `Set-Cookie` value to send.
+
+## Verifying webhooks
+
+```ts
+import { verifyWebhook, WebhookVerificationError } from "@boltclaw/referrals/server";
+
+export async function POST(request: Request) {
+  const body = await request.text(); // the RAW body, before any JSON parsing
+  try {
+    const event = await verifyWebhook(body, request.headers, process.env.BOLTCLAW_WEBHOOK_SECRET!);
+    if (event.test) return new Response(null, { status: 204 }); // a test delivery
+    // ... handle event.event
+  } catch (error) {
+    if (error instanceof WebhookVerificationError) return new Response(null, { status: 400 });
+    throw error;
+  }
+  return new Response(null, { status: 204 });
+}
+```
+
+It checks `X-BoltClaw-Signature` (HMAC-SHA256 of `{timestamp}.{raw body}` under the endpoint's
+signing secret) in constant time and refuses a timestamp more than 300 seconds away
+(`toleranceSeconds` to change it). `error.reason` is `missing_header`, `stale`, `bad_signature` or
+`bad_body`.
+
+## Test mode
+
+`test: true` on any conversion records it as TEST data: credited to the program's test partner, never
+payable, never counted toward a limit or a total, emailing nobody, and delivered only to webhook
+endpoints that switched test events on (each test delivery carries `"test": true`). A test
+`eventId` never collides with a live one. `sendTestSale()` runs a whole one; the dashboard's "Clear
+test data" (or `DELETE /v1/referrals/programs/{id}/test-data`) deletes them.
+
+## Security model
+
+- **Mint tokens on your server.** The page never needs your API key, only a token for one user.
+- **Tokens last 1 hour by default** (60 seconds to 24 hours with `ttlSeconds`). When one runs out
+  the panel emits `expired`; mint another and call `update({ token })`.
+- **List your origins** in the dashboard. The panel can only be framed by sites on that list.
+- **The token never goes in a URL or a log.** The loader puts it in the URL fragment (never sent to
+  a server or in a Referer); the browser client sends it in an `Authorization` header. Do not log it.
+- **An API key never reaches a browser.** `ReferralsServer` refuses to start where `window` exists.
+  Errors it throws never contain the key.
+- The panel makes no request to any host but Bolt Claw. A friend's email typed into "send from my
+  own system" is handed to your page as an `inviteRequested` event and goes nowhere else.
+- Messages from the panel are accepted only from its own frame and origin, in a fixed shape.
+- **The browser never decides a discount.** The public offer read (`useOffer`) sends no cookie and
+  no credential and only shows words; `getOffer` on your server decides what Stripe applies.
+
+## Events
+
+The handler receives the payload without `source`, `version` and `type`.
+
+| Event | Payload | When |
+| --- | --- | --- |
+| `ready` | none | The first View is drawn. |
+| `resize` | `{ height }` (100 to 4000) | The content height changed; inline frames resize themselves. |
+| `copied` | `{ what: "link" }` | The referrer copied their link. |
+| `shared` | `{ channel }` | A share button, copy or QR was used. |
+| `expired` | none | The token is no longer valid; call `update({ token })`. |
+| `closed` | none | The modal closed. |
+| `error` | `{ code }` | A short stable code. |
+| `inviteRequested` | `{ email }` | Only when the program allows inviting from your own system. |
+| `dismissed` | none | "Not right now" on the thank-you card, already recorded. Hide the card. |
+
+## Errors
+
+Every failed call throws `ReferralsApiError` with `status`, `code`, `message`, `requestId`, and, on
+a 428, `approvalId` and `approvalUrl`. Match on `code`. `error.isExpired` / `isExpired(error)` is true
+for an expired panel token.
+
+| Status | `code` | Meaning |
+| --- | --- | --- |
+| 0 | `network_error` | The request could not be sent. |
+| 400 | `validation_error` and others | The input was refused; the message says why. |
+| 401 | `token_expired` (panel) | Mint a new token. For the server API, a bad or revoked key. |
+| 403 | `INSUFFICIENT_SCOPE` and others | The key lacks the scope. |
+| 409 | `CONFLICT` | For example, choosing a code for an existing referrer. |
+| 428 | `APPROVAL_REQUIRED` | A person must approve at `approvalUrl`; repeat with `approvalId`. |
+| 429 | `rate_limited` | Slow down. |
+
+## License
+
+MIT