@weft-js/pay 0.1.1 → 0.1.4

package/docs/pay.md

@@ -12,11 +12,17 @@ App code names products, never a rail:
 // src/pay/catalog.ts: reaches the client, so names and amounts only
 import { product } from '@weft-js/pay'
 
-export const pro = product({ id: 'pro', kind: 'subscription', use: 'digital',
-  plans: { month: { usd: 999 }, year: { usd: 7999, trialDays: 7 } }, grants: ['pro'] })
+export const pro = product({
+  id: 'pro',
+  kind: 'subscription',
+  use: 'digital',
+  plans: { month: { usd: 999 }, year: { usd: 7999, trialDays: 7 } },
+  grants: ['pro'],
+})
 ```
 
 <!-- example: skip needs what `weft add pay` writes -->
+
 ```tsx
 // a page
 import { price } from '@weft-js/pay'
@@ -27,8 +33,15 @@ export default function Pricing() {
   const mine = entitlements.live()
   return (
     <section>
-      <button type="button" onClick={() => checkout({ product: 'pro', plan: 'year' })}>Go Pro · {price(pro, 'year').display}</button>
-      <button type="button" onClick={() => portal()}>Manage</button>
+      <button
+        type="button"
+        onClick={() => checkout({ product: 'pro', plan: 'year' })}
+      >
+        Go Pro · {price(pro, 'year').display}
+      </button>
+      <button type="button" onClick={() => portal()}>
+        Manage
+      </button>
       {mine.value?.includes('pro') && <p>You have Pro.</p>}
     </section>
   )
@@ -44,12 +57,23 @@ 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', requires: ['pro'], run: ({ ctx }) => buildReport(ctx) })  // a typed 403: ENTITLEMENT_REQUIRED
-if (!(await ctx.entitlements.has('pro'))) redirect('/pricing')                                          // await it (PAY015)
+export const report = query({
+  auth: 'user',
+  requires: ['pro'],
+  run: ({ ctx }) => buildReport(ctx),
+}) // a typed 403: ENTITLEMENT_REQUIRED
+// Await it (PAY015).
+if (!(await ctx.entitlements.has('pro'))) redirect('/pricing')
 ```
 
 `ctx.entitlements` has `has(id)` and `list()`, and works in any `query`, `mutation` or `load`. A query with `cache: { life }`
@@ -70,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).
@@ -82,13 +111,15 @@ generated file (PAY003).
 ledger, so a test sees what a user would:
 
 ```tsx
-const fake = fakePay(pay)                     // your `definePay`, or fakePay({ catalog })
+const fake = fakePay(pay) // your `definePay`, or fakePay({ catalog })
 net.context({ user: { id: 'u1' } })
 render(Paywall)
 await user.click(screen.getByRole('button', { name: /Go Pro/ }))
-await fake.complete()                          // the buyer finishes the hosted page
+await fake.complete() // the buyer finishes the hosted page
 expect(screen.getByLabelText('plan').textContent).toBe('Pro')
-await fake.simulate('renewal-failed')          // renewal, recovered, grace-expired, cancel, pause, resume, refund, revoke
+// renewal, recovered, grace-expired, cancel, pause, resume,
+// refund, revoke
+await fake.simulate('renewal-failed')
 ```
 
 `fake.buy(user, product, plan)` skips the page. `renewal` and `renewal-failed` move `clock` to the period's end when it's
@@ -97,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

@@ -1,17 +1,19 @@
 {
   "name": "@weft-js/pay",
-  "version": "0.1.1",
+  "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",
-  "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"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ravonus/weft.git",
+    "directory": "packages/pay"
   },
   "files": [
     "src",
@@ -21,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.1",
-    "drizzle-orm": "^0.45.0",
-    "@weft-js/core": "^0.1.1"
+    "@weft-js/core": "^0.1.4",
+    "@weft-js/start": "^0.1.4",
+    "drizzle-orm": "^0.45.0"
   },
   "peerDependenciesMeta": {
     "drizzle-orm": {
@@ -37,12 +56,6 @@
     }
   },
   "engines": {
-    "node": ">=26"
-  },
-  "keywords": [
-    "weft"
-  ],
-  "publishConfig": {
-    "access": "public"
+    "node": ">=24"
   }
-}
+}

package/plugin.mjs

@@ -5,22 +5,92 @@
 import { definePlugin, defineSlot, provide } from '@weft-js/core/plugin'
 import { setup } from './src/setup.mjs'
 
-const extension = defineSlot({ id: 'server.extension', version: 1, cardinality: 'keyed', sides: ['server'] })
+const extension = defineSlot({
+  id: 'server.extension',
+  version: 1,
+  cardinality: 'keyed',
+  sides: ['server'],
+})
 
 const diagnostics = [
-  ['PAY003', 'error', 'A Stripe secret, restricted or webhook key in the source, a server secret read in client code, or a key in plugin options', 'Move it to the server env (`src/env.server.ts`), and roll any real key that was committed'],
-  ['PAY004', 'error', "Paid state written on the client after `checkout()`, which only opens the rail's page", 'Read `entitlements` instead: a grant arrives from a verified event'],
-  ['PAY005', 'warning', 'A price typed into a page that sells something', '`price(product, plan).display`'],
-  ['PAY008', 'error', 'Money as a float, or with no currency, in `product()`', 'Whole minor units with a currency: `{ usd: 999 }`'],
-  ['PAY010', 'error', "A mutation that opens a checkout without `auth: 'user'`", "Add `auth: 'user'`: a purchase has to belong to someone"],
-  ['PAY011', 'error', 'A webhook left unverified: a handler of payment events with no signature check, a `PayRail` whose `verify` ignores `headers`, or no `STRIPE_WEBHOOK_SECRET`', 'Delete the handler: `/_weft/x/pay/<rail>` verifies. Give Stripe that URL, and set `STRIPE_WEBHOOK_SECRET`'],
-  ['PAY012', 'error', "A rail's price or product id in client code", "Name the catalog: `checkout({ product: 'pro', plan: 'month' })`. Map ids on the server: `stripe({ prices: { 'pro.month': … } })`"],
-  ['PAY013', 'error', 'An entitlement checked only on the client: nothing on the server enforces it', "`requires: ['pro']` on the query or mutation, or `await ctx.entitlements.has('pro')` in a `load`"],
-  ['PAY014', 'error', 'The plugin with no `src/pay.server.ts`: no webhook is mounted, so payments grant nothing', 'Default-export `definePay({ … })` from `src/pay.server.ts`'],
-  ['PAY015', 'error', '`ctx.entitlements.has()` tested without `await`: a promise is truthy, so everyone passes', 'Await it (`weft fix` does, in an `async` function)'],
-  ['PAY016', 'warning', '`memoryPayStore()` in `src/pay.server.ts`: a production server refuses to start with it', '`drizzlePayStore(db, { purchases, payEvents })`, or your own `PayStore`'],
-  ['PAY017', 'error', '`@weft-js/pay/server` or `/drizzle` imported in client code', 'Import them in a server module; the client gets `@weft-js/pay`'],
-  ['PAY018', 'error', '`src/pay.server.ts` with no `pay.rail` provider', 'Add a rail to `plugins`: `weft add pay-stripe`'],
+  [
+    'PAY003',
+    'error',
+    'A Stripe secret, restricted or webhook key in the source, a server secret read in client code, or a key in plugin options',
+    'Move it to the server env (`src/env.server.ts`), and roll any real key that was committed',
+  ],
+  [
+    'PAY004',
+    'error',
+    "Paid state written on the client after `checkout()`, which only opens the rail's page",
+    'Read `entitlements` instead: a grant arrives from a verified event',
+  ],
+  [
+    'PAY005',
+    'warning',
+    'A price typed into a page that sells something',
+    '`price(product, plan).display`',
+  ],
+  [
+    'PAY008',
+    'error',
+    'Money as a float, or with no currency, in `product()`',
+    'Whole minor units with a currency: `{ usd: 999 }`',
+  ],
+  [
+    'PAY010',
+    'error',
+    "A mutation that opens a checkout without `auth: 'user'`",
+    "Add `auth: 'user'`: a purchase has to belong to someone",
+  ],
+  [
+    'PAY011',
+    'error',
+    'A webhook left unverified: a handler of payment events with no signature check, a `PayRail` whose `verify` ignores `headers`, or no `STRIPE_WEBHOOK_SECRET`',
+    'Delete the handler: `/_weft/x/pay/<rail>` verifies. Give Stripe that URL, and set `STRIPE_WEBHOOK_SECRET`',
+  ],
+  [
+    'PAY012',
+    'error',
+    "A rail's price or product id in client code",
+    "Name the catalog: `checkout({ product: 'pro', plan: 'month' })`. Map ids on the server: `stripe({ prices: { 'pro.month': … } })`",
+  ],
+  [
+    'PAY013',
+    'error',
+    'An entitlement checked only on the client: nothing on the server enforces it',
+    "`requires: ['pro']` on the query or mutation, or `await ctx.entitlements.has('pro')` in a `load`",
+  ],
+  [
+    'PAY014',
+    'error',
+    'The plugin with no `src/pay.server.ts`: no webhook is mounted, so payments grant nothing',
+    'Default-export `definePay({ … })` from `src/pay.server.ts`',
+  ],
+  [
+    'PAY015',
+    'error',
+    '`ctx.entitlements.has()` tested without `await`: a promise is truthy, so everyone passes',
+    'Await it (`weft fix` does, in an `async` function)',
+  ],
+  [
+    'PAY016',
+    'warning',
+    '`memoryPayStore()` in `src/pay.server.ts`: a production server refuses to start with it',
+    '`drizzlePayStore(db, { purchases, payEvents })`, or your own `PayStore`',
+  ],
+  [
+    'PAY017',
+    'error',
+    '`@weft-js/pay/server` or `/drizzle` imported in client code',
+    'Import them in a server module; the client gets `@weft-js/pay`',
+  ],
+  [
+    'PAY018',
+    'error',
+    '`src/pay.server.ts` with no `pay.rail` provider',
+    'Add a rail to `plugins`: `weft add pay-stripe`',
+  ],
   ['PAY031', 'error', 'A live key in a test', '`fakePay` from `@weft-js/pay/test`'],
 ].map(([code, severity, catches, fix]) => ({ code, severity, catches, fix }))
 
@@ -31,19 +101,57 @@ export const pay = definePlugin({
   namespace: 'PAY',
   permissions: {},
   contribute: () => ({
-    provides: [provide(extension, { key: 'pay', sides: { server: { module: '@weft-js/pay/server', export: 'extension' } } })],
+    provides: [
+      provide(extension, {
+        key: 'pay',
+        sides: { server: { module: '@weft-js/pay/server', export: 'extension' } },
+      }),
+    ],
     diagnostics,
-    check: { include: ['src/**/*.{ts,tsx,js,jsx,mts,mjs}', 'test/**/*.{ts,tsx,js,mjs}', 'weft.config.*'], run: ctx => import('./src/checks.mjs').then(c => c.run(ctx)) },
-    docs: { topic: 'pay', summary: 'Payments: products, checkout, entitlements, webhooks, fakePay, another provider; PAY-codes', file: new URL('./docs/pay.md', import.meta.url).pathname },
+    check: {
+      include: ['src/**/*.{ts,tsx,js,jsx,mts,mjs}', 'test/**/*.{ts,tsx,js,mjs}', 'weft.config.*'],
+      run: (ctx) => import('./src/checks.mjs').then((c) => c.run(ctx)),
+    },
+    docs: {
+      topic: 'pay',
+      summary:
+        'Payments: products, checkout, entitlements, webhooks, fakePay, another provider; PAY-codes',
+      file: new URL('./docs/pay.md', import.meta.url).pathname,
+    },
     setup,
-    agents: { title: 'Payments', text: 'Products are in `src/pay/catalog.ts`, in minor units. `checkout` and `entitlements` are in `src/server/pay.ts`. App code never names a rail or a price id, and `checkout` grants nothing: a verified webhook does. Enforce on the server, with `requires: [...]` or `await ctx.entitlements.has(...)`: a check only on the client protects nothing. Test with `fakePay` from `@weft-js/pay/test`. `weft docs pay`.' },
+    agents: {
+      title: 'Payments',
+      text: 'Products are in `src/pay/catalog.ts`, in minor units. `checkout` and `entitlements` are in `src/server/pay.ts`. App code never names a rail or a price id, and `checkout` grants nothing: a verified webhook does. Enforce on the server, with `requires: [...]` or `await ctx.entitlements.has(...)`: a check only on the client protects nothing. Test with `fakePay` from `@weft-js/pay/test`. `weft docs pay`.',
+    },
     catalog: [
-      { name: 'product', import: '@weft-js/pay', summary: 'One thing you sell, in integer minor units' },
-      { name: 'price', import: '@weft-js/pay', summary: "A product's price, formatted for the reader" },
-      { name: 'definePay', import: '@weft-js/pay/server', summary: 'The ledger: src/pay.server.ts default-exports it' },
-      { name: 'fakePay', import: '@weft-js/pay/test', summary: 'A rail for tests: renewals, refunds and disputes on the clock' },
+      {
+        name: 'product',
+        import: '@weft-js/pay',
+        summary: 'One thing you sell, in integer minor units',
+      },
+      {
+        name: 'price',
+        import: '@weft-js/pay',
+        summary: "A product's price, formatted for the reader",
+      },
+      {
+        name: 'definePay',
+        import: '@weft-js/pay/server',
+        summary: 'The ledger: src/pay.server.ts default-exports it',
+      },
+      {
+        name: 'fakePay',
+        import: '@weft-js/pay/test',
+        summary: 'A rail for tests: renewals, refunds and disputes on the clock',
+      },
+    ],
+    map: [
+      {
+        want: 'Sell something',
+        call: 'add it to `src/pay/catalog.ts`, then `checkout({ product, plan })`',
+        have: '`weft docs pay`',
+      },
     ],
-    map: [{ want: 'Sell something', call: 'add it to `src/pay/catalog.ts`, then `checkout({ product, plan })`', have: '`weft docs pay`' }],
   }),
 })
 

package/square-plugin.d.mts

@@ -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

@@ -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/checks/config.mjs

@@ -0,0 +1,24 @@
+/** Check config and test files for exposed credentials. */
+export function configChecks({ ctx, out, secrets, spanOf, isTest, SECRET_OPTION }) {
+  for (const rel of ctx.files.filter((r) => r.startsWith('weft.config.'))) {
+    const text = ctx.read(rel)
+    secrets(rel, text, true, out)
+    const m = SECRET_OPTION.exec(text)
+    if (m)
+      out.push({
+        code: 'PAY003',
+        ...spanOf(rel, m.index, m[0].length),
+        why: 'Plugin options are written into `.weft/slots/`, so a key given here sits in a generated file.',
+      })
+  }
+
+  for (const rel of ctx.files.filter(isTest)) {
+    const text = ctx.read(rel)
+    for (const m of text.matchAll(/\b(?:sk|rk)_live_\w+/g))
+      out.push({
+        code: 'PAY031',
+        ...spanOf(rel, m.index, m[0].length),
+        why: 'A live key in a test: it charges real cards, and it is now in git.',
+      })
+  }
+}