npm - @weft-js/pay - Versions diffs - 0.1.3 → 0.1.4 - Mend

@weft-js/pay 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md CHANGED Viewed

@@ -94,7 +94,6 @@ Or let the `weft` CLI install it and add it to `weft.config.ts` in one step:
 npx weft add pay
 ```
 `weft add pay` needs a database and auth in the app, and stops without changes if either is missing. It also adds the
 Stripe rail (`@weft-js/pay/stripe`) to `plugins`, so `weft.config.ts` ends up with:
@@ -114,14 +113,14 @@ export default defineConfig({
 ### What `weft add pay` writes
-| File | What it holds |
-| --- | --- |
-| `src/pay/catalog.ts` | A `pro` subscription: `month` at `{ usd: 999 }`, `year` at `{ usd: 7999, trialDays: 7 }`, granting `pro`. Client-safe. |
-| `src/pay.server.ts` | `export default definePay({ catalog, store, urls: { success: '/', cancel: '/' } })` |
-| `src/server/pay.ts` | The `entitlements` query and the `checkout` and `portal` mutations. |
-| `src/db/pay.schema.ts` | The `purchases` and `pay_events` tables, for SQLite, Postgres or MySQL. Drizzle apps only. |
-| `src/env.server.ts` | `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` added to the `server` block. |
-| `.env`, `.env.example` | `STRIPE_SECRET_KEY=sk_test_placeholder`, `STRIPE_WEBHOOK_SECRET=whsec_placeholder` |
+| File                   | What it holds                                                                                                          |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `src/pay/catalog.ts`   | A `pro` subscription: `month` at `{ usd: 999 }`, `year` at `{ usd: 7999, trialDays: 7 }`, granting `pro`. Client-safe. |
+| `src/pay.server.ts`    | `export default definePay({ catalog, store, urls: { success: '/', cancel: '/' } })`                                    |
+| `src/server/pay.ts`    | The `entitlements` query and the `checkout` and `portal` mutations.                                                    |
+| `src/db/pay.schema.ts` | The `purchases` and `pay_events` tables, for SQLite, Postgres or MySQL. Drizzle apps only.                             |
+| `src/env.server.ts`    | `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` added to the `server` block.                                           |
+| `.env`, `.env.example` | `STRIPE_SECRET_KEY=sk_test_placeholder`, `STRIPE_WEBHOOK_SECRET=whsec_placeholder`                                     |
 On Drizzle, `src/pay.server.ts` uses `drizzlePayStore(db, { purchases, payEvents })`; then run `npx weft db generate` and
 the migration applies on the next request. On another data layer it starts on `memoryPayStore()`, and you write a
@@ -129,13 +128,13 @@ the migration applies on the next request. On another data layer it starts on `m
 ### Setup checklist
-| Need | Where | Notes |
-| --- | --- | --- |
-| A database | `weft add` refuses without one | Holds the ledger. |
-| Auth | `weft add` refuses without it | A purchase belongs to `ctx.user.id`. |
-| `STRIPE_SECRET_KEY` | `.env`, server only | Replace the placeholder with a real test key. The placeholder is refused before anything is sent (PAY003). |
-| `STRIPE_WEBHOOK_SECRET` | `.env`, server only | Without it every webhook is refused (PAY011). |
-| A Stripe webhook endpoint | Stripe dashboard | URL `https://<your-app>/_weft/x/pay/stripe`. Events: `customer.subscription.*`, `checkout.session.*`, `charge.refunded`, `charge.dispute.*`. |
+| Need                      | Where                          | Notes                                                                                                                                        |
+| ------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| A database                | `weft add` refuses without one | Holds the ledger.                                                                                                                            |
+| Auth                      | `weft add` refuses without it  | A purchase belongs to `ctx.user.id`.                                                                                                         |
+| `STRIPE_SECRET_KEY`       | `.env`, server only            | Replace the placeholder with a real test key. The placeholder is refused before anything is sent (PAY003).                                   |
+| `STRIPE_WEBHOOK_SECRET`   | `.env`, server only            | Without it every webhook is refused (PAY011).                                                                                                |
+| A Stripe webhook endpoint | Stripe dashboard               | URL `https://<your-app>/_weft/x/pay/stripe`. Events: `customer.subscription.*`, `checkout.session.*`, `charge.refunded`, `charge.dispute.*`. |
 Nothing calls Stripe until a user checks out.
