@trypattern/sdk 0.1.38 → 0.1.39

package/dist/server/requestSources.js

@@ -0,0 +1,157 @@
+import { Hono } from 'hono';
+import { REQUEST_ACTION_NAME, SOURCE_NAME, inquiry, requestTables } from "../requests.js";
+import { refused } from "../services.js";
+import { snakeCase } from "../table.js";
+import { fieldsOf, noticeOf, storedRows, textOf } from "./inquiries.js";
+import { afterResponse, drainNotices, receivedStatements, requestsLink, transitionStatements } from "./requests.js";
+const BUILT_IN = new Set(['reply', 'done']);
+const DECISIONS = {
+    accept: 'Accept',
+    decline: 'Decline'
+};
+function declared(source, actions) {
+    return Object.entries(actions).map(([name, action]) => {
+        if (!REQUEST_ACTION_NAME.test(name) || BUILT_IN.has(name)) {
+            throw new Error(`${source} declares an action called '${name}': give it a short camelCase name of its own, like 'markFulfilled'. Reply and Mark done come with every request`);
+        }
+        const isDecision = Object.hasOwn(DECISIONS, name);
+        const label = action.label ?? DECISIONS[name];
+        if (label === undefined || label.trim() === '') {
+            throw new Error(`${source}'s ${name} action needs a label, the words on its button, like 'Mark fulfilled'`);
+        }
+        if (!isDecision && action.resolves === undefined) {
+            throw new Error(`${source}'s ${name} action needs resolves: true when it finishes the request, or false when the request stays open`);
+        }
+        return {
+            ...action,
+            name,
+            label,
+            resolves: action.resolves ?? true
+        };
+    });
+}
+export function requestSource(table, options) {
+    if (!SOURCE_NAME.test(options.source) || options.source === 'bookings') {
+        throw new Error(`request source '${options.source}' needs a short camelCase name of its own, like 'rentals'`);
+    }
+    if (table.access.create !== 'server') {
+        throw new Error(`${table.name} holds the ${options.source} requests, so its create access is 'server': your own server code saves each row and records the request in the same batch with recordRequest(c, ${options.source}, row)`);
+    }
+    const { kind, actions, ...presentation } = options;
+    return {
+        source: options.source,
+        table,
+        kind: kind ?? 'inquiry',
+        described: inquiry(table, presentation),
+        actions: declared(options.source, actions ?? {})
+    };
+}
+export function recordRequest(c, source, row) {
+    return receivedStatements(c.env.DB, {
+        source: source.source,
+        table: snakeCase(source.table.name),
+        requestId: row.id,
+        notice: noticeOf(source.described, row, requestsLink(c.env))
+    });
+}
+export function deliverRequestNotices(c) {
+    return afterResponse(c, drainNotices(c.env));
+}
+function statusOf(source, progress) {
+    if (progress.state === 'done')
+        return progress.decision ?? 'done';
+    if (progress.replied)
+        return 'replied';
+    return source.actions.some((action) => action.name === 'accept')
+        ? 'requested'
+        : 'open';
+}
+function contentOf(source, row, progress) {
+    const { described } = source;
+    const isOpen = progress.state === 'open';
+    const message = described.message === null ? '' : textOf(row[described.message]);
+    const brief = described.summary === null ? message : textOf(row[described.summary]);
+    const when = described.when === null ? '' : textOf(row[described.when.field]);
+    const available = source.actions.filter((action) => action.can === undefined || action.can(row));
+    return {
+        kind: source.kind,
+        title: described.title,
+        label: described.title,
+        summary: brief === '' ? described.form : `${described.form} · ${brief}`,
+        name: textOf(row[described.name]),
+        email: textOf(row[described.email]),
+        when: when === '' ? null : when,
+        whenDetail: described.when === null ? null : described.when.detail,
+        fields: fieldsOf(described, row),
+        contact: [],
+        message,
+        status: statusOf(source, progress),
+        needsAnswer: isOpen,
+        actions: isOpen
+            ? ['reply', ...available.map((action) => action.name), 'done']
+            : [],
+        actionLabels: Object.fromEntries(source.actions.map((action) => [action.name, action.label])),
+        receivedAt: textOf(row['createdAt'])
+    };
+}
+function eventOf(name) {
+    if (name === 'accept')
+        return 'accepted';
+    if (name === 'decline')
+        return 'declined';
+    return name;
+}
+function gatewaySource(source) {
+    return {
+        name: source.source,
+        table: snakeCase(source.table.name),
+        labels: Object.fromEntries(source.actions.map((action) => [eventOf(action.name), action.label])),
+        contents: async (d1, progress) => {
+            const rows = await storedRows(d1, source.table, [...progress.keys()]);
+            return new Map([...progress].flatMap(([id, step]) => {
+                const row = rows.get(id);
+                return row === undefined
+                    ? []
+                    : [[id, contentOf(source, row, step)]];
+            }));
+        },
+        decide: async (d1, id, name, expected) => {
+            const action = source.actions.find((item) => item.name === name);
+            if (action === undefined)
+                throw refused(400, 'Not allowed');
+            const row = (await storedRows(d1, source.table, [id])).get(id);
+            if (row === undefined)
+                throw refused(404, 'No such request');
+            if (action.can !== undefined && !action.can(row)) {
+                throw refused(409, 'That can’t be done to this request now');
+            }
+            const own = await action.run({ d1, id, row });
+            return [
+                ...own,
+                ...transitionStatements(d1, {
+                    source: source.source,
+                    requestId: id,
+                    event: eventOf(action.name),
+                    state: action.resolves ? 'done' : 'open',
+                    expected
+                })
+            ];
+        }
+    };
+}
+export function requestSources(sources) {
+    const names = new Set();
+    for (const source of sources) {
+        if (names.has(source.source)) {
+            throw new Error(`Two request sources are called '${source.source}': give each its own source name`);
+        }
+        names.add(source.source);
+    }
+    return {
+        name: 'requestSources',
+        tables: requestTables,
+        openPaths: [],
+        routes: new Hono(),
+        requests: sources.map(gatewaySource)
+    };
+}

