cascivo 1.5.0 → 1.6.0

package/dist/{create-xLiwiyNv.mjs → create-DmBKREqv.mjs}

@@ -1,4 +1,4 @@
-import{a as e,r as t}from"./config-DT-Cs7bC.mjs";import{i as n}from"./fs-B7O-fNID.mjs";import{n as r,r as i,t as a}from"./args-CtmltI1S.mjs";import{stdin as o,stdout as s}from"node:process";import{existsSync as c,readdirSync as l}from"node:fs";import{join as u}from"node:path";import{createInterface as d}from"node:readline/promises";const f={"@cascivo/react":`1.5.0`,"@cascivo/themes":`1.0.0`,"@cascivo/charts":`1.5.0`,"@cascivo/icons":`1.1.0`,"@cascivo/eslint-config":`0.4.1`,"@cascivo/app":`1.5.0`,"@cascivo/render":`1.5.0`,"@cascivo/storage":`1.5.0`,"@cascivo/email":`0.5.0`},p=`>=3.0.0`;function m(e){let t=e.startsWith(`/`)?e:`/${e}`;return t.length>1?t.replace(/\/+$/,``)||`/`:t}function h(e){return e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)}function g(e){let t=m(e).split(`/`).filter(Boolean),n=[],r=[],i=``;return t.forEach((a,o)=>{if(a===`*`){if(o!==t.length-1)throw Error(`"*" must be the last segment of a path pattern: "${e}"`);n.push(`*`),r.push(1),i+=`(?:/(.*))?`}else if(a.startsWith(`:`)){let t=a.slice(1);if(!/^[A-Za-z_$][\w$]*$/.test(t))throw Error(`Invalid param name "${t}" in path pattern "${e}"`);n.push(t),r.push(2),i+=`/([^/]+)`}else r.push(3),i+=`/${h(a)}`}),{pattern:e,keys:n,regex:RegExp(`^${i||`/`}/?$`),score:r}}function _(e,t){let n=Math.max(e.score.length,t.score.length);for(let r=0;r<n;r++){let n=(t.score[r]??0)-(e.score[r]??0);if(n!==0)return n}return 0}var v=/\.(tsx|jsx)$/;function y(e){if(!v.test(e)||/\.(test|spec)\.[jt]sx$/.test(e))return;let t=e.replace(v,``).split(`/`);if(!t.some(e=>e.startsWith(`_`)))return t.length===1&&t[0]===`404`?null:(t.at(-1)===`index`&&t.pop(),`/${t.map((n,r)=>{if(/^\[\.\.\.[A-Za-z_$][\w$]*\]$/.test(n)){if(r!==t.length-1)throw Error(`routes/${e}: a [...rest] segment must be last`);return`*`}let i=/^\[([A-Za-z_$][\w$]*)\]$/.exec(n);if(i)return`:${i[1]}`;if(/[[\]]/.test(n))throw Error(`routes/${e}: malformed segment "${n}"`);return n}).join(`/`)}`)}function b(e,t){let n=[],r=new Map;for(let t of e){let e=y(t);if(e===void 0)continue;let i=r.get(e);if(i)throw Error(`routes/${i} and routes/${t} both define ${e??`the 404 route`}`);r.set(e,t),n.push({file:t,path:e})}let i=e=>`${t}/${e.replace(v,``)}`,a=n.filter(e=>e.path!==null).map(e=>({...e,compiled:g(e.path)})).sort((e,t)=>_(e.compiled,t.compiled)||e.path.localeCompare(t.path)),o=n.find(e=>e.path===null);return[`// Generated by @cascivo/app/vite from the routes directory — do not edit.`,`// Add, rename or delete a route file and this file is rewritten.`,`import { lazyRoute } from '@cascivo/app'`,`import type { Route } from '@cascivo/app'`,``,`export const routes: Route[] = [`,...a.map(e=>`  lazyRoute('${e.path}', () => import('${i(e.file)}')),`),`]`,``,o?`export const notFound: Route | undefined = lazyRoute('*', () => import('${i(o.file)}'))`:`export const notFound: Route | undefined = undefined`,``,"/** Every route pattern. Fill one with `buildPath` for a typed link. */",`export type AppPath = ${a.length>0?a.map(e=>`'${e.path}'`).join(` | `):`never`}`,``].join(`
+import{a as e,r as t}from"./config-DT-Cs7bC.mjs";import{i as n}from"./fs-B7O-fNID.mjs";import{n as r,r as i,t as a}from"./args-CtmltI1S.mjs";import{stdin as o,stdout as s}from"node:process";import{existsSync as c,readdirSync as l}from"node:fs";import{join as u}from"node:path";import{createInterface as d}from"node:readline/promises";const f={"@cascivo/react":`1.6.0`,"@cascivo/themes":`1.0.1`,"@cascivo/charts":`1.6.0`,"@cascivo/icons":`1.1.0`,"@cascivo/eslint-config":`0.4.1`,"@cascivo/app":`1.6.0`,"@cascivo/render":`1.6.0`,"@cascivo/storage":`1.6.0`,"@cascivo/email":`0.5.0`},p=`>=3.0.0`;function m(e){let t=e.startsWith(`/`)?e:`/${e}`;return t.length>1?t.replace(/\/+$/,``)||`/`:t}function h(e){return e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)}function g(e){let t=m(e).split(`/`).filter(Boolean),n=[],r=[],i=``;return t.forEach((a,o)=>{if(a===`*`){if(o!==t.length-1)throw Error(`"*" must be the last segment of a path pattern: "${e}"`);n.push(`*`),r.push(1),i+=`(?:/(.*))?`}else if(a.startsWith(`:`)){let t=a.slice(1);if(!/^[A-Za-z_$][\w$]*$/.test(t))throw Error(`Invalid param name "${t}" in path pattern "${e}"`);n.push(t),r.push(2),i+=`/([^/]+)`}else r.push(3),i+=`/${h(a)}`}),{pattern:e,keys:n,regex:RegExp(`^${i||`/`}/?$`),score:r}}function _(e,t){let n=Math.max(e.score.length,t.score.length);for(let r=0;r<n;r++){let n=(t.score[r]??0)-(e.score[r]??0);if(n!==0)return n}return 0}var v=/\.(tsx|jsx)$/;function y(e){if(!v.test(e)||/\.(test|spec)\.[jt]sx$/.test(e))return;let t=e.replace(v,``).split(`/`);if(!t.some(e=>e.startsWith(`_`)))return t.length===1&&t[0]===`404`?null:(t.at(-1)===`index`&&t.pop(),`/${t.map((n,r)=>{if(/^\[\.\.\.[A-Za-z_$][\w$]*\]$/.test(n)){if(r!==t.length-1)throw Error(`routes/${e}: a [...rest] segment must be last`);return`*`}let i=/^\[([A-Za-z_$][\w$]*)\]$/.exec(n);if(i)return`:${i[1]}`;if(/[[\]]/.test(n))throw Error(`routes/${e}: malformed segment "${n}"`);return n}).join(`/`)}`)}function b(e,t){let n=[],r=new Map;for(let t of e){let e=y(t);if(e===void 0)continue;let i=r.get(e);if(i)throw Error(`routes/${i} and routes/${t} both define ${e??`the 404 route`}`);r.set(e,t),n.push({file:t,path:e})}let i=e=>`${t}/${e.replace(v,``)}`,a=n.filter(e=>e.path!==null).map(e=>({...e,compiled:g(e.path)})).sort((e,t)=>_(e.compiled,t.compiled)||e.path.localeCompare(t.path)),o=n.find(e=>e.path===null);return[`// Generated by @cascivo/app/vite from the routes directory — do not edit.`,`// Add, rename or delete a route file and this file is rewritten.`,`import { lazyRoute } from '@cascivo/app'`,`import type { Route } from '@cascivo/app'`,``,`export const routes: Route[] = [`,...a.map(e=>`  lazyRoute('${e.path}', () => import('${i(e.file)}')),`),`]`,``,o?`export const notFound: Route | undefined = lazyRoute('*', () => import('${i(o.file)}'))`:`export const notFound: Route | undefined = undefined`,``,"/** Every route pattern. Fill one with `buildPath` for a typed link. */",`export type AppPath = ${a.length>0?a.map(e=>`'${e.path}'`).join(` | `):`never`}`,``].join(`
 `)}const x=f;function S(e){return e===`yarn`?`yarn`:`${e} install`}function C(e,t){return e===`npm`?`npm run ${t}`:`${e} ${t}`}function w(e,t){return`${e} run ${t}`}const T=[`react-vite`,`astro`,`cloudflare`],E=[`preact`,`react`],D=[`board`,`agent`,`notes`,`import`,`files`,`export`,`usage`,`crud`,`live`,`voice`,`publish`,`webhooks`,`digest`,`search`,`checkout`,`newsletter`];function O(e){return D.includes(e)}function k(e){return E.includes(e)}function A(e){return e.trim().toLowerCase().replace(/[^a-z0-9]+/g,`-`).replace(/^-+|-+$/g,``)||`section`}function j(e){let t=e.trim().split(/[^a-zA-Z0-9]+/).filter(Boolean).map(e=>e.charAt(0).toUpperCase()+e.slice(1)).join(``)||`Section`;return/^[0-9]/.test(t)?`Section${t}`:t}function M(e){let t=e.trim().split(/[^a-zA-Z0-9]+/).filter(e=>e!==``&&!/^\d+$/.test(e)&&!/^v\d+$/i.test(e)),n=[];for(let e of t){if(n.length>=3||n.length>0&&n.join(` `).length+1+e.length>24)break;n.push(e.charAt(0).toUpperCase()+e.slice(1))}return n.join(` `)||`App`}function N(e){return e.trim().toLowerCase().replace(/[^a-z0-9._-]+/g,`-`).replace(/^-+|-+$/g,``)||`cascivo-app`}function ee(e){let t=new Set,n=new Set,r=[];for(let i of e){let e=i.trim();if(!e)continue;let a=A(e),o=j(e),s=2;for(;t.has(a)||n.has(o);)a=`${A(e)}-${s}`,o=`${j(e)}${s}`,s++;t.add(a),n.add(o),r.push({key:a,label:e,component:o})}return r.length>0?r:[{key:`home`,label:`Home`,component:`Home`}]}function te(e){let t={name:N(e.name),private:!0,version:`0.0.0`,type:`module`,scripts:{dev:`vite`,build:`tsc && vite build`,preview:`vite preview`,typecheck:`tsc --noEmit`,lint:`eslint .`,format:`prettier --write .`,"format:check":`prettier --check .`},dependencies:{"@cascivo/react":x[`@cascivo/react`],"@cascivo/themes":x[`@cascivo/themes`],"@preact/signals-react":p,react:`^19.0.0`,"react-dom":`^19.0.0`},devDependencies:{"@cascivo/eslint-config":x[`@cascivo/eslint-config`],"@eslint/js":`^9.0.0`,"@types/react":`^19.0.0`,"@types/react-dom":`^19.0.0`,"@vitejs/plugin-react":`^5.0.0`,eslint:`^9.0.0`,"eslint-plugin-react-hooks":`^7.0.0`,prettier:`^3.0.0`,typescript:`^5.7.0`,"typescript-eslint":`^8.0.0`,vite:`^7.0.0`}};return JSON.stringify(t,null,2)+`
 `}function P(e){return JSON.stringify(e,null,2).replace(/\[\n\s+("[^"\n]*"(?:,\n\s+"[^"\n]*")*)\n\s*\]/g,(e,t)=>`[${t.split(/,\n\s+/).join(`, `)}]`)+`
 `}function F(){return P({compilerOptions:{target:`ES2022`,useDefineForClassFields:!0,lib:[`ES2022`,`DOM`,`DOM.Iterable`],module:`ESNext`,skipLibCheck:!0,moduleResolution:`bundler`,allowImportingTsExtensions:!0,resolveJsonModule:!0,isolatedModules:!0,moduleDetection:`force`,noEmit:!0,jsx:`react-jsx`,strict:!0,noUnusedLocals:!0,noUnusedParameters:!0,noFallthroughCasesInSwitch:!0},include:[`src`]})}function ne(){return`import react from '@vitejs/plugin-react'
@@ -1100,9 +1100,7 @@ ${C?`  ${w?`async `:``}fetch(request: Request, env: Env): Promise<Response>${w?`
     // Stripe's webhook (worker/checkout.ts); a bad signature is a 401.
     if (checkoutPath === orderStore.STRIPE_WEBHOOK_PATH && request.method === 'POST') {
       try {
-        return await orderStore.receiveStripe(request, env${g?`, (id) =>
-          billingStore.syncSubscription(env, id),
-        `:``})
+        return await orderStore.receiveStripe(request, env${g?`, billingStore.billingHooks(env)`:``})
       } catch (error) {
         return guardResponse(error)
       }
@@ -3793,8 +3791,12 @@ export const PRODUCT = {
   currency: 'eur',
 }
 
-/** \`pending\` until Stripe confirms the payment; the other three are final. */
-export type OrderStatus = 'pending' | 'paid' | 'failed' | 'expired'
+/**
+ * \`pending\` until Stripe confirms the payment. \`failed\` and \`expired\` are final. A paid
+ * order becomes \`refunded\` when all of it is refunded, and \`disputed\` while a chargeback is
+ * open (back to \`paid\` if it is won).
+ */
+export type OrderStatus = 'pending' | 'paid' | 'failed' | 'expired' | 'refunded' | 'disputed'
 
 export interface Order {
   id: string
@@ -3802,6 +3804,8 @@ export interface Order {
   /** What Stripe charged, in the currency's smallest unit. */
   amount: number
   currency: string
+  /** Refunded so far, in the same unit: part of a paid order, or all of a refunded one. */
+  refundedAmount: number
   createdAt: string
   paidAt: string | null
 }
@@ -3819,22 +3823,34 @@ export function formatPrice(amount: number, currency: string): string {
   return format.format(amount / 10 ** digits)
 }
 
-const STATUSES = ['pending', 'paid', 'failed', 'expired']
+const STATUSES = ['pending', 'paid', 'failed', 'expired', 'refunded', 'disputed']
 
 export function parseOrder(raw: unknown): Order {
   if (typeof raw === 'object' && raw !== null) {
-    const { id, status, amount, currency, createdAt, paidAt } = raw as Record<string, unknown>
+    const { id, status, amount, currency, refundedAmount, createdAt, paidAt } = raw as Record<
+      string,
+      unknown
+    >
     if (
       typeof id === 'string' &&
       typeof status === 'string' &&
       STATUSES.includes(status) &&
       typeof amount === 'number' &&
       typeof currency === 'string' &&
+      typeof refundedAmount === 'number' &&
       typeof createdAt === 'string' &&
       (paidAt === null || typeof paidAt === 'string')
     ) {
-      // Checked against STATUSES just above.
-      return { id, status: status as OrderStatus, amount, currency, createdAt, paidAt }
+      return {
+        id,
+        // Checked against STATUSES just above.
+        status: status as OrderStatus,
+        amount,
+        currency,
+        refundedAmount,
+        createdAt,
+        paidAt,
+      }
     }
   }
   throw new Error('Malformed order')
@@ -3852,7 +3868,15 @@ import { migrate, queryRows } from '@cascivo/app/db'
 import type { Database } from '@cascivo/app/db'
 import { verifyWebhook } from '@cascivo/app/guard'
 import { StripeError, createStripe, parseStripeEvent } from '@cascivo/app/stripe'
-import type { CheckoutEventType, CheckoutSession, Stripe } from '@cascivo/app/stripe'
+import type {
+  Charge,
+  CheckoutEventType,
+  CheckoutSession,
+  Dispute,
+  DisputeEventType,
+  Invoice,
+  Stripe,
+} from '@cascivo/app/stripe'
 import { writeRoom } from '@cascivo/app/sync-server'
 import type { RoomNamespace } from '@cascivo/app/sync-server'
 import { Receipt, receiptSubject, renderEmail } from '@cascivo/email'
@@ -3872,8 +3896,13 @@ const migrations = [
         currency TEXT NOT NULL,
         email TEXT,
         created_at TEXT NOT NULL,
-        paid_at TEXT
+        paid_at TEXT,
+        payment_intent_id TEXT,
+        refunded_amount INTEGER NOT NULL DEFAULT 0,
+        dispute_status TEXT
       )\`,
+      // Refund and dispute events name the payment, not the session.
+      'CREATE INDEX orders_payment_intent ON orders (payment_intent_id)',
     ],
   },
 ]
@@ -3901,7 +3930,8 @@ export interface CheckoutEnv {
   STRIPE_WEBHOOK_SECRET?: string
 }
 
-const COLUMNS = 'id, status, amount, currency, created_at AS createdAt, paid_at AS paidAt'
+const COLUMNS =
+  'id, status, amount, currency, refunded_amount AS refundedAmount, created_at AS createdAt, paid_at AS paidAt'
 
 export function stripeOf(env: { STRIPE_SECRET_KEY?: string }): Stripe {
   if (!env.STRIPE_SECRET_KEY) {
@@ -3996,7 +4026,7 @@ async function settle(
   const [order] = await queryRows(
     env.DB,
     \`UPDATE orders SET status = ?, paid_at = ?, amount = COALESCE(?, amount),
-       currency = COALESCE(?, currency), email = ?
+       currency = COALESCE(?, currency), email = ?, payment_intent_id = ?
      WHERE session_id = ? AND status = 'pending' RETURNING \${COLUMNS}\`,
     [
       status,
@@ -4004,6 +4034,7 @@ async function settle(
       session.amountTotal,
       session.currency,
       session.customerEmail,
+      session.paymentIntentId,
       session.id,
     ],
     parseOrder,
@@ -4051,16 +4082,83 @@ async function sendReceipt(env: CheckoutEnv, order: Order, to: string, origin: s
   }
 }
 
+/**
+ * A refund, made in the Stripe dashboard or with \`createRefund\`. \`charge.refunded\` carries the
+ * running total, so a retried or late event cannot count a refund twice. All of it refunded
+ * makes the order \`refunded\`; part of it leaves it \`paid\`, with the amount shown.
+ */
+async function refundOrder(env: CheckoutEnv, charge: Charge): Promise<void> {
+  if (!charge.paymentIntentId) return
+  await migrate(env.DB, migrations)
+  const [order] = await queryRows(
+    env.DB,
+    \`UPDATE orders SET refunded_amount = MAX(refunded_amount, ?),
+       status = CASE WHEN ? = 1 THEN 'refunded' ELSE status END
+     WHERE payment_intent_id = ? AND status IN ('paid', 'refunded') RETURNING \${COLUMNS}\`,
+    [charge.amountRefunded, charge.refunded ? 1 : 0, charge.paymentIntentId],
+    parseOrder,
+  )
+  if (order) await writeRoom(env.ROOMS, orderRoom(order.id), 'order', { ...order })
+}
+
+/**
+ * A chargeback. While it is open the order is \`disputed\`: hold back anything not yet
+ * delivered, and answer it with evidence in the Stripe dashboard before the deadline shown
+ * there. Won, the order is \`paid\` again; lost, it stays \`disputed\`. The dispute's status is
+ * stored, so a \`created\` event arriving after \`closed\` cannot reopen it.
+ */
+async function disputeOrder(
+  env: CheckoutEnv,
+  type: DisputeEventType,
+  dispute: Dispute,
+): Promise<void> {
+  if (!dispute.paymentIntentId) return
+  await migrate(env.DB, migrations)
+  const [order] =
+    type === 'charge.dispute.created'
+      ? await queryRows(
+          env.DB,
+          \`UPDATE orders SET status = 'disputed', dispute_status = ?
+           WHERE payment_intent_id = ? AND status = 'paid' AND dispute_status IS NULL
+           RETURNING \${COLUMNS}\`,
+          [dispute.status, dispute.paymentIntentId],
+          parseOrder,
+        )
+      : await queryRows(
+          env.DB,
+          \`UPDATE orders SET dispute_status = ?,
+             status = CASE WHEN ? = 'won' THEN 'paid' ELSE 'disputed' END
+           WHERE payment_intent_id = ? AND status IN ('paid', 'disputed') RETURNING \${COLUMNS}\`,
+          [dispute.status, dispute.status, dispute.paymentIntentId],
+          parseOrder,
+        )
+  if (!order) return
+  if (type === 'charge.dispute.created') {
+    console.warn(
+      \`[checkout] order \${order.id} is disputed (\${dispute.reason ?? 'no reason given'})\`,
+    )
+  }
+  await writeRoom(env.ROOMS, orderRoom(order.id), 'order', { ...order })
+}
+
+/** What the webhook hands to worker/billing.ts, when the app bills subscriptions. */
+export interface BillingHooks {
+  /** A subscription changed: store its current state. */
+  subscription(subscriptionId: string): Promise<void>
+  /** A renewal could not be charged: tell the customer. */
+  paymentFailed(invoice: Invoice, origin: string): Promise<void>
+}
+
 /**
  * Stripe's webhook: verified against STRIPE_WEBHOOK_SECRET before anything in it is read,
- * then each Checkout event settles its order. Subscription events, and completed subscription
- * checkouts, go to \`onSubscription\` when the app bills subscriptions (worker/billing.ts).
- * Other events are acknowledged, so Stripe stops sending them.
+ * then each Checkout event settles its order, and refunds and disputes update it. Subscription
+ * and invoice events, and completed subscription checkouts, go to \`billing\` when the app bills
+ * subscriptions (worker/billing.ts). Other events are acknowledged, so Stripe stops sending them.
  */
 export async function receiveStripe(
   request: Request,
   env: CheckoutEnv,
-  onSubscription?: (subscriptionId: string) => Promise<void>,
+  billing?: BillingHooks,
 ): Promise<Response> {
   if (!env.STRIPE_WEBHOOK_SECRET) throw new HttpError(503, 'Set STRIPE_WEBHOOK_SECRET (README)')
   const { body } = await verifyWebhook(request, {
@@ -4068,12 +4166,18 @@ export async function receiveStripe(
     secret: env.STRIPE_WEBHOOK_SECRET,
   })
   const event = parseStripeEvent(body)
-  if (event.kind === 'subscription') await onSubscription?.(event.subscription.id)
+  const origin = new URL(request.url).origin
+  if (event.kind === 'subscription') await billing?.subscription(event.subscription.id)
+  if (event.kind === 'invoice' && event.type === 'invoice.payment_failed') {
+    await billing?.paymentFailed(event.invoice, origin)
+  }
+  if (event.kind === 'refund') await refundOrder(env, event.charge)
+  if (event.kind === 'dispute') await disputeOrder(env, event.type, event.dispute)
   if (event.kind === 'checkout' && event.session.mode === 'subscription') {
-    if (event.session.subscriptionId) await onSubscription?.(event.session.subscriptionId)
+    if (event.session.subscriptionId) await billing?.subscription(event.session.subscriptionId)
   } else if (event.kind === 'checkout') {
     const status = statusAfter(event.type, event.session)
-    if (status) await settle(env, event.session, status, new URL(request.url).origin)
+    if (status) await settle(env, event.session, status, origin)
   }
   return Response.json({ received: true })
 }
@@ -4246,6 +4350,8 @@ const STATUS = {
   paid: { variant: 'success', label: 'Paid' },
   failed: { variant: 'destructive', label: 'Payment failed' },
   expired: { variant: 'secondary', label: 'Expired' },
+  refunded: { variant: 'secondary', label: 'Refunded' },
+  disputed: { variant: 'destructive', label: 'Disputed' },
 } as const
 
 /** \`/checkout/:order\` — where Stripe sends the buyer back. It updates when Stripe confirms. */
@@ -4281,11 +4387,27 @@ export default function OrderPage({ params }: RouteProps<'/checkout/:order'>) {
           This page updates by itself when Stripe confirms. A bank payment can take a few days.
         </Alert>
       ) : null}
-      {order.status === 'paid' ? (
+      {order.status === 'paid' && order.refundedAmount === 0 ? (
         <Alert variant="success" title="Thank you">
           Your payment went through. A receipt is on its way to your inbox.
         </Alert>
       ) : null}
+      {order.status === 'paid' && order.refundedAmount > 0 ? (
+        <Alert variant="info" title="Partly refunded">
+          {formatPrice(order.refundedAmount, order.currency)} of this order was refunded to the card
+          that paid it.
+        </Alert>
+      ) : null}
+      {order.status === 'refunded' ? (
+        <Alert variant="info" title="Refunded">
+          The full amount went back to the card that paid it. It can take a few days to show.
+        </Alert>
+      ) : null}
+      {order.status === 'disputed' ? (
+        <Alert variant="warning" title="This payment is disputed">
+          The card's bank is reviewing a chargeback. The order is on hold until it is decided.
+        </Alert>
+      ) : null}
       {order.status === 'failed' ? (
         <Alert variant="destructive" title="The payment failed">
           Nothing was charged. <Link href="/checkout">Try again</Link>
@@ -4535,6 +4657,8 @@ import type { Database } from '@cascivo/app/db'
 import { SesError, createSes, handleSns, parseSesNotification } from '@cascivo/app/ses'
 import { writeRoom } from '@cascivo/app/sync-server'
 import type { RoomNamespace } from '@cascivo/app/sync-server'
+import { assertSendable, sendEmail } from '@cascivo/email'
+import type { RenderResult } from '@cascivo/email'
 import { ISSUE_ID, issueRoom, parseIssue } from '../src/newsletter'
 import type { Issue, IssueInput, Overview, SubscriberCounts } from '../src/newsletter'
 import { TOKEN_SLOT, renderConfirmation, renderIssue } from './newsletter-email'
@@ -4646,18 +4770,16 @@ async function requireKey(env: NewsletterEnv, key: string): Promise<void> {
   }
 }
 
-interface Mail {
-  subject: string
-  html: string
-  text: string
-  headers?: Record<string, string>
-}
-
-type Send = (to: string, mail: Mail) => Promise<'sent' | 'logged'>
+type Send = (
+  to: string,
+  message: RenderResult,
+  headers?: Record<string, string>,
+) => Promise<'sent' | 'logged'>
 
 /**
  * Sends one email through SES, or, in \`vite dev\` without AWS credentials, logs it instead.
- * Deployed without them, it refuses with what to set.
+ * Deployed without them, it refuses with what to set. The SES client is an \`EmailSender\`, so
+ * \`sendEmail\` checks the message (subject, preheader, text part, size) and every header first.
  */
 function mailer(env: NewsletterEnv): Send {
   const configured =
@@ -4679,8 +4801,12 @@ function mailer(env: NewsletterEnv): Send {
     accessKeyId: env.AWS_ACCESS_KEY_ID!,
     secretAccessKey: env.AWS_SECRET_ACCESS_KEY!,
   })
-  return async (to, message) => {
-    await ses.sendEmail({ from: env.NEWSLETTER_FROM, to, ...message })
+  return async (to, message, headers) => {
+    await sendEmail(ses, message, {
+      from: env.NEWSLETTER_FROM,
+      to,
+      ...(headers ? { headers } : {}),
+    })
     return 'sent'
   }
 }
@@ -4722,11 +4848,7 @@ export async function subscribe(
   const message = renderConfirmation(link)
   let outcome: 'sent' | 'logged'
   try {
-    outcome = await send(email, {
-      subject: message.subject,
-      html: message.html,
-      text: message.text,
-    })
+    outcome = await send(email, message)
   } catch (error) {
     if (!(error instanceof SesError)) throw error
     console.error('[newsletter] confirmation not sent:', error.code, error.message)
@@ -4840,6 +4962,12 @@ export async function sendIssue(
 ): Promise<Issue> {
   await requireKey(env, input.key)
   mailer(env) // Deployed without SES, refuse now rather than fail in the queue.
+  try {
+    // An issue too large to send (Gmail clips it) is refused here, not retried in the queue.
+    assertSendable(renderIssue(input.subject, input.body, origin))
+  } catch (error) {
+    throw new HttpError(400, error instanceof Error ? error.message : String(error))
+  }
   await migrate(env.DB, migrations)
   const readers = await queryRows(
     env.DB,
@@ -4917,15 +5045,18 @@ export async function deliver(env: NewsletterEnv, batch: NewsletterBatch): Promi
       let status: string
       let detail: string | null = null
       try {
-        status = await send(email, {
-          subject: rendered.subject,
-          html: rendered.html.replaceAll(TOKEN_SLOT, readerToken),
-          text: rendered.text.replaceAll(TOKEN_SLOT, readerToken),
-          headers: {
+        status = await send(
+          email,
+          {
+            ...rendered,
+            html: rendered.html.replaceAll(TOKEN_SLOT, readerToken),
+            text: rendered.text.replaceAll(TOKEN_SLOT, readerToken),
+          },
+          {
             'List-Unsubscribe': \`<\${unsubscribe}>\`,
             'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
           },
-        })
+        )
       } catch (error) {
         if (!(error instanceof SesError) || error.retryable) throw error
         status = 'failed'
@@ -5401,7 +5532,10 @@ const STATUSES: readonly BillingStatus[] = [
 
 export interface Billing {
   status: BillingStatus
-  /** Whether the plan's features are on: the subscription is active or trialing. */
+  /**
+   * Whether the plan's features are on: the subscription is active or trialing, or past due
+   * while Stripe retries the renewal (\`isEntitled\` from @cascivo/app/stripe, in the Worker).
+   */
   active: boolean
   /** When the current period ends: the next charge, or the end of a cancelled plan. */
   currentPeriodEnd: string | null
@@ -5411,9 +5545,6 @@ export interface Billing {
   canManage: boolean
 }
 
-/** The statuses that unlock the plan. Check this in the Worker before serving a paid feature. */
-export const isActive = (status: BillingStatus) => status === 'active' || status === 'trialing'
-
 export function parseBilling(raw: unknown): Billing {
   if (typeof raw === 'object' && raw !== null) {
     const { status, active, currentPeriodEnd, cancelAtPeriodEnd, canManage } = raw as Record<
@@ -5454,10 +5585,26 @@ export function parseSyncInput(raw: unknown): { sessionId: string } {
 import { requireUser } from '@cascivo/app/auth-server'
 import { migrate, queryRows } from '@cascivo/app/db'
 import type { Database } from '@cascivo/app/db'
-import type { Subscription } from '@cascivo/app/stripe'
-import { PLAN, isActive, parseBilling } from '../src/billing'
+import { isEntitled, requireEntitlement } from '@cascivo/app/stripe'
+import type { Invoice, Subscription } from '@cascivo/app/stripe'
+import {
+  Body,
+  Button,
+  Container,
+  Head,
+  Heading,
+  Html,
+  Preview,
+  Section,
+  Text,
+  renderEmail,
+} from '@cascivo/email'
+import { createElement as h } from 'react'
+import { PLAN, parseBilling } from '../src/billing'
 import type { Billing } from '../src/billing'
+import { SHOP_NAME, formatPrice } from '../src/checkout'
 import { refused, stripeOf } from './checkout'
+import type { BillingHooks, ReceiptSender } from './checkout'
 
 const migrations = [
   {
@@ -5470,7 +5617,8 @@ const migrations = [
         status TEXT NOT NULL,
         current_period_end INTEGER,
         cancel_at_period_end INTEGER NOT NULL DEFAULT 0,
-        updated_at TEXT NOT NULL
+        updated_at TEXT NOT NULL,
+        reminded TEXT
       )\`,
     ],
   },
@@ -5478,6 +5626,8 @@ const migrations = [
 
 export interface BillingEnv {
   DB: Database
+  EMAIL: ReceiptSender
+  RECEIPT_FROM: string
   STRIPE_SECRET_KEY?: string
 }
 
@@ -5526,7 +5676,7 @@ function toBilling(row: Row | null): Billing {
     cancelAtPeriodEnd: row?.cancelAtPeriodEnd === 1,
     canManage: row?.customerId != null,
   })
-  return { ...billing, active: isActive(billing.status) }
+  return { ...billing, active: isEntitled(billing.status) }
 }
 
 /**
@@ -5578,6 +5728,102 @@ export async function getBilling(env: BillingEnv, request: Request): Promise<Bil
   return toBilling(await readRow(env.DB, user.id))
 }
 
+/**
+ * Refuses a user whose plan is not on: 401 signed out, 402 without the plan. Call it in the
+ * Worker before serving a paid feature, never trusting what the page shows.
+ */
+export async function requirePlan(env: BillingEnv, request: Request): Promise<void> {
+  const user = await requireUser(env.DB, request)
+  requireEntitlement((await readRow(env.DB, user.id))?.status)
+}
+
+/** The email for a renewal that could not be charged, with where to pay it. */
+function renderPaymentFailed(invoice: Invoice, payHref: string) {
+  const subject = \`Your \${PLAN.name} payment did not go through\`
+  const amount = formatPrice(invoice.amountDue, invoice.currency)
+  return renderEmail(
+    h(
+      Html,
+      null,
+      h(Head, { title: subject }),
+      h(
+        Body,
+        null,
+        h(Preview, null, \`We could not charge \${amount}. Update your card to keep \${PLAN.name}.\`),
+        h(
+          Container,
+          null,
+          h(
+            Section,
+            { padding: 32 },
+            h(Heading, { level: 1 }, 'Your payment did not go through'),
+            h(
+              Text,
+              null,
+              \`We could not charge \${amount} for \${SHOP_NAME} \${PLAN.name}. Your plan stays on while we try again; pay with another card to keep it.\`,
+            ),
+            h(Button, { href: payHref }, 'Update payment'),
+          ),
+        ),
+      ),
+    ),
+    { subject },
+  )
+}
+
+/**
+ * A renewal Stripe could not charge (\`invoice.payment_failed\`). The customer hears about it
+ * once per attempt, with Stripe's page for paying the invoice with another card. The plan stays
+ * on while Stripe retries (\`past_due\`); the Stripe dashboard's failed-payment settings decide
+ * when it ends. Only customers this app bills are written to: a retried event, or an invoice
+ * for something else on the same Stripe account, sends nothing.
+ */
+export async function remindPayment(
+  env: BillingEnv,
+  invoice: Invoice,
+  origin: string,
+): Promise<void> {
+  if (!invoice.customerId || !invoice.customerEmail) return
+  await migrate(env.DB, migrations)
+  const attempt = \`\${invoice.id}:\${invoice.attemptCount}\`
+  const [row] = await queryRows(
+    env.DB,
+    'UPDATE billing SET reminded = ? WHERE customer_id = ? AND reminded IS NOT ? RETURNING user_id',
+    [attempt, invoice.customerId, attempt],
+    (raw) => raw,
+  )
+  if (!row) return
+  const message = renderPaymentFailed(invoice, invoice.hostedInvoiceUrl ?? \`\${origin}/billing\`)
+  if (import.meta.env.DEV) {
+    console.log(\`[billing] payment reminder for \${invoice.customerEmail}: "\${message.subject}"\`)
+    return
+  }
+  if (!env.RECEIPT_FROM) {
+    console.warn('[billing] no payment reminder sent: set RECEIPT_FROM in wrangler.jsonc')
+    return
+  }
+  try {
+    await env.EMAIL.send({
+      from: env.RECEIPT_FROM,
+      to: invoice.customerEmail,
+      subject: message.subject,
+      text: message.text,
+      html: message.html,
+    })
+  } catch (error) {
+    // Logged, not thrown: Stripe retrying the event would not send it again.
+    console.error('[billing] payment reminder not sent:', error)
+  }
+}
+
+/** What the Stripe webhook (worker/checkout.ts) hands over to billing. */
+export function billingHooks(env: BillingEnv): BillingHooks {
+  return {
+    subscription: (id) => syncSubscription(env, id),
+    paymentFailed: (invoice, origin) => remindPayment(env, invoice, origin),
+  }
+}
+
 /** Opens a subscription checkout for PLAN, naming the user in the subscription's metadata. */
 export async function startSubscription(
   env: BillingEnv,
@@ -7546,8 +7792,9 @@ it to the order page, and emails a receipt rendered with \`@cascivo/email\`.
 3. Deployed: \`npx wrangler secret put STRIPE_SECRET_KEY\` and
    \`npx wrangler secret put STRIPE_WEBHOOK_SECRET\`. In the dashboard, add a webhook endpoint
    at \`https://<your app>/api/stripe/webhook\` for \`checkout.session.completed\`,
-   \`checkout.session.async_payment_succeeded\`, \`checkout.session.async_payment_failed\` and
-   \`checkout.session.expired\`; its signing secret is \`STRIPE_WEBHOOK_SECRET\`.
+   \`checkout.session.async_payment_succeeded\`, \`checkout.session.async_payment_failed\`,
+   \`checkout.session.expired\`, \`charge.refunded\`, \`charge.dispute.created\` and
+   \`charge.dispute.closed\`; its signing secret is \`STRIPE_WEBHOOK_SECRET\`.
 4. Receipts: set \`RECEIPT_FROM\` in \`wrangler.jsonc\` to an address on a domain you have
    onboarded to Email Service. \`vite dev\` renders each receipt and logs it instead.
 
@@ -7563,10 +7810,38 @@ browser cannot change it.
   set on a Payment Link.
 - A bank debit completes the session as \`unpaid\`: the order stays pending until
   \`async_payment_succeeded\` or \`async_payment_failed\` arrives, possibly days later.
+- Refunds are made in the Stripe dashboard (or with \`createRefund\`); \`charge.refunded\` records
+  the amount, and an order refunded in full becomes \`refunded\`. A chargeback makes it
+  \`disputed\` until it is decided: answer it with evidence in the dashboard. Both find the
+  order by the payment it stored when it was paid.
 - \`src/routes/checkout/[order].tsx\` — where Stripe sends the buyer back. It watches the
   order's read-only room, so it updates when the webhook arrives.
 
-Each caller (by IP) may start 20 checkouts a minute.${J(e)?"\n\n### Subscriptions (`/billing`)\n\nSigned-in users subscribe to `PLAN` (`src/billing.ts`) on Stripe's checkout and change,\npause or cancel it in Stripe's hosted billing portal, so the app has no billing screens to build.\n\n1. Add `customer.subscription.created`, `customer.subscription.updated` and\n   `customer.subscription.deleted` to the webhook endpoint's events.\n2. In the Stripe dashboard, save the Customer Portal's settings once (test mode too): until\n   then, Stripe refuses to open it.\n3. Gate a paid feature in the Worker on `(await billingStore.getBilling(env, request)).active`,\n   never on what the page shows.\n\n- `worker/billing.ts` — the subscription names its user in its metadata, which only the\n  Worker sets (`client_reference_id` can be set by a buyer on a Payment Link). Every\n  subscription event is read back from Stripe before it is stored, because events arrive out of\n  order, and a late event about an older subscription cannot end a live one.\n- Back from checkout, `/billing` reads the session and its subscription at once, so it is right\n  before the webhook arrives, and only for the user the subscription names.":`
+Each caller (by IP) may start 20 checkouts a minute.${J(e)?`
+
+### Subscriptions (\`/billing\`)
+
+Signed-in users subscribe to \`PLAN\` (\`src/billing.ts\`) on Stripe's checkout and change,
+pause or cancel it in Stripe's hosted billing portal, so the app has no billing screens to build.
+
+1. Add \`customer.subscription.created\`, \`customer.subscription.updated\`,
+   \`customer.subscription.deleted\` and \`invoice.payment_failed\` to the webhook endpoint's
+   events.
+2. In the Stripe dashboard, save the Customer Portal's settings once (test mode too): until
+   then, Stripe refuses to open it.
+3. Gate a paid feature in the Worker with \`await billingStore.requirePlan(env, request)\` (402
+   without the plan), never on what the page shows.
+
+- \`worker/billing.ts\` — the subscription names its user in its metadata, which only the
+  Worker sets (\`client_reference_id\` can be set by a buyer on a Payment Link). Every
+  subscription event is read back from Stripe before it is stored, because events arrive out of
+  order, and a late event about an older subscription cannot end a live one.
+- Back from checkout, \`/billing\` reads the session and its subscription at once, so it is right
+  before the webhook arrives, and only for the user the subscription names.
+- A renewal that cannot be charged leaves the plan on (\`past_due\`) while Stripe retries, and
+  emails the customer once per attempt with Stripe's page to pay with another card. How long
+  Stripe retries, and whether it then cancels, is set in the dashboard (Billing → Subscriptions
+  and emails); turn off Stripe's own failed-payment emails there, or customers get two.`:`
 
 Subscriptions need an account to belong to: \`cascivo create --framework cloudflare
 --example checkout --auth email\` adds a \`/billing\` page with a monthly plan and Stripe's
@@ -7597,7 +7872,8 @@ To send for real:
 - \`worker/newsletter.ts\` — double opt-in: a sign-up gets a confirmation link (valid a day,
   resent at most every ten minutes) and gets no issue until it is opened. Sending stores the
   issue and puts its readers on the \`NEWSLETTER\` queue, 25 per message; the consumer sends
-  them one by one through \`createSes\` (\`@cascivo/app/ses\`), one message at a time. Each
+  them one by one through \`createSes\` (\`@cascivo/app/ses\`), handed to \`sendEmail\` from
+  \`@cascivo/email\`, which checks each message before it leaves, one message at a time. Each
   send is recorded, so a message retried after SES throttling skips whoever already has it.
 - Every issue carries \`List-Unsubscribe\` and \`List-Unsubscribe-Post\` (one-click
   unsubscribe, RFC 8058, which Gmail and Yahoo require of bulk senders) and a footer link to
@@ -7711,4 +7987,4 @@ Good to know:`),console.log(`  No cascivo.config.ts is written — this app uses
   No account yet? Share a 60-minute preview, claimable into a free account:`),console.log(`  ${w(M,`deploy:preview`)}`)):m===`astro`?(console.log(`
   Pages are real Astro routes — no client router to add. Only src/`),console.log(`  components/Shell.tsx hydrates (client:load, for the mobile nav drawer);`),console.log(`  page content is server-rendered and ships no JS. See`),console.log(`  https://cascivo.com/docs/using-with-astro.md`)):(console.log(`
   Adding a router? Keep src/Shell.tsx, delete src/App.tsx + src/sections/,`),console.log(`  and register your Link once with setLinkComponent — see`),console.log(`  https://cascivo.com/docs/using-with-a-router.md`))}finally{N?.close()}}export{hn as create};
-//# sourceMappingURL=create-xLiwiyNv.mjs.map
+//# sourceMappingURL=create-DmBKREqv.mjs.map