@@ -221,10 +220,7 @@ export default function Pricing() {
       >
         Go Pro · {price(pro, 'year').display}
       </button>
-      <button
-        type="button"
-        onClick={() => portal()}
-      >
+      <button type="button" onClick={() => portal()}>
         Manage
       </button>
       {mine.value?.includes('pro') && <p>You have Pro.</p>}
@@ -253,16 +249,16 @@ The buyer clicks, lands on Stripe Checkout, pays, and comes back to `urls.succes
 `product(def)` checks a definition and returns it frozen. It is the only place products are defined.
-| Field | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `id` | `string` | required | Lowercase letters, digits and dashes (PAY021 otherwise). What `checkout` and `requires` name. |
-| `kind` | `'subscription' \| 'one-time' \| 'consumable'` | required | A subscription renews, a one-time purchase stays, a consumable is used up. |
-| `use` | `'digital' \| 'physical' \| 'service'` | required | What the buyer gets. |
-| `name` | `string` | the `id` | Display name at checkout. |
-| `plans` | `Record<string, Plan>` | none | Subscriptions only, and required for them. Each plan is `Amounts` plus optional `trialDays` and `interval`. |
-| `price` | `Amounts` | none | One-time and consumable products only. |
-| `grants` | `string[]` | `[]` | Entitlements a live purchase gives. |
-| `shipping` | `boolean` | `false` | Collect a shipping address at checkout. |
+| Field      | Type                                           | Default  | What it does                                                                                                |
+| ---------- | ---------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
+| `id`       | `string`                                       | required | Lowercase letters, digits and dashes (PAY021 otherwise). What `checkout` and `requires` name.               |
+| `kind`     | `'subscription' \| 'one-time' \| 'consumable'` | required | A subscription renews, a one-time purchase stays, a consumable is used up.                                  |
+| `use`      | `'digital' \| 'physical' \| 'service'`         | required | What the buyer gets.                                                                                        |
+| `name`     | `string`                                       | the `id` | Display name at checkout.                                                                                   |
+| `plans`    | `Record<string, Plan>`                         | none     | Subscriptions only, and required for them. Each plan is `Amounts` plus optional `trialDays` and `interval`. |
+| `price`    | `Amounts`                                      | none     | One-time and consumable products only.                                                                      |
+| `grants`   | `string[]`                                     | `[]`     | Entitlements a live purchase gives.                                                                         |
+| `shipping` | `boolean`                                      | `false`  | Collect a shipping address at checkout.                                                                     |
 `Amounts` is `Record<currency, number>`: lowercase ISO codes, non-negative whole minor units. `{ usd: 999 }` is $9.99.
 A plan's interval is its name when the name is `day`, `week`, `month` or `year`; any other name needs `interval`.
@@ -297,32 +293,32 @@ three) for the reader's locale. Show `price(pro, 'month').display` instead of ty
 plugin mounts it as a `server.extension` at `/_weft/x/pay/...`. An app with no `src/pay.server.ts` has no route and no code
 from any of this.
-| Option | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `catalog` | `Product[]` or `Record<string, Product>` | required | `import * as catalog from './pay/catalog'` works. |
-| `store` | `PayStore` | required | Where purchases and seen events live. |
-| `urls` | `{ success, cancel, portal? }` | required | Paths or URLs a buyer returns to. Never from the client. The portal returns to `portal`, else `cancel`. |
-| `user` | `(ctx) => string \| null \| undefined` | `ctx.user?.id` | Who a request is. |
-| `rail` | `string` | the only bound rail | Which rail takes payments when several are bound (PAY022 otherwise). |
-| `origin` | `string` | the request's origin | Absolute origin for `urls`, behind a proxy. |
-| `leeway` | `number` (ms) | 3 days | How long past a paid period access lasts, while a late renewal event arrives. |
-| `slot` | `() => Promise<…>` | `weft:slot/pay.rail` | Where rails come from. Leave it alone outside tests. |
+| Option    | Type                                     | Default              | What it does                                                                                            |
+| --------- | ---------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------- |
+| `catalog` | `Product[]` or `Record<string, Product>` | required             | `import * as catalog from './pay/catalog'` works.                                                       |
+| `store`   | `PayStore`                               | required             | Where purchases and seen events live.                                                                   |
+| `urls`    | `{ success, cancel, portal? }`           | required             | Paths or URLs a buyer returns to. Never from the client. The portal returns to `portal`, else `cancel`. |
+| `user`    | `(ctx) => string \| null \| undefined`   | `ctx.user?.id`       | Who a request is.                                                                                       |
+| `rail`    | `string`                                 | the only bound rail  | Which rail takes payments when several are bound (PAY022 otherwise).                                    |
+| `origin`  | `string`                                 | the request's origin | Absolute origin for `urls`, behind a proxy.                                                             |
+| `leeway`  | `number` (ms)                            | 3 days               | How long past a paid period access lasts, while a late renewal event arrives.                           |
+| `slot`    | `() => Promise<…>`                       | `weft:slot/pay.rail` | Where rails come from. Leave it alone outside tests.                                                    |
 What it returns, besides the `server.extension` members Weft uses:
-| Member | What it does |
-| --- | --- |
-| `pay.input` | A Standard Schema validator for a checkout mutation's `input`: `{ product, plan?, currency?, quantity? }`, checked against the catalog. `quantity` is a whole number under 1000. |
-| `pay.checkout(ctx, input)` | The hosted checkout URL for this buyer. Grants nothing. |
-| `pay.portal(ctx)` | Where this buyer manages or cancels. |
-| `pay.entitlements(userId)` | `{ has(id), list() }` for any user, as a job or webhook would read it. |
-| `pay.forContext(ctx)` | The same, for a request: what `ctx.entitlements` is. |
-| `pay.purchases(userId)` | The user's `Purchase` rows. |
-| `pay.refund(purchaseId)` | Asks the purchase's rail to refund it. |
-| `pay.webhook(rail, request, report?)` | One verified delivery: `{ response, tags }`. |
-| `pay.ingest(rail, events, report?)` | Apply events that were already verified. Anything else goes through `webhook`. |
-| `pay.use(rail)` / `pay.reset()` | Swap in a rail directly (what `fakePay` does), and go back to the slot. |
-| `pay.catalog` | The products, as a list. |
+| Member                                | What it does                                                                                                                                                                     |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pay.input`                           | A Standard Schema validator for a checkout mutation's `input`: `{ product, plan?, currency?, quantity? }`, checked against the catalog. `quantity` is a whole number under 1000. |
+| `pay.checkout(ctx, input)`            | The hosted checkout URL for this buyer. Grants nothing.                                                                                                                          |
+| `pay.portal(ctx)`                     | Where this buyer manages or cancels.                                                                                                                                             |
+| `pay.entitlements(userId)`            | `{ has(id), list() }` for any user, as a job or webhook would read it.                                                                                                           |
+| `pay.forContext(ctx)`                 | The same, for a request: what `ctx.entitlements` is.                                                                                                                             |
+| `pay.purchases(userId)`               | The user's `Purchase` rows.                                                                                                                                                      |
+| `pay.refund(purchaseId)`              | Asks the purchase's rail to refund it.                                                                                                                                           |
+| `pay.webhook(rail, request, report?)` | One verified delivery: `{ response, tags }`.                                                                                                                                     |
+| `pay.ingest(rail, events, report?)`   | Apply events that were already verified. Anything else goes through `webhook`.                                                                                                   |
+| `pay.use(rail)` / `pay.reset()`       | Swap in a rail directly (what `fakePay` does), and go back to the slot.                                                                                                          |
+| `pay.catalog`                         | The products, as a list.                                                                                                                                                         |
 ## Checkout, portal and webhooks
@@ -336,14 +332,14 @@ PAY024 (404).
 **Webhooks.** The rail posts to `/_weft/x/pay/<rail>`. For each delivery:
-| Step | Result |
-| --- | --- |
-| Not a `POST` | 405 |
-| No rail bound under that name | 404 |
-| Body over 1 MiB | 413 |
-| `verify` throws (bad or missing signature, a replay) | 400, and the reason goes to the server log, not the response |
-| `ingest` fails | 500, so the rail delivers it again |
-| Otherwise | `{"received":true}`, and the affected `entitlements:<user>` tags are invalidated |
+| Step                                                 | Result                                                                           |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Not a `POST`                                         | 405                                                                              |
+| No rail bound under that name                        | 404                                                                              |
+| Body over 1 MiB                                      | 413                                                                              |
+| `verify` throws (bad or missing signature, a replay) | 400, and the reason goes to the server log, not the response                     |
+| `ingest` fails                                       | 500, so the rail delivers it again                                               |
+| Otherwise                                            | `{"received":true}`, and the affected `entitlements:<user>` tags are invalidated |
 An event applies when it is newer than the purchase's last one by the rail's clock. On a tie, a terminal state wins: a
 refund and a renewal in the same second is a refund. The event id is recorded after the purchase is saved, so a crash in
@@ -353,10 +349,10 @@ between means a redelivery, not a lost event.
 The same on every rail:
-| State | Gives access |
-| --- | --- |
-| `active`, `trial`, `grace` | Yes, until `expires` plus `leeway` |
-| `pending`, `billing-retry`, `paused`, `expired`, `refunded`, `revoked` | No |
+| State                                                                  | Gives access                       |
+| ---------------------------------------------------------------------- | ---------------------------------- |
+| `active`, `trial`, `grace`                                             | Yes, until `expires` plus `leeway` |
+| `pending`, `billing-retry`, `paused`, `expired`, `refunded`, `revoked` | No                                 |
 ## Entitlements
@@ -370,12 +366,12 @@ import { redirect } from '@weft-js/start'
 if (!(await ctx.entitlements.has('pro'))) redirect('/pricing')
 ```
-| Way | Where | What happens without the entitlement |
-| --- | --- | --- |
-| `requires: ['pro']` | any `query` or `mutation` | A 403 with code `ENTITLEMENT_REQUIRED` |
-| `await ctx.entitlements.has(id)` | `query`, `mutation`, `load` | Whatever you do: redirect, hide, refuse |
-| `await ctx.entitlements.list()` | same | The sorted list |
-| `entitlementTag(userId)` | a query's `tags` | The tag a verified event invalidates: `entitlements:<user>` |
+| Way                              | Where                       | What happens without the entitlement                        |
+| -------------------------------- | --------------------------- | ----------------------------------------------------------- |
+| `requires: ['pro']`              | any `query` or `mutation`   | A 403 with code `ENTITLEMENT_REQUIRED`                      |
+| `await ctx.entitlements.has(id)` | `query`, `mutation`, `load` | Whatever you do: redirect, hide, refuse                     |
+| `await ctx.entitlements.list()`  | same                        | The sorted list                                             |
+| `entitlementTag(userId)`         | a query's `tags`            | The tag a verified event invalidates: `entitlements:<user>` |
 What the client shows is decoration; a check only on the client is PAY013. A query with `cache: { life }` needs
 `scope: 'user'` to read entitlements.
@@ -386,13 +382,13 @@ What the client shows is decoration; a check only on the client is PAY013. A que
 Checkout and the billing portal over Stripe's REST API, server side only, and verifies webhooks itself with WebCrypto
 HMAC-SHA256 on `<t>.<raw body>`, accepting any of several `v1` signatures while a secret rolls.
-| Option | Type | Default | What it does |
-| --- | --- | --- | --- |
-| `prices` | `Record<string, string>` | none | Stripe Price ids by `<product>.<plan>` or `<product>`. Without an entry the amount comes from the catalog as `price_data`. |
-| `api` | `string` | `https://api.stripe.com` | The API origin; point it at a local mock. |
-| `apiVersion` | `string` | `2025-09-30.clover` | Pinned, so an account's default version can't reshape the calls. |
-| `tolerance` | `number` (s) | `300` | How old a signed delivery may be before it is refused as a replay. |
-| `shippingCountries` | `string[]` | `['US', 'CA']` | Where a `shipping` product delivers. |
+| Option              | Type                     | Default                  | What it does                                                                                                               |
+| ------------------- | ------------------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `prices`            | `Record<string, string>` | none                     | Stripe Price ids by `<product>.<plan>` or `<product>`. Without an entry the amount comes from the catalog as `price_data`. |
+| `api`               | `string`                 | `https://api.stripe.com` | The API origin; point it at a local mock.                                                                                  |
+| `apiVersion`        | `string`                 | `2025-09-30.clover`      | Pinned, so an account's default version can't reshape the calls.                                                           |
+| `tolerance`         | `number` (s)             | `300`                    | How old a signed delivery may be before it is refused as a replay.                                                         |
+| `shippingCountries` | `string[]`               | `['US', 'CA']`           | Where a `shipping` product delivers.                                                                                       |
 Keys come from the server environment, `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET`. Don't pass a key as an option:
 plugin options are written into `.weft/slots/`, a generated file (PAY003).
@@ -415,12 +411,12 @@ export default defineConfig({
 How Stripe events map to the ledger:
-| Stripe event | Ledger effect |
-| --- | --- |
-| `customer.subscription.*` | `active`, `trialing` → `trial`, `past_due` → `grace`, `unpaid` → `billing-retry`, `paused`, `canceled` and `incomplete_expired` → `expired`, `incomplete` → `pending`; `expires` from the period end |
-| `checkout.session.completed`, `…async_payment_succeeded`, `…async_payment_failed` | One-time payments only: `active`, `pending` while unpaid, or `expired` on failure |
-| `charge.refunded` | `refunded`, for a full refund only; a partial refund keeps what was bought |
-| `charge.dispute.created` / `.closed` | `revoked`, then `active` again if the dispute is won |
+| Stripe event                                                                      | Ledger effect                                                                                                                                                                                        |
+| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `customer.subscription.*`                                                         | `active`, `trialing` → `trial`, `past_due` → `grace`, `unpaid` → `billing-retry`, `paused`, `canceled` and `incomplete_expired` → `expired`, `incomplete` → `pending`; `expires` from the period end |
+| `checkout.session.completed`, `…async_payment_succeeded`, `…async_payment_failed` | One-time payments only: `active`, `pending` while unpaid, or `expired` on failure                                                                                                                    |
+| `charge.refunded`                                                                 | `refunded`, for a full refund only; a partial refund keeps what was bought                                                                                                                           |
+| `charge.dispute.created` / `.closed`                                              | `revoked`, then `active` again if the dispute is won                                                                                                                                                 |
 Who bought what travels in metadata (`weft_user`, `weft_product`, `weft_plan`) on the session, the subscription and the
 payment intent. `pay.refund()` refunds one-time payments (`pi_…`); a subscription is cancelled in the portal.
@@ -429,13 +425,13 @@ payment intent. `pay.refund()` refunds one-time payments (`pi_…`); a subscript
 A `PayStore` is five methods:
-| Method | What it does |
-| --- | --- |
-| `seen(eventId)` | Whether an event was already applied. |
-| `mark(eventId, at)` | Record that it was. |
-| `purchase(id)` | One `Purchase` by id, or `null`. |
-| `save(purchase)` | Insert or replace by `id`. |
-| `byUser(user)` | Every purchase of a user. |
+| Method              | What it does                          |
+| ------------------- | ------------------------------------- |
+| `seen(eventId)`     | Whether an event was already applied. |
+| `mark(eventId, at)` | Record that it was.                   |
+| `purchase(id)`      | One `Purchase` by id, or `null`.      |
+| `save(purchase)`    | Insert or replace by `id`.            |
+| `byUser(user)`      | Every purchase of a user.             |
 `drizzlePayStore(db, { purchases, payEvents })` from `@weft-js/pay/drizzle` implements it on Postgres, SQLite or MySQL, with
 the tables `weft add pay` writes (times are milliseconds, so they need a 64-bit integer column on Postgres and MySQL). It
@@ -450,13 +446,13 @@ and `user`, `product` and `plan` stay `null` until an event names them (a disput
 A rail is a plugin that provides the `pay.rail` slot for the `server` side and implements `PayRail` from `@weft-js/pay`:
-| Member | What it does |
-| --- | --- |
-| `id` | The rail's name, and its webhook path: `/_weft/x/pay/<id>`. |
-| `checkout(request)` | Open a hosted page for a `CheckoutRequest` (user, optional customer, the catalog line, return URLs, an idempotency key). Returns `{ url }`. |
-| `portal({ customer, returnUrl })` | Returns `{ url }`. |
-| `verify({ body, headers })` | Gets the exact bytes received and returns normalised `RailEvent`s, or throws `PayError('PAY011', …)` for anything it can't prove. |
-| `refund({ purchase })` | Optional. |
+| Member                            | What it does                                                                                                                                |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`                              | The rail's name, and its webhook path: `/_weft/x/pay/<id>`.                                                                                 |
+| `checkout(request)`               | Open a hosted page for a `CheckoutRequest` (user, optional customer, the catalog line, return URLs, an idempotency key). Returns `{ url }`. |
+| `portal({ customer, returnUrl })` | Returns `{ url }`.                                                                                                                          |
+| `verify({ body, headers })`       | Gets the exact bytes received and returns normalised `RailEvent`s, or throws `PayError('PAY011', …)` for anything it can't prove.           |
+| `refund({ purchase })`            | Optional.                                                                                                                                   |
 Hold it to the contract with `payRailSuite` from `@weft-js/pay/test`:
@@ -509,31 +505,31 @@ test('checkout grants nothing; the verified event does', async () => {
 })
 ```
-| Member | What it does |
-| --- | --- |
-| `complete(user?)` | The buyer finishes the newest open checkout, or that user's. Returns the purchase id. |
-| `abandon(user?)` | The buyer closes the page. Nothing is delivered. |
-| `buy(user, product, plan?)` | A whole purchase with no page in the way. |
-| `simulate(what, purchase?)` | `renewal`, `renewal-failed`, `grace-expired`, `recovered`, `cancel`, `pause`, `resume`, `refund`, `revoke`. Defaults to the newest purchase. `renewal` and `renewal-failed` move `clock` to the period's end when it is installed. |
-| `redeliver()` | The last event again. |
-| `deliver(event, { forged? })` | Any event, in any order. `forged: true` signs with the wrong key, so it answers 400. |
-| `sessions`, `deliveries` | Every checkout opened, and every delivery with the status the app answered. |
-| `entitlements(user)`, `purchases(user)` | Read the ledger. |
-| `pay`, `rail` | The ledger in use and the fake rail. |
+| Member                                  | What it does                                                                                                                                                                                                                       |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `complete(user?)`                       | The buyer finishes the newest open checkout, or that user's. Returns the purchase id.                                                                                                                                              |
+| `abandon(user?)`                        | The buyer closes the page. Nothing is delivered.                                                                                                                                                                                   |
+| `buy(user, product, plan?)`             | A whole purchase with no page in the way.                                                                                                                                                                                          |
+| `simulate(what, purchase?)`             | `renewal`, `renewal-failed`, `grace-expired`, `recovered`, `cancel`, `pause`, `resume`, `refund`, `revoke`. Defaults to the newest purchase. `renewal` and `renewal-failed` move `clock` to the period's end when it is installed. |
+| `redeliver()`                           | The last event again.                                                                                                                                                                                                              |
+| `deliver(event, { forged? })`           | Any event, in any order. `forged: true` signs with the wrong key, so it answers 400.                                                                                                                                               |
+| `sessions`, `deliveries`                | Every checkout opened, and every delivery with the status the app answered.                                                                                                                                                        |
+| `entitlements(user)`, `purchases(user)` | Read the ledger.                                                                                                                                                                                                                   |
+| `pay`, `rail`                           | The ledger in use and the fake rail.                                                                                                                                                                                               |
 `fakePay` registers the ledger with `net.extension`, which resets it after each test. A live key in a test is PAY031.
 ## API reference
-| Entry | Side | Exports |
-| --- | --- | --- |
-| `@weft-js/pay` | client and server | `product`, `price`, `entitlementTag`, `PayError`; types `Product`, `ProductDef`, `ProductKind`, `ProductUse`, `Plan`, `Amounts`, `Interval`, `Price`, `PurchaseState`, `PayRail`, `RailEvent`, `CheckoutRequest`, `CheckoutLine` |
-| `@weft-js/pay/server` | server | `definePay`, `memoryPayStore`, `extension`; types `Pay`, `PayOptions`, `PayStore`, `Purchase`, `Entitlements`, `CheckoutInput`, `PayContext`, `PayReport` |
-| `@weft-js/pay/drizzle` | server | `drizzlePayStore` |
-| `@weft-js/pay/test` | tests | `fakePay`, `payRailSuite`; types `FakePay`, `PayScenario`, `PayRailSuiteOptions`, `Check` |
-| `@weft-js/pay/plugin` | config | `pay` (default and named): the `server.extension`, the PAY checks, `weft docs pay` and `weft add pay` |
-| `@weft-js/pay/stripe` | server | `stripeRail`; type `StripeOptions` |
-| `@weft-js/pay/stripe/plugin` | config | `stripe` (default and named): the `pay.rail` provider |
+| Entry                        | Side              | Exports                                                                                                                                                                                                                          |
+| ---------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@weft-js/pay`               | client and server | `product`, `price`, `entitlementTag`, `PayError`; types `Product`, `ProductDef`, `ProductKind`, `ProductUse`, `Plan`, `Amounts`, `Interval`, `Price`, `PurchaseState`, `PayRail`, `RailEvent`, `CheckoutRequest`, `CheckoutLine` |
+| `@weft-js/pay/server`        | server            | `definePay`, `memoryPayStore`, `extension`; types `Pay`, `PayOptions`, `PayStore`, `Purchase`, `Entitlements`, `CheckoutInput`, `PayContext`, `PayReport`                                                                        |
+| `@weft-js/pay/drizzle`       | server            | `drizzlePayStore`                                                                                                                                                                                                                |
+| `@weft-js/pay/test`          | tests             | `fakePay`, `payRailSuite`; types `FakePay`, `PayScenario`, `PayRailSuiteOptions`, `Check`                                                                                                                                        |
+| `@weft-js/pay/plugin`        | config            | `pay` (default and named): the `server.extension`, the PAY checks, `weft docs pay` and `weft add pay`                                                                                                                            |
+| `@weft-js/pay/stripe`        | server            | `stripeRail`; type `StripeOptions`                                                                                                                                                                                               |
+| `@weft-js/pay/stripe/plugin` | config            | `stripe` (default and named): the `pay.rail` provider                                                                                                                                                                            |
 Importing `@weft-js/pay/server` or `@weft-js/pay/drizzle` from client code is PAY017.
@@ -609,44 +605,44 @@ amount; `price(pro, 'month', { currency: 'eur' }).display` shows it.
 `weft check` and `weft build` run the PAY checks. `weft docs PAY012` prints any code's page.
-| Code | When | Fix |
-| --- | --- | --- |
-| PAY003 | A Stripe key in source, a server secret read in client code, a key in plugin options, or the placeholder key still in `.env` at run time | Move it to the server env; roll any real key that was committed |
-| PAY004 | Paid state written on the client after `checkout()` | Read `entitlements`: a grant arrives from a verified event |
-| PAY005 | A price typed into a page that sells something (warning) | `price(product, plan).display` |
-| PAY008 | A float or currency-less amount in `product()` | Whole minor units: `{ usd: 999 }` |
-| PAY010 | A checkout mutation without `auth: 'user'`, or a checkout with no signed-in user (401) | Add `auth: 'user'` |
+| Code   | When                                                                                                                                                  | Fix                                                                |
+| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| PAY003 | A Stripe key in source, a server secret read in client code, a key in plugin options, or the placeholder key still in `.env` at run time              | Move it to the server env; roll any real key that was committed    |
+| PAY004 | Paid state written on the client after `checkout()`                                                                                                   | Read `entitlements`: a grant arrives from a verified event         |
+| PAY005 | A price typed into a page that sells something (warning)                                                                                              | `price(product, plan).display`                                     |
+| PAY008 | A float or currency-less amount in `product()`                                                                                                        | Whole minor units: `{ usd: 999 }`                                  |
+| PAY010 | A checkout mutation without `auth: 'user'`, or a checkout with no signed-in user (401)                                                                | Add `auth: 'user'`                                                 |
 | PAY011 | A webhook handler with no signature check, a `verify` that ignores `headers`, no `STRIPE_WEBHOOK_SECRET`, or a delivery that fails verification (400) | Delete the handler: `/_weft/x/pay/<rail>` verifies. Set the secret |
-| PAY012 | A rail's price or product id in client code | Name the catalog; map ids in `stripe({ prices })` |
-| PAY013 | An entitlement checked only on the client | `requires: [...]`, or `await ctx.entitlements.has(...)` |
-| PAY014 | The plugin with no `src/pay.server.ts`: no webhook is mounted | Default-export `definePay({ … })` from it |
-| PAY015 | `ctx.entitlements.has()` without `await` | Await it (`weft fix` does, in an `async` function) |
-| PAY016 | `memoryPayStore()` in `src/pay.server.ts` (warning); a production server refuses to start | `drizzlePayStore` or your own `PayStore` |
-| PAY017 | `@weft-js/pay/server` or `/drizzle` imported in client code | Import them in a server module |
-| PAY018 | `src/pay.server.ts` with no `pay.rail` provider | `weft add pay-stripe` |
-| PAY031 | A live key in a test | `fakePay` |
+| PAY012 | A rail's price or product id in client code                                                                                                           | Name the catalog; map ids in `stripe({ prices })`                  |
+| PAY013 | An entitlement checked only on the client                                                                                                             | `requires: [...]`, or `await ctx.entitlements.has(...)`            |
+| PAY014 | The plugin with no `src/pay.server.ts`: no webhook is mounted                                                                                         | Default-export `definePay({ … })` from it                          |
+| PAY015 | `ctx.entitlements.has()` without `await`                                                                                                              | Await it (`weft fix` does, in an `async` function)                 |
+| PAY016 | `memoryPayStore()` in `src/pay.server.ts` (warning); a production server refuses to start                                                             | `drizzlePayStore` or your own `PayStore`                           |
+| PAY017 | `@weft-js/pay/server` or `/drizzle` imported in client code                                                                                           | Import them in a server module                                     |
+| PAY018 | `src/pay.server.ts` with no `pay.rail` provider                                                                                                       | `weft add pay-stripe`                                              |
+| PAY031 | A live key in a test                                                                                                                                  | `fakePay`                                                          |
 At run time:
-| Code | Status | Means |
-| --- | --- | --- |
-| PAY021 | 404 | No such product, plan or currency in the catalog (also thrown by `product()` for a bad definition) |
-| PAY022 | 500 / 501 / 400 | No rail chosen while several are bound, a named rail isn't bound, or the rail can't refund this purchase |
-| PAY023 | 409 | The user already holds this subscription |
-| PAY024 | 404 | Nothing to manage or refund |
-| PAY030 | 502 / 503 | Stripe refused the call (503 when it rate-limited) |
-| P101 | 500 | `pay.rail` has no provider in `plugins` |
-| `ENTITLEMENT_REQUIRED` | 403 | A `requires` entitlement is missing |
-| `E_PAY` | 500 | Applying a verified delivery failed; the rail will redeliver |
+| Code                   | Status          | Means                                                                                                    |
+| ---------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
+| PAY021                 | 404             | No such product, plan or currency in the catalog (also thrown by `product()` for a bad definition)       |
+| PAY022                 | 500 / 501 / 400 | No rail chosen while several are bound, a named rail isn't bound, or the rail can't refund this purchase |
+| PAY023                 | 409             | The user already holds this subscription                                                                 |
+| PAY024                 | 404             | Nothing to manage or refund                                                                              |
+| PAY030                 | 502 / 503       | Stripe refused the call (503 when it rate-limited)                                                       |
+| P101                   | 500             | `pay.rail` has no provider in `plugins`                                                                  |
+| `ENTITLEMENT_REQUIRED` | 403             | A `requires` entitlement is missing                                                                      |
+| `E_PAY`                | 500             | Applying a verified delivery failed; the rail will redeliver                                             |
 ## Related packages
-| Package | What it is |
-| --- | --- |
+| Package                                                          | What it is                                                                      |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------- |
 | [`@weft-js/start`](https://www.npmjs.com/package/@weft-js/start) | Server functions, `ctx`, `server.extension` and live queries that pay builds on |
-| [`@weft-js/core`](https://www.npmjs.com/package/@weft-js/core) | The plugin API (`definePlugin`, slots) and the test kit (`net`, `clock`) |
-| [`@weft-js/db`](https://www.npmjs.com/package/@weft-js/db) | The database layer `drizzlePayStore` runs on |
-| [`@weft-js/cli`](https://www.npmjs.com/package/@weft-js/cli) | `weft add pay`, `weft check`, `weft docs pay` and `weft docs plugins` |
+| [`@weft-js/core`](https://www.npmjs.com/package/@weft-js/core)   | The plugin API (`definePlugin`, slots) and the test kit (`net`, `clock`)        |
+| [`@weft-js/db`](https://www.npmjs.com/package/@weft-js/db)       | The database layer `drizzlePayStore` runs on                                    |
+| [`@weft-js/cli`](https://www.npmjs.com/package/@weft-js/cli)     | `weft add pay`, `weft check`, `weft docs pay` and `weft docs plugins`           |
 ## Contributing

package/docs/pay.md CHANGED Viewed

@@ -22,6 +22,7 @@ export const pro = product({
 ```
 <!-- example: skip needs what `weft add pay` writes -->
 ```tsx
 // a page
 import { price } from '@weft-js/pay'
@@ -56,9 +57,15 @@ verified on the exact bytes, applied to `purchases`, and pokes `entitlements:<us
 Delivery is at least once and in any order: a repeat is a no-op, and an old event changes nothing, by the rail's own clock.
 A bad signature answers 400; a failure answers 500, so the rail delivers it again.
+**A cart the server prices.** `pay.order(ctx, { ref, lines: [{ name, amount, quantity? }], currency?, email?, title? })`
+opens one payment for lines your server priced from its own tables, for a guest or a signed-in buyer. It grants nothing.
+`definePay({ onOrder({ ref, state, purchase }) })` hears each verified state, before the event is marked, so a throw
+redelivers. Each order event pokes `orders` and `orderTag(ref)`. `urls.order` and `urls.orderCancel` may hold `{ref}`.
 **Enforce on the server.** What the client shows is decoration (PAY013):
 <!-- example: skip fragments of a server module -->
 ```ts
 export const report = query({
   auth: 'user',
@@ -87,6 +94,11 @@ changes. A rail implements `PayRail` from `@weft-js/pay`: `checkout`, `portal`,
 `PayError('PAY011', …)` for anything it can't prove. An app with no `src/pay.server.ts` has no route and no code from any
 of this.
+`square({ environment?, api?, apiVersion? })` from `@weft-js/pay/square/plugin` is the Square rail: one-time payments
+through payment links, so web orders land beside the shop's card readers. Env: `SQUARE_ACCESS_TOKEN`, `SQUARE_LOCATION_ID`,
+`SQUARE_WEBHOOK_SIGNATURE_KEY`, `SQUARE_WEBHOOK_URL` (the exact URL given to Square, which it signs), `SQUARE_ENV=sandbox`.
+Subscribe the webhook to `payment.created` and `payment.updated`. Subscriptions and `portal` are PAY022 on it.
 `stripe({ prices?, api?, apiVersion?, tolerance?, shippingCountries? })` from `@weft-js/pay/stripe/plugin`. It reads
 `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET` from the server env. Don't put a key in its options: they land in a
 generated file (PAY003).
@@ -116,22 +128,22 @@ installed. `fake.redeliver()`, `fake.deliver(event, { forged: true })`, `fake.de
 ## Diagnostics
-| Code | Catches |
-|---|---|
-| PAY003 | A key in the source, or a server secret in client code |
-| PAY004 | Paid state written on the client after `checkout()` |
-| PAY005 | A price typed into a page that sells something (warning) |
-| PAY008 | A float or a currency-less amount in `product()` |
-| PAY010 | A checkout mutation without `auth: 'user'` |
-| PAY011 | A webhook left unverified, or no `STRIPE_WEBHOOK_SECRET` |
-| PAY012 | A rail's price or product id in client code |
-| PAY013 | An entitlement checked only on the client |
-| PAY014 | A rail bound with no `src/pay.server.ts` |
-| PAY015 | `ctx.entitlements.has()` tested without `await` |
-| PAY016 | `memoryPayStore()` in `src/pay.server.ts` (warning) |
+| Code   | Catches                                                     |
+| ------ | ----------------------------------------------------------- |
+| PAY003 | A key in the source, or a server secret in client code      |
+| PAY004 | Paid state written on the client after `checkout()`         |
+| PAY005 | A price typed into a page that sells something (warning)    |
+| PAY008 | A float or a currency-less amount in `product()`            |
+| PAY010 | A checkout mutation without `auth: 'user'`                  |
+| PAY011 | A webhook left unverified, or no `STRIPE_WEBHOOK_SECRET`    |
+| PAY012 | A rail's price or product id in client code                 |
+| PAY013 | An entitlement checked only on the client                   |
+| PAY014 | A rail bound with no `src/pay.server.ts`                    |
+| PAY015 | `ctx.entitlements.has()` tested without `await`             |
+| PAY016 | `memoryPayStore()` in `src/pay.server.ts` (warning)         |
 | PAY017 | `@weft-js/pay/server` or `/drizzle` imported in client code |
-| PAY018 | `src/pay.server.ts` with no `pay.rail` provider |
-| PAY031 | A live key in a test |
+| PAY018 | `src/pay.server.ts` with no `pay.rail` provider             |
+| PAY031 | A live key in a test                                        |
 At run time: PAY021 (not in the catalog), PAY022 (no rail chosen), PAY023 (already subscribed, 409), PAY024 (nothing to
 manage or refund), PAY030 (the rail refused). Native rails, store policy and `weft pay sync` aren't built.

package/package.json CHANGED Viewed

@@ -1,27 +1,20 @@
 {
   "name": "@weft-js/pay",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "@weft-js/pay: products, one ledger for every rail, and entitlements. weft's reference plugin: read it to build your own",
+  "keywords": [
+    "weft"
+  ],
+  "homepage": "https://github.com/Ravonus/weft/tree/main/packages/pay#readme",
+  "bugs": {
+    "url": "https://github.com/Ravonus/weft/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Ravonus/weft.git",
     "directory": "packages/pay"
   },
-  "homepage": "https://github.com/Ravonus/weft/tree/main/packages/pay#readme",
-  "bugs": {
-    "url": "https://github.com/Ravonus/weft/issues"
-  },
-  "type": "module",
-  "exports": {
-    ".": "./src/index.ts",
-    "./server": "./src/server.ts",
-    "./drizzle": "./src/drizzle.ts",
-    "./test": "./src/test.ts",
-    "./plugin": "./plugin.mjs",
-    "./stripe": "./src/stripe.ts",
-    "./stripe/plugin": "./stripe-plugin.mjs"
-  },
   "files": [
     "src",
     "docs",
@@ -30,15 +23,32 @@
     "stripe-plugin.mjs",
     "stripe-plugin.d.mts",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "square-plugin.mjs",
+    "square-plugin.d.mts"
   ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts",
+    "./drizzle": "./src/drizzle.ts",
+    "./test": "./src/test.ts",
+    "./plugin": "./plugin.mjs",
+    "./stripe": "./src/stripe.ts",
+    "./stripe/plugin": "./stripe-plugin.mjs",
+    "./square": "./src/square.ts",
+    "./square/plugin": "./square-plugin.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "dependencies": {
     "typescript": "6.0.3"
   },
   "peerDependencies": {
-    "@weft-js/start": "^0.1.3",
-    "drizzle-orm": "^0.45.0",
-    "@weft-js/core": "^0.1.3"
+    "@weft-js/core": "^0.1.4",
+    "@weft-js/start": "^0.1.4",
+    "drizzle-orm": "^0.45.0"
   },
   "peerDependenciesMeta": {
     "drizzle-orm": {
@@ -46,12 +56,6 @@
     }
   },
   "engines": {
-    "node": ">=26"
-  },
-  "keywords": [
-    "weft"
-  ],
-  "publishConfig": {
-    "access": "public"
+    "node": ">=24"
   }
 }

package/square-plugin.d.mts ADDED Viewed

@@ -0,0 +1,9 @@
+import type { PluginInstance } from '@weft-js/core/plugin'
+declare const plugin: (options?: {
+  environment?: 'sandbox' | 'production'
+  api?: string
+  apiVersion?: string
+}) => PluginInstance<unknown>
+/** `square()` for `weft.config.ts`: Square as a `pay.rail` provider. Tokens stay in the environment. */
+export default plugin

package/square-plugin.mjs ADDED Viewed

@@ -0,0 +1,47 @@
+// square() for weft.config.ts: Square as the `pay.rail` provider, so web orders land in the same account as the shop's
+// card readers. Options are in the generated slot module, so they name env vars and never hold a token (PAY003).
+import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
+const slot = defineSlot({
+  id: 'pay.rail',
+  version: 1,
+  cardinality: 'keyed',
+  sides: ['server', 'client', 'native'],
+})
+export const square = definePlugin({
+  name: '@weft-js/pay/square',
+  version: '0.0.0',
+  weft: '*',
+  permissions: {
+    net: ['connect.squareup.com', 'connect.squareupsandbox.com'],
+    env: [
+      'SQUARE_ACCESS_TOKEN',
+      'SQUARE_LOCATION_ID',
+      'SQUARE_WEBHOOK_SIGNATURE_KEY',
+      'SQUARE_WEBHOOK_URL',
+      'SQUARE_ENV',
+    ],
+  },
+  contribute: (options) => ({
+    provides: [
+      provide(slot, {
+        key: 'square',
+        sides: { server: { module: '@weft-js/pay/square', export: 'squareRail', options } },
+      }),
+    ],
+    agents: {
+      title: 'Pay rail: Square',
+      text: 'Square payment links, one-time payments only (`pay.order`, one-time products): `SQUARE_ACCESS_TOKEN`, `SQUARE_LOCATION_ID`, and for `/_weft/x/pay/square` (subscribe it to `payment.created` and `payment.updated`) `SQUARE_WEBHOOK_SIGNATURE_KEY` plus `SQUARE_WEBHOOK_URL`, the exact URL given to Square. `SQUARE_ENV=sandbox` for test.',
+    },
+    map: [
+      {
+        want: 'Change the payment provider',
+        call: 'replace this plugin in `plugins`: app code stays',
+        have: 'Square payment links',
+      },
+    ],
+  }),
+})
+export default square

package/src/index.ts CHANGED Viewed

@@ -163,6 +163,9 @@ export function price<P extends string>(
 /** What a query reads, tagged so a verified event pokes it: `tags: (_, ctx) => [entitlementTag(ctx.user.id)]`. */
 export const entitlementTag = (user: string) => `entitlements:${user}`
+/** What a verified event pokes for one order: `tags: (input) => [orderTag(input.ref)]`. Every order also pokes `orders`. */
+export const orderTag = (ref: string) => `order:${ref}`
 // ---- pay.rail@1 ---------------------------------------------------------------------------------------------------
 /** What a purchase is doing now, on any rail. */
@@ -198,6 +201,10 @@ export interface CheckoutRequest {
   /** This user's id on the rail, when a purchase gave one. */
   customer?: string
   line: CheckoutLine
+  /** An order's own lines, priced on the server (`pay.order`): charged in place of `line`, which sums them. */
+  lines?: readonly CheckoutLine[]
+  /** A guest's email, for the receipt, when the rail has no customer for them. */
+  email?: string
   successUrl: string
   cancelUrl: string
   /** The same click twice gives one session. */
@@ -228,6 +235,8 @@ export interface RailEvent {
  */
 export interface PayRail {
   readonly id: string
+  /** What it can sell. Default both; a rail without `subscription` has no portal to offer. */
+  readonly modes?: readonly ('payment' | 'subscription')[]
   checkout(request: CheckoutRequest): Promise<{ url: string }>
   /** Where a buyer manages or cancels. */
   portal(request: { customer: string; returnUrl: string }): Promise<{ url: string }>

package/src/server/ledger.ts CHANGED Viewed

@@ -1,14 +1,23 @@
-import { entitlementTag, type Product, type PurchaseState, type RailEvent } from '../index'
-import type { Entitlements, PayReport, PayStore, Purchase } from '../server'
+import {
+  entitlementTag,
+  orderTag,
+  type Product,
+  type PurchaseState,
+  type RailEvent,
+} from '../index'
+import type { Entitlements, OrderHook, PayReport, PayStore, Purchase } from '../server'
 const ACCESS: ReadonlySet<PurchaseState> = new Set(['active', 'trial', 'grace'])
 const FINAL: ReadonlySet<PurchaseState> = new Set(['refunded', 'revoked'])
+/** The product id every `pay.order` is recorded under; its plan is the app's order ref. */
+export const ORDER = 'order'
 /** Derive access and apply verified events against one store. */
 export function makeLedger<P extends Product>(
   store: PayStore,
   byId: Map<string, P>,
   leeway: number,
+  onOrder?: OrderHook,
 ) {
   const live = (p: Purchase) =>
     ACCESS.has(p.state) && (p.expires === null || Date.now() < p.expires + leeway)
@@ -27,7 +36,7 @@ export function makeLedger<P extends Product>(
   }
   /** One event onto its purchase. Identity always merges; state moves only forward on the rail's clock. */
-  async function apply(rail: string, e: RailEvent, report?: PayReport): Promise<string | null> {
+  async function apply(rail: string, e: RailEvent, report?: PayReport): Promise<string[]> {
     const id = `${rail}:${e.purchase}`
     const had = await store.purchase(id)
     const newer =
@@ -44,13 +53,19 @@ export function makeLedger<P extends Product>(
       expires: newer ? (e.expires ?? had?.expires ?? null) : had.expires,
     }
     await store.save(next)
+    // An order (`pay.order`) grants nothing: the app hears its state, before the event is marked, so a throw redelivers.
+    if (next.product === ORDER && next.plan) {
+      if (newer && had?.state !== next.state)
+        await onOrder?.({ ref: next.plan, state: next.state, purchase: next })
+      return ['orders', orderTag(next.plan)]
+    }
     if (next.product && !byId.has(next.product))
       report?.({
         code: 'PAY021',
         severity: 'warning',
         message: `purchase \`${id}\` is for \`${next.product}\`, which isn't in the catalog: it grants nothing`,
       })
-    return next.user && entitlementTag(next.user)
+    return next.user ? [entitlementTag(next.user)] : []
   }
   async function ingest(rail: string, events: RailEvent[], report?: PayReport) {
@@ -58,9 +73,9 @@ export function makeLedger<P extends Product>(
     for (const e of events) {
       const key = `${rail}:${e.id}`
       if (await store.seen(key)) continue
-      const tag = await apply(rail, e, report)
+      const poked = await apply(rail, e, report)
       await store.mark(key, e.at)
-      if (tag) tags.add(tag)
+      for (const t of poked) tags.add(t)
     }
     return [...tags]
   }

package/src/server/operations.ts CHANGED Viewed

@@ -1,6 +1,7 @@
-import { PayError, type PayRail, type Product, type RailEvent } from '../index'
+import { PayError, type CheckoutLine, type PayRail, type Product, type RailEvent } from '../index'
 import type {
   CheckoutInput,
+  OrderInput,
   PayContext,
   PayOptions,
   PayReport,
@@ -8,6 +9,7 @@ import type {
   Purchase,
 } from '../server'
 import { lineOf } from './catalog'
+import { ORDER } from './ledger'
 const BODY = 1 << 20
 const hex = async (s: string) =>
@@ -140,3 +142,74 @@ export function webhookFor(
   }
   return webhook
 }
+const REF = /^[A-Za-z0-9_-]{1,64}$/
+/** Check an order's lines, which the app priced on the server, and sum them into the ledger's one line. */
+export function orderLines(input: OrderInput): { line: CheckoutLine; lines: CheckoutLine[] } {
+  const { ref, currency = 'usd' } = input
+  if (!REF.test(ref))
+    throw new PayError(
+      'PAY021',
+      `order ref \`${ref}\` must be 1–64 letters, digits, \`-\` or \`_\``,
+    )
+  if (!/^[a-z]{3}$/.test(currency))
+    throw new PayError('PAY008', `\`${currency}\` isn't a lowercase ISO currency`)
+  if (!input.lines.length || input.lines.length > 100)
+    throw new PayError('PAY021', `order \`${ref}\` needs 1 to 100 lines`)
+  const lines = input.lines.map((l): CheckoutLine => {
+    const quantity = l.quantity ?? 1
+    if (!Number.isSafeInteger(l.amount) || l.amount < 0)
+      throw new PayError(
+        'PAY008',
+        `\`${l.name}\`: ${l.amount} isn't whole minor units (999 is $9.99)`,
+      )
+    if (!Number.isInteger(quantity) || quantity < 1 || quantity > 999)
+      throw new PayError('PAY021', `\`${l.name}\`: quantity ${quantity} is out of range`)
+    return {
+      product: ORDER,
+      plan: ref,
+      name: l.name.slice(0, 250),
+      amount: l.amount,
+      currency,
+      mode: 'payment',
+      quantity,
+    }
+  })
+  const total = lines.reduce((sum, l) => sum + l.amount * l.quantity, 0)
+  if (total <= 0) throw new PayError('PAY021', `order \`${ref}\` totals nothing`)
+  return {
+    line: {
+      product: ORDER,
+      plan: ref,
+      name: input.title ?? `Order ${ref}`,
+      amount: total,
+      currency,
+      mode: 'payment',
+      quantity: 1,
+    },
+    lines,
+  }
+}
+/** Create the order operation: one payment for lines the app priced, signed in or not. */
+export function orderFor<P extends Product>({ options, urls, userOf, railFor }: Services<P>) {
+  async function order(ctx: PayContext, input: OrderInput) {
+    const { line, lines } = orderLines(input)
+    const rail = await railFor()
+    const origin = options.origin ?? new URL(ctx.request.url).origin
+    const back = (path: string) => new URL(path.replaceAll('{ref}', input.ref), origin).href
+    const { url } = await rail.checkout({
+      user: userOf(ctx) ?? `guest:${input.ref}`,
+      line,
+      lines,
+      ...(input.email && { email: input.email }),
+      successUrl: back(urls.order ?? urls.success),
+      cancelUrl: back(urls.orderCancel ?? urls.cancel),
+      // One session per order: paying twice for the same ref can't happen from a double click.
+      idempotencyKey: await hex(JSON.stringify(['order', input.ref, line.amount])),
+    })
+    return url
+  }
+  return order
+}

package/src/server.ts CHANGED Viewed

@@ -4,9 +4,9 @@
 import type { Context } from '@weft-js/start'
 import { makeRails } from './server/rails'
-import { makeLedger } from './server/ledger'
+import { makeLedger, ORDER } from './server/ledger'
 import { checkoutInput } from './server/catalog'
-import { checkoutFor, portalFor, webhookFor } from './server/operations'
+import { checkoutFor, orderFor, portalFor, webhookFor } from './server/operations'
 import type { ServerExtension } from '@weft-js/start/extension'
 import { PayError, type PayRail, type Product, type PurchaseState, type RailEvent } from './index'
@@ -91,8 +91,10 @@ export interface PayOptions<P extends Product> {
   /** `import * as catalog from './pay/catalog'`, or a list. */
   catalog: readonly P[] | Record<string, P>
   store: PayStore
-  /** Paths or URLs a buyer comes back to. They never come from the client. */
-  urls: { success: string; cancel: string; portal?: string }
+  /** Paths or URLs a buyer comes back to. They never come from the client. `order` and `orderCancel` may hold `{ref}`. */
+  urls: { success: string; cancel: string; portal?: string; order?: string; orderCancel?: string }
+  /** Hears each state an order (`pay.order`) moves to, from verified events only: mark it paid here. A throw redelivers. */
+  onOrder?: OrderHook
   /** Who a request is. Default `ctx.user?.id`. */
   user?: (ctx: PayContext) => string | null | undefined
   /** With several rails bound, the one that takes payments. One rail needs no choosing. */
@@ -116,6 +118,34 @@ export interface CheckoutInput<P extends Product = Product> {
   quantity?: number
 }
+/** One line of an order, priced by the app on the server: never from the client. */
+export interface OrderLine {
+  name: string
+  /** Whole minor units, each. */
+  amount: number
+  quantity?: number
+}
+/** What `pay.order` takes: the app's own order id and the lines it priced. */
+export interface OrderInput {
+  /** The app's order id, 1–64 of `A-Z a-z 0-9 - _`. It comes back in `onOrder` and in `orderTag(ref)`. */
+  ref: string
+  lines: readonly OrderLine[]
+  /** Lowercase ISO. Default `usd`. */
+  currency?: string
+  /** What the ledger's one line is called. Default `Order <ref>`. */
+  title?: string
+  /** A guest's email, for the rail's receipt. */
+  email?: string
+}
+/** `onOrder`: an order's new state, and its row in the ledger. */
+export type OrderHook = (order: {
+  ref: string
+  state: PurchaseState
+  purchase: Purchase
+}) => Promise<void> | void
 /** What `definePay` returns: the ledger's calls, and a `server.extension` that carries them to the server. */
 export interface Pay<P extends Product = Product> extends ServerExtension {
   readonly catalog: readonly P[]
@@ -130,6 +160,8 @@ export interface Pay<P extends Product = Product> extends ServerExtension {
   }
   /** The hosted checkout's URL, for this buyer. Grants nothing. */
   checkout(ctx: PayContext, input: CheckoutInput<P>): Promise<string>
+  /** The hosted page for one order the app priced, signed in or a guest. Pays nothing until `onOrder` hears `active`. */
+  order(ctx: PayContext, input: OrderInput): Promise<string>
   /** Where this buyer manages or cancels. */
   portal(ctx: PayContext): Promise<string>
   /** Read for a user id, as a webhook or a job would. In a request, `ctx.entitlements`. */
@@ -160,6 +192,11 @@ export function definePay<P extends Product>(options: PayOptions<P>): Pay<P> {
     Array.isArray(options.catalog) ? options.catalog : Object.values(options.catalog)
   ) as P[]
   const byId = new Map(catalog.map((p) => [p.id, p]))
+  if (byId.has(ORDER))
+    throw new PayError(
+      'PAY021',
+      `\`${ORDER}\` is the id \`pay.order\` records under: name the product something else`,
+    )
   const { store, urls, leeway = 3 * DAY } = options
   const userOf = options.user ?? ((ctx) => ctx?.user?.id)
   const slot =
@@ -172,12 +209,13 @@ export function definePay<P extends Product>(options: PayOptions<P>): Pay<P> {
   const rails = makeRails(options, slot)
   const { railFor } = rails
-  const { live, entitlements, ingest } = makeLedger(store, byId, leeway)
+  const { live, entitlements, ingest } = makeLedger(store, byId, leeway, options.onOrder)
   const pay: Pay<P> = {
     catalog,
     input: checkoutInput(byId),
     checkout: checkoutFor({ options, urls, userOf, store, railFor, live, byId }),
+    order: orderFor({ options, urls, userOf, store, railFor, live, byId }),
     portal: portalFor({ options, urls, userOf, store, railFor, live, byId }),
     entitlements,
     forContext: (ctx) => entitlements(userOf(ctx)),

package/src/square.ts ADDED Viewed

@@ -0,0 +1,231 @@
+// Square's signature is base64 HMAC-SHA256 of `<notification URL><raw body>` with the subscription's signature key, in
+// `x-square-hmacsha256-signature`. It carries no time, so a replay is stopped by the ledger's event ids. A payment's event
+// doesn't carry the order's metadata, so after the signature checks out the rail reads the order once to learn who and what.
+// Square sells one-time payments here: subscriptions and a customer portal are Stripe's (PAY022).
+import {
+  PayError,
+  type CheckoutLine,
+  type CheckoutRequest,
+  type PayRail,
+  type PurchaseState,
+  type RailEvent,
+} from './index'
+/** Options of `squareRail()`. Secrets default to the environment, which is where they belong. */
+export interface SquareOptions {
+  /** `sandbox` talks to squareupsandbox.com. Default `process.env.SQUARE_ENV`, else production. */
+  environment?: 'sandbox' | 'production'
+  /** The API's origin: point it at a local mock. Default from `environment`. */
+  api?: string
+  /** Pinned, so an account's default version can't reshape these calls. */
+  apiVersion?: string
+  /** Default `process.env.SQUARE_ACCESS_TOKEN`. */
+  accessToken?: string
+  /** Default `process.env.SQUARE_LOCATION_ID`: the shop the payments land in. */
+  locationId?: string
+  /** Default `process.env.SQUARE_WEBHOOK_SIGNATURE_KEY`. */
+  signatureKey?: string
+  /** The exact URL given to Square for the webhook; it's part of what's signed. Default `process.env.SQUARE_WEBHOOK_URL`. */
+  notificationUrl?: string
+  /** Default the global one. */
+  fetch?: typeof fetch
+}
+interface Money {
+  amount?: number
+  currency?: string
+}
+interface SquarePayment {
+  id: string
+  order_id?: string
+  status?: string
+  updated_at?: string
+  created_at?: string
+  customer_id?: string
+  total_money?: Money
+  amount_money?: Money
+  refunded_money?: Money
+}
+interface SquareEvent {
+  event_id?: string
+  type?: string
+  created_at?: string
+  data?: { object?: { payment?: SquarePayment } }
+}
+const PAYMENT: Record<string, PurchaseState> = {
+  APPROVED: 'pending',
+  PENDING: 'pending',
+  COMPLETED: 'active',
+  CANCELED: 'expired',
+  FAILED: 'expired',
+}
+const encoder = new TextEncoder()
+const env = (name: string) => (typeof process === 'undefined' ? undefined : process.env[name])
+async function signatureOk(key: string, text: string, given: string) {
+  const k = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(key),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['verify'],
+  )
+  let bytes: Uint8Array<ArrayBuffer>
+  try {
+    bytes = Uint8Array.from(atob(given), (c) => c.charCodeAt(0))
+  } catch {
+    return false
+  }
+  return crypto.subtle.verify('HMAC', k, bytes, encoder.encode(text))
+}
+/** One Square payment as a ledger state: a whole refund is final, a part refund keeps what was bought. */
+function stateOf(p: SquarePayment): PurchaseState | null {
+  const paid = p.total_money?.amount ?? p.amount_money?.amount ?? 0
+  if (p.refunded_money?.amount && paid && p.refunded_money.amount >= paid) return 'refunded'
+  return PAYMENT[p.status ?? ''] ?? null
+}
+function squareCall(options: SquareOptions, fetcher: typeof fetch) {
+  const sandbox = (options.environment ?? env('SQUARE_ENV')) === 'sandbox'
+  const api =
+    options.api ??
+    (sandbox ? 'https://connect.squareupsandbox.com' : 'https://connect.squareup.com')
+  const version = options.apiVersion ?? '2025-10-16'
+  return async function call(path: string, body?: unknown) {
+    const token = options.accessToken ?? env('SQUARE_ACCESS_TOKEN')
+    if (!token) throw new PayError('PAY003', '`SQUARE_ACCESS_TOKEN` is not set on the server', 500)
+    const res = await fetcher(`${api}${path}`, {
+      method: body === undefined ? 'GET' : 'POST',
+      headers: {
+        authorization: `Bearer ${token}`,
+        'content-type': 'application/json',
+        'square-version': version,
+      },
+      ...(body !== undefined && { body: JSON.stringify(body) }),
+    })
+    const data = (await res.json().catch(() => null)) as Record<string, unknown> | null
+    if (!res.ok) {
+      const errors = (data?.errors as { detail?: string }[] | undefined) ?? []
+      throw new PayError(
+        'PAY030',
+        `Square refused ${path}: ${errors[0]?.detail ?? res.status}`,
+        res.status === 429 ? 503 : 502,
+      )
+    }
+    return data ?? {}
+  }
+}
+const upper = (c: string) => c.toUpperCase()
+const lineItem = (l: CheckoutLine) => ({
+  name: l.name,
+  quantity: String(l.quantity),
+  base_price_money: { amount: l.amount, currency: upper(l.currency) },
+})
+type Call = ReturnType<typeof squareCall>
+/** One payment link for a checkout's lines, with the metadata its order carries back to `verify`. */
+async function paymentLink(call: Call, options: SquareOptions, request: CheckoutRequest) {
+  const { line, user } = request
+  if (line.mode !== 'payment')
+    throw new PayError(
+      'PAY022',
+      'The Square rail takes one-time payments: sell subscriptions with Stripe',
+      501,
+    )
+  const location = options.locationId ?? env('SQUARE_LOCATION_ID')
+  if (!location) throw new PayError('PAY003', '`SQUARE_LOCATION_ID` is not set on the server', 500)
+  const data = (await call('/v2/online-checkout/payment-links', {
+    idempotency_key: request.idempotencyKey.slice(0, 45),
+    order: {
+      location_id: location,
+      ...(line.plan && line.product === 'order' && { reference_id: line.plan.slice(0, 40) }),
+      line_items: (request.lines ?? [line]).map(lineItem),
+      metadata: {
+        weft_user: user.slice(0, 255),
+        weft_product: line.product,
+        ...(line.plan && { weft_plan: line.plan }),
+      },
+    },
+    checkout_options: { redirect_url: request.successUrl },
+    ...(request.email && { pre_populated_data: { buyer_email: request.email } }),
+  })) as { payment_link?: { url?: string } }
+  const url = data.payment_link?.url
+  if (typeof url !== 'string')
+    throw new PayError('PAY030', 'Square answered a link with no url', 502)
+  return { url }
+}
+/** The Square `pay.rail` provider: hosted payment links and webhooks verified here. One-time payments only. */
+export function squareRail(options: SquareOptions = {}): PayRail {
+  const fetcher = options.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args))
+  const call = squareCall(options, fetcher)
+  async function identity(orderId: string) {
+    const { order } = (await call(`/v2/orders/${encodeURIComponent(orderId)}`)) as {
+      order?: { metadata?: Record<string, string> }
+    }
+    const m = order?.metadata ?? {}
+    return {
+      ...(m.weft_user && { user: m.weft_user }),
+      ...(m.weft_product && { product: m.weft_product }),
+      ...(m.weft_plan && { plan: m.weft_plan }),
+    }
+  }
+  return {
+    id: 'square',
+    modes: ['payment'],
+    checkout: (request) => paymentLink(call, options, request),
+    portal() {
+      return Promise.reject(
+        new PayError('PAY022', 'Square has no customer portal: a buyer manages nothing here', 501),
+      )
+    },
+    async verify({ body, headers }) {
+      const key = options.signatureKey ?? env('SQUARE_WEBHOOK_SIGNATURE_KEY')
+      const url = options.notificationUrl ?? env('SQUARE_WEBHOOK_URL')
+      if (!key || !url)
+        throw new PayError(
+          'PAY011',
+          '`SQUARE_WEBHOOK_SIGNATURE_KEY` and `SQUARE_WEBHOOK_URL` must both be set: refusing every webhook rather than trusting one',
+        )
+      const given = headers.get('x-square-hmacsha256-signature') ?? ''
+      if (!given || !(await signatureOk(key, url + body, given)))
+        throw new PayError('PAY011', 'the signature does not match this body and URL')
+      const event = JSON.parse(body) as SquareEvent
+      const p = event.data?.object?.payment
+      if (!event.event_id || !p?.order_id || !event.type?.startsWith('payment.')) return []
+      const state = stateOf(p)
+      if (!state) return []
+      const at = Date.parse(p.updated_at ?? event.created_at ?? '') || Date.now()
+      const out: RailEvent = {
+        id: event.event_id,
+        at,
+        purchase: p.order_id,
+        state,
+        ...(await identity(p.order_id)),
+        ...(p.customer_id && { customer: p.customer_id }),
+      }
+      return [out]
+    },
+    async refund({ purchase }) {
+      const { order } = (await call(`/v2/orders/${encodeURIComponent(purchase)}`)) as {
+        order?: { tenders?: { payment_id?: string }[]; total_money?: Money }
+      }
+      const payment = order?.tenders?.[0]?.payment_id
+      if (!payment || !order?.total_money)
+        throw new PayError('PAY024', `order \`${purchase}\` has no payment to refund`, 404)
+      await call('/v2/refunds', {
+        idempotency_key: `refund-${purchase}`.slice(0, 45),
+        payment_id: payment,
+        amount_money: order.total_money,
+      })
+    },
+  }
+}

package/src/stripe.ts CHANGED Viewed

@@ -4,7 +4,7 @@
 import {
   PayError,
-  type CheckoutRequest,
+  type CheckoutLine,
   type PayRail,
   type PurchaseState,
   type RailEvent,
@@ -241,7 +241,7 @@ export function stripeRail(options: StripeOptions = {}): PayRail {
   const fetcher = options.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args))
   const call = stripeCall(options, api, apiVersion, fetcher)
-  function lineItem({ line }: CheckoutRequest) {
+  function lineItem(line: CheckoutLine) {
     const known = prices[line.plan ? `${line.product}.${line.plan}` : line.product]
     if (known) return { price: known, quantity: line.quantity }
     return {
@@ -268,11 +268,12 @@ export function stripeRail(options: StripeOptions = {}): PayRail {
         '/v1/checkout/sessions',
         {
           mode: line.mode,
-          line_items: [lineItem(request)],
+          line_items: (request.lines ?? [line]).map(lineItem),
           success_url: request.successUrl,
           cancel_url: request.cancelUrl,
           client_reference_id: user,
           customer,
+          customer_email: customer ? undefined : request.email,
           metadata,
           // What the later events carry: a charge and a subscription don't inherit the session's metadata.
           ...(line.mode === 'subscription'

package/src/test.ts CHANGED Viewed

@@ -277,16 +277,26 @@ export async function payRailSuite({
   check('no signature is refused', await refused({ body: good.body, headers: new Headers() }))
   if (tolerance)
     check('an old delivery is refused as a replay', await refused(delivery(tolerance + 60_000)))
-  const line = {
-    product: 'pro',
-    name: 'Pro',
-    amount: 999,
-    currency: 'usd',
-    mode: 'subscription',
-    plan: 'month',
-    interval: 'month',
-    quantity: 1,
-  } as const
+  const subscriptions = rail.modes?.includes('subscription') ?? true
+  const line = subscriptions
+    ? ({
+        product: 'pro',
+        name: 'Pro',
+        amount: 999,
+        currency: 'usd',
+        mode: 'subscription',
+        plan: 'month',
+        interval: 'month',
+        quantity: 1,
+      } as const)
+    : ({
+        product: 'pie',
+        name: 'Pie',
+        amount: 2400,
+        currency: 'usd',
+        mode: 'payment',
+        quantity: 1,
+      } as const)
   const { url } = await rail.checkout({
     user: 'u1',
     line,
@@ -295,7 +305,9 @@ export async function payRailSuite({
     idempotencyKey: 'k1',
   })
   check('`checkout` answers an absolute URL', /^https?:\/\//.test(url), url)
-  const portal = await rail.portal({ customer: 'c1', returnUrl: 'https://app.test/account' })
-  check('`portal` answers an absolute URL', /^https?:\/\//.test(portal.url), portal.url)
+  if (subscriptions) {
+    const portal = await rail.portal({ customer: 'c1', returnUrl: 'https://app.test/account' })
+    check('`portal` answers an absolute URL', /^https?:\/\//.test(portal.url), portal.url)
+  }
   return out
 }