package/dist/server/requests.d.ts

@@ -2,18 +2,22 @@ import type { D1Database, D1PreparedStatement } from '@cloudflare/workers-types'
 import type { Context } from 'hono';
 import type { RequestCard } from '../requests.ts';
 import type { ServerBindings, ServerEnv } from './env.ts';
-export type RequestContent = Omit<RequestCard, 'revision' | 'history' | 'notice' | 'source' | 'id' | 'receivedAt'>;
+export type RequestContent = Omit<RequestCard, 'revision' | 'history' | 'notice' | 'source' | 'id' | 'receivedAt' | 'actionLabels'> & {
+    actionLabels?: Readonly<Record<string, string>>;
+};
 export type RequestProgress = {
     state: 'open' | 'done';
     replied: boolean;
+    decision: 'accepted' | 'declined' | null;
 };
 export type RequestSource = {
     readonly name: string;
     readonly table: string;
+    readonly labels?: Readonly<Record<string, string>>;
     readonly contents: (d1: D1Database, progress: ReadonlyMap<string, RequestProgress>) => Promise<ReadonlyMap<string, RequestContent & {
         receivedAt: string;
     }>>;
-    readonly decide?: (d1: D1Database, id: string, action: 'accept' | 'decline', expected: number) => Promise<readonly D1PreparedStatement[]>;
+    readonly decide?: (d1: D1Database, id: string, action: string, expected: number) => Promise<readonly D1PreparedStatement[]>;
     readonly backfill?: (d1: D1Database) => D1PreparedStatement;
 };
 export type OwnerNotice = {
@@ -33,7 +37,7 @@ export declare function receivedStatements(d1: D1Database, { source, table, requ
 export declare function transitionStatements(d1: D1Database, { source, requestId, event, state, expected }: {
     source: string;
     requestId: string;
-    event: 'accepted' | 'declined' | 'replied' | 'done';
+    event: string;
     state: 'open' | 'done';
     expected: number | null;
 }): D1PreparedStatement[];

package/dist/server/requests.js

@@ -1,7 +1,7 @@
 import { Hono } from 'hono';
 import { z } from 'zod';
 import { REQUESTS_ACT, verifiedAssertion } from "../patternAccess.js";
-import { REQUEST_SYNC_PAGE, requestAct, requestBound, requestCard } from "../requests.js";
+import { REQUEST_EVENTS, REQUEST_SYNC_PAGE, requestAct, requestBound, requestCard } from "../requests.js";
 import { ServiceRefused, refused } from "../services.js";
 import { authServiceFor } from "./authService.js";
 import { PATTERN_KEYS } from "./patternKeys.js";
@@ -11,7 +11,11 @@ const MAX_ATTEMPTS = 8;
 const STALE_CLAIM_MS = 5 * 60 * 1000;
 const BACKOFF_MINUTES = [1, 5, 30, 120, 720];
 const DRAINED_AT_ONCE = 10;
+const DRAIN_ROUNDS = 5;
 const CHANGED = 'This request changed since you opened it. Open it again to see what’s new.';
+const NOT_NOW = 'That can’t be done to this request now';
+const UNCHANGED = 'unchanged';
+const BUILT_IN_EVENTS = new Set(REQUEST_EVENTS);
 const REQUEST_TABLES = [
     'request_states',
     'request_events',
@@ -36,6 +40,16 @@ export const NEXT_SEQUENCE = '(SELECT COALESCE(MAX(sequence), 0) + 1 FROM reques
 function stateId(source, requestId) {
     return `${source}:${requestId}`;
 }
+function mustChange(d1) {
+    return d1.prepare(`SELECT json(CASE WHEN changes() > 0 THEN '1' ELSE '${UNCHANGED}' END)`);
+}
+function eachMustChange(d1, statements) {
+    return statements.flatMap((statement) => [statement, mustChange(d1)]);
+}
+function isAbandoned(error) {
+    const text = error instanceof Error ? error.message : String(error);
+    return /malformed JSON|NOT NULL constraint/i.test(text);
+}
 export function requestsLink(env) {
     const name = env.APP_NAME ?? '';
     return name === '' ? DASHBOARD : `${DASHBOARD}/sites/${name}/requests`;
@@ -43,27 +57,26 @@ export function requestsLink(env) {
 export function receivedStatements(d1, { source, table, requestId, notice }) {
     const guard = `WHERE EXISTS (SELECT 1 FROM ${table} WHERE id = ?3)`;
     const now = new Date().toISOString();
+    const id = stateId(source, requestId);
     return [
         d1
-            .prepare(`INSERT INTO request_states (id, source, request_id, state, revision, sequence, updated_at) SELECT ?1, ?2, ?3, 'open', 1, ${NEXT_SEQUENCE}, ?4 ${guard}`)
-            .bind(stateId(source, requestId), source, requestId, now),
+            .prepare(`INSERT OR IGNORE INTO request_states (id, source, request_id, state, revision, sequence, updated_at) SELECT ?1, ?2, ?3, 'open', 1, ${NEXT_SEQUENCE}, ?4 ${guard}`)
+            .bind(id, source, requestId, now),
         d1
-            .prepare(`INSERT INTO request_events (id, source, request_id, kind) SELECT ?1, ?2, ?3, 'received' ${guard}`)
-            .bind(crypto.randomUUID(), source, requestId),
+            .prepare(`INSERT OR IGNORE INTO request_events (id, source, request_id, kind) SELECT ?1, ?2, ?3, 'received' ${guard}`)
+            .bind(`${id}:received`, source, requestId),
         d1
-            .prepare(`INSERT INTO request_outbox (id, source, request_id, subject, text, reply_to, status, attempts, next_at, sent_at, claimed_at) SELECT ?1, ?2, ?3, ?4, ?5, ?6, 'pending', 0, NULL, NULL, NULL ${guard}`)
-            .bind(crypto.randomUUID(), source, requestId, notice.subject, notice.text, notice.replyTo)
+            .prepare(`INSERT OR IGNORE INTO request_outbox (id, source, request_id, subject, text, reply_to, status, attempts, next_at, sent_at, claimed_at) SELECT ?1, ?2, ?3, ?4, ?5, ?6, 'pending', 0, NULL, NULL, NULL ${guard}`)
+            .bind(`${id}:received`, source, requestId, notice.subject, notice.text, notice.replyTo)
     ];
 }
 export function transitionStatements(d1, { source, requestId, event, state, expected }) {
     const id = stateId(source, requestId);
-    const guard = expected === null
-        ? ''
-        : `WHERE (SELECT revision FROM request_states WHERE id = ?4) = ?5`;
+    const guarded = expected === null ? [] : [id, expected];
     return [
         d1
-            .prepare(`INSERT INTO request_events (id, source, request_id, kind) SELECT ?1, ?2, ?3, '${event}' ${guard}`)
-            .bind(crypto.randomUUID(), source, requestId, ...(expected === null ? [] : [id, expected])),
+            .prepare(`INSERT INTO request_events (id, source, request_id, kind) SELECT ?1, ?2, ?3, ?4${expected === null ? '' : ' WHERE (SELECT revision FROM request_states WHERE id = ?5) = ?6'}`)
+            .bind(crypto.randomUUID(), source, requestId, event, ...guarded),
         d1
             .prepare(`UPDATE request_states SET state = ?1, revision = revision + 1, sequence = ${NEXT_SEQUENCE}, updated_at = ?2 WHERE id = ?3${expected === null ? '' : ' AND revision = ?4'}`)
             .bind(state, new Date().toISOString(), id, ...(expected === null ? [] : [expected]))
@@ -92,31 +105,44 @@ async function deliver(env, row) {
         return false;
     }
 }
+async function sendNotice(env, row, claim) {
+    const d1 = env.DB;
+    const claimed = await d1
+        .prepare(`UPDATE request_outbox SET status = 'sending', claimed_at = ?4 WHERE id = ?5 AND ${claim.claimable}`)
+        .bind(claim.force ? 1 : 0, claim.now, claim.stale, claim.now, row.id)
+        .run();
+    if (claimed.meta.changes !== 1)
+        return;
+    const sent = await deliver(env, row);
+    const attempts = row.attempts + 1;
+    await d1.batch([
+        d1
+            .prepare('UPDATE request_outbox SET status = ?1, attempts = ?2, sent_at = ?3, next_at = ?4, claimed_at = NULL WHERE id = ?5')
+            .bind(sent ? 'sent' : 'failed', attempts, sent ? new Date().toISOString() : null, sent ? null : nextTry(attempts, Date.now()), row.id),
+        touchStatement(d1, row.source, row.request_id)
+    ]);
+}
 export async function drainNotices(env, { force = false } = {}) {
     const d1 = env.DB;
     const now = Date.now();
-    const nowText = new Date(now).toISOString();
-    const stale = new Date(now - STALE_CLAIM_MS).toISOString();
-    const claimable = `(status = 'pending' OR (status = 'failed' AND attempts < ${MAX_ATTEMPTS} AND (?1 = 1 OR next_at <= ?2)) OR (status = 'sending' AND claimed_at < ?3))`;
-    const { results } = await d1
-        .prepare(`SELECT id, source, request_id, subject, text, reply_to, status, attempts FROM request_outbox WHERE ${claimable} ORDER BY created_at LIMIT ${DRAINED_AT_ONCE}`)
-        .bind(force ? 1 : 0, nowText, stale)
-        .all();
-    for (const row of results) {
-        const claimed = await d1
-            .prepare(`UPDATE request_outbox SET status = 'sending', claimed_at = ?4 WHERE id = ?5 AND ${claimable}`)
-            .bind(force ? 1 : 0, nowText, stale, nowText, row.id)
-            .run();
-        if (claimed.meta.changes !== 1)
-            continue;
-        const sent = await deliver(env, row);
-        const attempts = row.attempts + 1;
-        await d1.batch([
-            d1
-                .prepare('UPDATE request_outbox SET status = ?1, attempts = ?2, sent_at = ?3, next_at = ?4, claimed_at = NULL WHERE id = ?5')
-                .bind(sent ? 'sent' : 'failed', attempts, sent ? new Date().toISOString() : null, sent ? null : nextTry(attempts, Date.now()), row.id),
-            touchStatement(d1, row.source, row.request_id)
-        ]);
+    const claim = {
+        force,
+        now: new Date(now).toISOString(),
+        stale: new Date(now - STALE_CLAIM_MS).toISOString(),
+        claimable: `(status = 'pending' OR (status = 'failed' AND attempts < ${MAX_ATTEMPTS} AND (?1 = 1 OR next_at <= ?2)) OR (status = 'sending' AND claimed_at < ?3))`
+    };
+    const tried = [];
+    for (let round = 0; round < DRAIN_ROUNDS; round += 1) {
+        const { results } = await d1
+            .prepare(`SELECT id, source, request_id, subject, text, reply_to, status, attempts FROM request_outbox WHERE ${claim.claimable} AND id NOT IN (SELECT value FROM json_each(?4)) ORDER BY created_at LIMIT ${DRAINED_AT_ONCE}`)
+            .bind(force ? 1 : 0, claim.now, claim.stale, JSON.stringify(tried))
+            .all();
+        for (const row of results) {
+            tried.push(row.id);
+            await sendNotice(env, row, claim);
+        }
+        if (results.length < DRAINED_AT_ONCE)
+            return;
     }
 }
 export function afterResponse(c, work) {
@@ -128,6 +154,33 @@ export function afterResponse(c, work) {
         return work.then(() => undefined, () => undefined);
     }
 }
+function historyItem(source, event) {
+    if (BUILT_IN_EVENTS.has(event.kind)) {
+        return {
+            kind: event.kind,
+            at: event.created_at,
+            label: null
+        };
+    }
+    return {
+        kind: 'acted',
+        at: event.created_at,
+        label: source.labels?.[event.kind] ?? event.kind
+    };
+}
+function progressOf(state, events) {
+    const own = events.filter((event) => event.source === state.source && event.request_id === state.request_id);
+    const decision = own
+        .filter((event) => event.kind === 'accepted' || event.kind === 'declined')
+        .at(-1);
+    return {
+        state: state.state,
+        replied: own.some((event) => event.kind === 'replied'),
+        decision: decision === undefined
+            ? null
+            : decision.kind
+    };
+}
 async function cardsOf(d1, sources, states) {
     if (states.length === 0)
         return [];
@@ -149,12 +202,7 @@ async function cardsOf(d1, sources, states) {
             continue;
         const contents = await source.contents(d1, new Map(mine.map((state) => [
             state.request_id,
-            {
-                state: state.state,
-                replied: events.results.some((event) => event.kind === 'replied' &&
-                    event.source === state.source &&
-                    event.request_id === state.request_id)
-            }
+            progressOf(state, events.results)
         ])));
         for (const state of mine) {
             const content = contents.get(state.request_id);
@@ -164,12 +212,13 @@ async function cardsOf(d1, sources, states) {
             const notice = notices.results.filter(of).at(-1);
             cards.push({
                 ...content,
+                actionLabels: content.actionLabels ?? {},
                 source: state.source,
                 id: state.request_id,
                 revision: Number(state.revision),
                 history: events.results
                     .filter(of)
-                    .map((event) => ({ kind: event.kind, at: event.created_at })),
+                    .map((event) => historyItem(source, event)),
                 notice: notice === undefined
                     ? null
                     : {
@@ -225,15 +274,29 @@ async function sync(c, sources) {
         requests: await cardsOf(c.env.DB, sources, states)
     };
 }
-async function remembered(d1, operation) {
+const pointer = z.object({
+    source: z.string(),
+    id: z.string(),
+    revision: z.number().int()
+});
+async function remembered(d1, sources, operation) {
     const row = await d1
         .prepare('SELECT result FROM request_operations WHERE id = ?1')
         .bind(operation)
         .first();
     if (row === null || row.result === '')
         return undefined;
-    const card = requestCard.safeParse(JSON.parse(row.result));
-    return card.success ? card.data : undefined;
+    const saved = JSON.parse(row.result);
+    const card = requestCard.safeParse(saved);
+    if (card.success)
+        return card.data;
+    const done = pointer.safeParse(saved);
+    if (!done.success)
+        return undefined;
+    const now = await cardOf(d1, sources, done.data.source, done.data.id);
+    if (now === undefined)
+        throw refused(404, 'No such request');
+    return now;
 }
 async function actionStatements(d1, source, act) {
     const base = { source: act.source, requestId: act.id, expected: act.revision };
@@ -251,6 +314,15 @@ async function actionStatements(d1, source, act) {
         throw refused(400, 'Not allowed');
     return source.decide(d1, act.id, act.action, act.revision);
 }
+function operationStatement(d1, act) {
+    return d1
+        .prepare('INSERT INTO request_operations (id, result) VALUES (?1, CASE WHEN (SELECT revision FROM request_states WHERE id = ?3) = ?4 THEN ?2 END)')
+        .bind(act.operation, JSON.stringify({
+        source: act.source,
+        id: act.id,
+        revision: act.revision + 1
+    }), stateId(act.source, act.id), act.revision);
+}
 async function act(c, sources) {
     requirePattern(c);
     if (!(await takesRequests(c.env.DB)))
@@ -269,7 +341,7 @@ async function act(c, sources) {
     if (email === undefined)
         throw refused(403, 'This pass is for another action');
     const d1 = c.env.DB;
-    const earlier = await remembered(d1, wanted.operation);
+    const earlier = await remembered(d1, sources, wanted.operation);
     if (earlier !== undefined)
         return earlier;
     const source = sources.find((item) => item.name === wanted.source);
@@ -281,36 +353,32 @@ async function act(c, sources) {
     }
     if (current.revision !== wanted.revision)
         throw refused(409, CHANGED);
-    if (!current.actions.includes(wanted.action)) {
-        throw refused(409, 'That can’t be done to this request now');
-    }
+    if (!current.actions.includes(wanted.action))
+        throw refused(409, NOT_NOW);
     const statements = await actionStatements(d1, source, wanted);
     try {
         await d1.batch([
-            d1
-                .prepare('INSERT INTO request_operations (id, result) VALUES (?1, ?2)')
-                .bind(wanted.operation, ''),
-            ...statements
+            operationStatement(d1, wanted),
+            ...eachMustChange(d1, statements)
         ]);
     }
     catch (error) {
-        const again = await remembered(d1, wanted.operation);
+        const again = await remembered(d1, sources, wanted.operation);
         if (again !== undefined)
             return again;
-        throw error;
+        if (!isAbandoned(error))
+            throw error;
+        const latest = await cardOf(d1, sources, wanted.source, wanted.id);
+        throw refused(409, latest?.revision === wanted.revision ? NOT_NOW : CHANGED);
     }
     const after = await cardOf(d1, sources, wanted.source, wanted.id);
-    if (after === undefined || after.revision !== wanted.revision + 1) {
-        await d1
-            .prepare('DELETE FROM request_operations WHERE id = ?1')
-            .bind(wanted.operation)
-            .run();
-        throw refused(409, CHANGED);
-    }
+    if (after === undefined)
+        throw refused(404, 'No such request');
     await d1
         .prepare('UPDATE request_operations SET result = ?1 WHERE id = ?2')
         .bind(JSON.stringify(after), wanted.operation)
-        .run();
+        .run()
+        .catch(() => undefined);
     return after;
 }
 function answer(c, work) {