@profullstack/agenticjobs 0.11.0 → 0.14.0

package/dist/server/routes/api.js

@@ -16,7 +16,7 @@
 import { Hono } from 'hono';
 import { approveDeviceCode, createSession, ensureUser, normaliseEmail, pollDeviceAuth, requireAdmin, safeRedirect, startDeviceAuth, startMagicLink, } from "../../core/auth.js";
 import { createApplication, decideApplication, listApplications, listDraftApplications, recentApplicationCount, submitApplication, validateApplication, } from "../../core/applications.js";
-import { countJobs, createJob, getJobBySlug, getJobBySourceUrl, normaliseInput, searchJobs, setStatus, editJob, updateJobFromImport, } from "../../core/jobs.js";
+import { countJobs, createJob, getJobBySlug, getJobBySourceUrl, normaliseInput, publishProblem, searchJobs, setStatus, editJob, updateJobFromImport, } from "../../core/jobs.js";
 import { extractJob, JobImportProblem } from "../../core/import-job.js";
 import { createOrg, deleteOrg, getOrgBySlug, isMember, listOrgs, listOrgsForUser, updateOrg, } from "../../core/orgs.js";
 import { createResume, deleteResume, getPublicResume, getResume, listPublicResumes, getResumeById, getSharedResume, isVisibility, listResumes, updateResume, } from "../../core/resumes.js";
@@ -24,6 +24,7 @@ import { importDocument, ImportProblem, MAX_UPLOAD_BYTES } from "../../core/impo
 import { deliverMagicLink } from "../../core/mail.js";
 import { resumeForViewer, tagsFrom, toCandidateSummary, withTags, } from "../../core/candidates.js";
 import { candidateSlugFor, deleteUpdate, follow, followerCount, isFollowing, listFollowedUpdates, listFollowing, listScoped, postUpdate, scopeFrom, unfollow, userForCandidate, } from "../../core/updates.js";
+import { decide as decideRecommendation, listApproved, listGiven, listReceived, notifySubject, resolve as resolveRecommendation, withdraw as withdrawRecommendation, writeRecommendation, } from "../../core/recommendations.js";
 import { sameOrigin } from "../../config.js";
 import { announce, Blocked, listInstances, listTopics } from "../../directory/registry.js";
 import { federatedSearch, targetsFromDescriptors } from "../../directory/federate.js";
@@ -33,6 +34,10 @@ import { APPLICATION_DECISIONS, isApplicationDecision } from "../../schema/job.j
 import { jobPostingJsonLd } from "../../schema/jsonld.js";
 import { parseResume } from "../../markup/resume.js";
 import { renderMarkdown } from "../../markup/markdown.js";
+import { counterpartyFrom, getThread, listThreads, markRead, notifyParticipants, sendMessage, startThread, } from "../../core/inbox.js";
+import { applyWebhook, cancelInvoice, getInvoice, listInvoicesFor, listInvoicesIn, requestPayment, sendInvoice, syncInvoice, } from "../../core/invoices.js";
+import { disconnect, finishConnect, getAccount } from "../../core/coinpay.js";
+import { coinpayRedirectUri } from "./pages.js";
 import { descriptorFor } from "./descriptor.js";
 import { openApiDocument } from "./openapi.js";
 function fail(c, status, code, message, fields) {
@@ -42,6 +47,9 @@ function fail(c, status, code, message, fields) {
 function viewerOf(c) {
     return c.get('viewer');
 }
+function isUuid(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}
 /** Body from JSON or a form, so curl, a browser and a model all work. */
 async function readBody(c) {
     const type = c.req.header('content-type') ?? '';
@@ -59,6 +67,38 @@ async function readBody(c) {
         return {};
     }
 }
+/**
+ * The pay fields of a PATCH, merged onto what the listing already says.
+ *
+ * Any pay field in the body replaces the whole of the pay: `pay` (lines, in
+ * either form), the flat salary fields, `payMethod`, `unpaid`. A body with
+ * none of them keeps the listing's pay as it is, so editing a description
+ * does not quietly clear a rate.
+ */
+function payPatch(body, job) {
+    const sent = (key) => body[key] !== undefined && body[key] !== null;
+    const hasLines = sent('pay') || sent('payLines') || sent('salaryMin') || sent('salaryMax') ||
+        sent('salaryPeriod') || sent('salaryCurrency');
+    const hasUnpaid = sent('salaryUnpaid') || sent('unpaid') || sent('payUnpaid');
+    return {
+        ...(hasLines
+            ? {
+                pay: body['pay'] ?? body['payLines'],
+                salaryMin: body['salaryMin'],
+                salaryMax: body['salaryMax'],
+                salaryPeriod: body['salaryPeriod'],
+                salaryCurrency: body['salaryCurrency'],
+            }
+            : { pay: { lines: job.pay.lines } }),
+        salaryUnpaid: hasUnpaid
+            ? (body['salaryUnpaid'] ?? body['unpaid'] ?? body['payUnpaid'])
+            : hasLines
+                ? false
+                : job.pay.unpaid,
+        payMethod: body['payMethod'] ?? body['paymentMethod'] ?? body['paymentCoin'] ?? job.pay.method,
+        payEquity: body['payEquity'] ?? body['salaryEquity'] ?? body['equity'] ?? job.pay.equity,
+    };
+}
 export function apiRoutes() {
     const api = new Hono();
     // --- jobs -------------------------------------------------------------
@@ -188,11 +228,19 @@ export function apiRoutes() {
         const input = normaliseInput(body, org.id);
         if (typeof input === 'string')
             return fail(c, 400, 'invalid', input);
-        const job = await createJob(pool, input);
         // A job posted through the API arrives as a draft like any other, unless
         // the caller asked for it to go live. An agent that posts a job the author
         // has not read is the failure mode worth designing against.
-        if (body['publish'] === true || body['publish'] === 'true') {
+        const publish = body['publish'] === true || body['publish'] === 'true';
+        if (publish) {
+            // Checked before the insert: a caller who asked for a live listing and
+            // gets a 400 should not find a draft they did not ask for either.
+            const problem = publishProblem(input);
+            if (problem !== null)
+                return fail(c, 400, 'pay_required', problem);
+        }
+        const job = await createJob(pool, input);
+        if (publish) {
             const published = await setStatus(pool, job.id, 'published');
             return c.json({ job: published ?? job }, 201);
         }
@@ -321,13 +369,17 @@ export function apiRoutes() {
             requirements: body['requirements'] ?? job.requirements,
             responsibilities: body['responsibilities'] ?? job.responsibilities,
             agentPolicy: body['agentPolicy'] ?? job.agentPolicy,
-            salaryMin: body['salaryMin'] ?? job.salary.min ?? undefined,
-            salaryMax: body['salaryMax'] ?? job.salary.max ?? undefined,
-            salaryCurrency: body['salaryCurrency'] ?? job.salary.currency,
-            salaryPeriod: body['salaryPeriod'] ?? job.salary.period,
+            ...payPatch(body, job),
         }, job.org.id);
         if (typeof merged === 'string')
             return fail(c, 400, 'invalid', merged);
+        // A live listing stays held to the publish rule: an edit that removes
+        // the pay would leave it public without one.
+        if (job.status === 'published') {
+            const problem = publishProblem(merged);
+            if (problem !== null)
+                return fail(c, 400, 'pay_required', problem);
+        }
         const updated = await editJob(pool, job.id, merged);
         return c.json({ job: updated ?? job });
     });
@@ -344,6 +396,13 @@ export function apiRoutes() {
         }
         const action = c.req.param('action');
         const status = action === 'close' ? 'closed' : 'published';
+        if (status === 'published') {
+            // Pay is required to go live. The message says what to send, because
+            // the caller is as likely to be an agent as a person.
+            const problem = publishProblem(job);
+            if (problem !== null)
+                return fail(c, 400, 'pay_required', problem);
+        }
         const updated = await setStatus(pool, job.id, status);
         return c.json({ job: updated });
     });
@@ -845,6 +904,100 @@ export function apiRoutes() {
         const items = await listFollowing(pool, viewer.id);
         return c.json({ items, total: items.length });
     });
+    // --- recommendations ----------------------------------------------------
+    /**
+     * Written by somebody who worked with the subject, shown once the subject
+     * approves. Reading is public: an approved recommendation is on the page.
+     */
+    api.get('/candidates/:slug/recommendations', async (c) => {
+        const { pool } = c.get('deps');
+        const userId = await userForCandidate(pool, c.req.param('slug'));
+        if (userId === null)
+            return fail(c, 404, 'not_found', `Nobody here is "${c.req.param('slug')}".`);
+        const items = await listApproved(pool, { kind: 'candidate', userId });
+        return c.json({ items, total: items.length });
+    });
+    api.get('/orgs/:slug/recommendations', async (c) => {
+        const { pool } = c.get('deps');
+        const org = await getOrgBySlug(pool, c.req.param('slug'));
+        if (org === null)
+            return fail(c, 404, 'not_found', `No employer here is "${c.req.param('slug')}".`);
+        const items = await listApproved(pool, { kind: 'employer', orgId: org.id });
+        return c.json({ items, total: items.length });
+    });
+    /**
+     * Write one. As yourself, which needs a published resume so it is signed
+     * by a page, or as an employer you post for ("as"). It is pending until
+     * the subject approves it, and writing again replaces it.
+     */
+    const recommend = async (c, target) => {
+        const { pool, config, mailer } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthorised', 'Sign in to write a recommendation.');
+        const body = await readBody(c);
+        const resolved = await resolveRecommendation(pool, viewer.id, {
+            ...target,
+            ...(typeof body['as'] === 'string' ? { as: body['as'] } : {}),
+        });
+        if (typeof resolved === 'string') {
+            const notFound = /^Nobody here|^No employer/.test(resolved);
+            const noPage = /Publish a resume|signed by a page/.test(resolved);
+            return fail(c, notFound ? 404 : noPage ? 403 : 400, notFound ? 'not_found' : noPage ? 'no_profile' : 'invalid', resolved);
+        }
+        const written = await writeRecommendation(pool, viewer.id, {
+            as: resolved.as,
+            subject: resolved.subject,
+            body: body['body'],
+            relationship: body['relationship'],
+        });
+        if (typeof written === 'string') {
+            return fail(c, /limit/.test(written) ? 429 : 400, /limit/.test(written) ? 'rate_limited' : 'invalid', written);
+        }
+        void notifySubject({
+            pool,
+            mailer,
+            boardName: config.boardName,
+            publicUrl: config.publicUrl,
+            recommendation: written,
+            subject: resolved.subject,
+        }).catch(() => undefined);
+        return c.json({ recommendation: written }, 201);
+    };
+    api.post('/candidates/:slug/recommendations', (c) => recommend(c, { candidate: c.req.param('slug') }));
+    api.post('/orgs/:slug/recommendations', (c) => recommend(c, { org: c.req.param('slug') }));
+    /** About you and your employers, every status, and what you wrote. */
+    api.get('/me/recommendations', async (c) => {
+        const { pool } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthorised', 'Sign in to see your recommendations.');
+        const [received, given] = await Promise.all([listReceived(pool, viewer.id), listGiven(pool, viewer.id)]);
+        return c.json({ received, given, pending: received.filter((item) => item.status === 'pending').length });
+    });
+    /**
+     * Approve or reject one written about you, or withdraw one you wrote. A
+     * 404 covers "no such recommendation" and "not yours to decide", which
+     * are the same fact to a caller who should not be able to tell.
+     */
+    api.post('/recommendations/:id/:action{approve|reject|withdraw}', async (c) => {
+        const { pool } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthorised', 'Sign in first.');
+        const id = c.req.param('id');
+        const action = c.req.param('action');
+        if (action === 'withdraw') {
+            const gone = await withdrawRecommendation(pool, viewer.id, id);
+            if (!gone)
+                return fail(c, 404, 'not_found', 'No such recommendation, or it is not yours to withdraw.');
+            return c.json({ withdrawn: true });
+        }
+        const decided = await decideRecommendation(pool, viewer.id, id, action === 'approve' ? 'approved' : 'rejected');
+        if (decided === null)
+            return fail(c, 404, 'not_found', 'No such recommendation, or it is not yours to decide.');
+        return c.json({ recommendation: decided });
+    });
     // --- sign in ----------------------------------------------------------
     api.post('/auth/magic-link', async (c) => {
         const { pool, config, mailer } = c.get('deps');
@@ -954,6 +1107,283 @@ export function apiRoutes() {
         const result = await federatedSearch(targetsFromDescriptors(instances.map((instance) => instance.descriptor)), query);
         return c.json(result);
     });
+    // --- inbox ------------------------------------------------------------
+    /**
+     * Private conversations. Everything here needs the caller's identity, and
+     * nothing here is visible to anyone outside the conversation: a thread id
+     * that is not yours is a 404, not a 403, so ids cannot be probed.
+     */
+    api.get('/inbox', async (c) => {
+        const { pool } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthenticated', 'Sign in to read your inbox.');
+        const items = await listThreads(pool, viewer.id);
+        return c.json({ items, total: items.length, unread: items.filter((t) => t.unread > 0).length });
+    });
+    /**
+     * Start a conversation, or continue the one these two parties already have.
+     *
+     * `candidate` or `employer` names who it is to, by slug. `as` is an employer
+     * slug to write as, for a member writing on the company's behalf. `job` ties
+     * it to a listing.
+     */
+    api.post('/inbox', async (c) => {
+        const { pool, config, mailer } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthenticated', 'Sign in to send a message.');
+        const body = await readBody(c);
+        const to = await counterpartyFrom(pool, {
+            candidate: typeof body['candidate'] === 'string' ? body['candidate'] : null,
+            employer: typeof body['employer'] === 'string' ? body['employer'] : null,
+        });
+        if (to === null) {
+            return fail(c, 404, 'not_found', 'Name a candidate or an employer by slug. Nobody here matches.');
+        }
+        const jobSlug = typeof body['job'] === 'string' ? body['job'].trim() : '';
+        const job = jobSlug === '' ? null : await getJobBySlug(pool, jobSlug);
+        if (jobSlug !== '' && job === null)
+            return fail(c, 404, 'not_found', `No job with the slug "${jobSlug}".`);
+        const asSlug = typeof body['as'] === 'string' ? body['as'].trim() : '';
+        const asOrg = asSlug === '' ? null : await getOrgBySlug(pool, asSlug);
+        if (asSlug !== '' && asOrg === null)
+            return fail(c, 404, 'not_found', `No employer with the slug "${asSlug}".`);
+        const started = await startThread(pool, viewer.id, to, {
+            subject: body['subject'],
+            body: body['body'],
+            jobId: job?.id ?? null,
+            as: asOrg?.id ?? null,
+        });
+        if (typeof started === 'string') {
+            return fail(c, started.includes('conversations today') ? 429 : 400, 'rejected', started);
+        }
+        await notifyParticipants(pool, {
+            mailer,
+            boardName: config.boardName,
+            publicUrl: config.publicUrl,
+            threadId: started.threadId,
+            senderId: viewer.id,
+            kind: 'text',
+        });
+        return c.json({ ...started, url: `${config.publicUrl}/inbox/${started.threadId}` }, started.created ? 201 : 200);
+    });
+    api.get('/inbox/:id', async (c) => {
+        const { pool, coinpay } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthenticated', 'Sign in to read your inbox.');
+        const id = c.req.param('id');
+        if (!isUuid(id))
+            return fail(c, 404, 'not_found', 'No such conversation.');
+        const thread = await getThread(pool, id, viewer.id);
+        if (thread === null)
+            return fail(c, 404, 'not_found', 'No such conversation.');
+        const invoices = await Promise.all((await listInvoicesIn(pool, coinpay, id)).map((invoice) => syncInvoice(pool, coinpay, invoice)));
+        await markRead(pool, id, viewer.id);
+        return c.json({ thread, invoices });
+    });
+    api.post('/inbox/:id/messages', async (c) => {
+        const { pool, config, mailer } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthenticated', 'Sign in to send a message.');
+        const id = c.req.param('id');
+        if (!isUuid(id))
+            return fail(c, 404, 'not_found', 'No such conversation.');
+        const body = await readBody(c);
+        const sent = await sendMessage(pool, id, viewer.id, body['body']);
+        if (typeof sent === 'string') {
+            return fail(c, sent.includes('not in that') ? 404 : 400, 'rejected', sent);
+        }
+        await notifyParticipants(pool, {
+            mailer,
+            boardName: config.boardName,
+            publicUrl: config.publicUrl,
+            threadId: id,
+            senderId: viewer.id,
+            kind: 'text',
+        });
+        return c.json({ message: sent }, 201);
+    });
+    // --- invoices and billing ------------------------------------------------
+    /**
+     * Send an invoice into a conversation. The caller is the payee; the money
+     * settles to the wallet on their connected CoinPay account, in `currency`
+     * (a chain they have a wallet on). Omit `currency` when there is one wallet.
+     */
+    api.post('/inbox/:id/invoices', async (c) => {
+        const { pool, config, mailer, coinpay } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthenticated', 'Sign in to send an invoice.');
+        const id = c.req.param('id');
+        if (!isUuid(id))
+            return fail(c, 404, 'not_found', 'No such conversation.');
+        const body = await readBody(c);
+        const invoice = await sendInvoice(pool, coinpay, {
+            threadId: id,
+            payeeId: viewer.id,
+            amount: body['amount'],
+            currency: body['currency'],
+            description: body['description'],
+        });
+        if (typeof invoice === 'string') {
+            return fail(c, invoice.includes('not in that') ? 404 : 400, 'rejected', invoice);
+        }
+        await notifyParticipants(pool, {
+            mailer,
+            boardName: config.boardName,
+            publicUrl: config.publicUrl,
+            threadId: id,
+            senderId: viewer.id,
+            kind: 'invoice',
+        });
+        return c.json({ invoice }, 201);
+    });
+    /** Every invoice the caller sent or can pay, newest first. */
+    api.get('/invoices', async (c) => {
+        const { pool, coinpay } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthenticated', 'Sign in to read your invoices.');
+        const items = await listInvoicesFor(pool, coinpay, viewer.id);
+        return c.json({ items, total: items.length });
+    });
+    api.get('/invoices/:id', async (c) => {
+        const { pool, coinpay } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthenticated', 'Sign in to read an invoice.');
+        const id = c.req.param('id');
+        if (!isUuid(id))
+            return fail(c, 404, 'not_found', 'No such invoice.');
+        const invoice = await getInvoice(pool, coinpay, id, viewer.id);
+        if (invoice === null)
+            return fail(c, 404, 'not_found', 'No such invoice.');
+        return c.json({ invoice: await syncInvoice(pool, coinpay, invoice) });
+    });
+    /**
+     * Get a live quote to pay an invoice. The response carries `payment.url`,
+     * the CoinPay page to pay on, and `payment.address` plus `amountCrypto` for
+     * a wallet that would rather pay directly.
+     */
+    api.post('/invoices/:id/pay', async (c) => {
+        const { pool, config, coinpay } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthenticated', 'Sign in to pay an invoice.');
+        const id = c.req.param('id');
+        if (!isUuid(id))
+            return fail(c, 404, 'not_found', 'No such invoice.');
+        const result = await requestPayment(pool, coinpay, {
+            invoiceId: id,
+            payerId: viewer.id,
+            publicUrl: config.publicUrl,
+        });
+        if (typeof result === 'string') {
+            return fail(c, result === 'No such invoice.' ? 404 : 400, 'rejected', result);
+        }
+        return c.json({ invoice: result });
+    });
+    api.post('/invoices/:id/cancel', async (c) => {
+        const { pool, coinpay } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthenticated', 'Sign in first.');
+        const id = c.req.param('id');
+        if (!isUuid(id))
+            return fail(c, 404, 'not_found', 'No such invoice.');
+        const invoice = await getInvoice(pool, coinpay, id, viewer.id);
+        if (invoice === null)
+            return fail(c, 404, 'not_found', 'No such invoice.');
+        const cancelled = await cancelInvoice(pool, id, viewer.id);
+        if (!cancelled) {
+            return fail(c, 409, 'not_cancellable', 'Only the sender can cancel an invoice, and only while it is unpaid.');
+        }
+        return c.json({ ok: true });
+    });
+    /**
+     * The caller's CoinPay connection: whether this board has billing at all,
+     * and whether this account is connected well enough to be paid.
+     */
+    api.get('/coinpay', async (c) => {
+        const { pool, config, coinpay } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthenticated', 'Sign in first.');
+        if (coinpay === null)
+            return c.json({ configured: false, account: null });
+        const account = await getAccount(pool, viewer.id);
+        return c.json({
+            configured: true,
+            account,
+            // Connecting needs a browser: it is CoinPay's consent screen.
+            connectUrl: `${config.publicUrl}/me/coinpay/connect`,
+        });
+    });
+    api.delete('/coinpay', async (c) => {
+        const { pool } = c.get('deps');
+        const viewer = viewerOf(c);
+        if (viewer === null)
+            return fail(c, 401, 'unauthenticated', 'Sign in first.');
+        return c.json({ ok: await disconnect(pool, viewer.id) });
+    });
+    /**
+     * Where CoinPay sends the person after consent. Under /api/v1 because that
+     * is the path registered on the OAuth client; it answers a browser, with a
+     * redirect, not JSON.
+     */
+    api.get('/coinpay/callback', async (c) => {
+        const { pool, config, coinpay } = c.get('deps');
+        const params = new URL(c.req.url).searchParams;
+        const code = params.get('code') ?? '';
+        const state = params.get('state') ?? '';
+        if (params.get('error') !== null) {
+            const said = params.get('error_description') ?? params.get('error') ?? 'refused';
+            return c.redirect(`/me?coinpay=${encodeURIComponent(`CoinPay said: ${said}`)}#billing`, 303);
+        }
+        if (code === '' || state === '')
+            return fail(c, 400, 'bad_request', 'Missing code or state.');
+        if (coinpay === null)
+            return fail(c, 404, 'not_found', 'This board has no payment rail configured.');
+        const done = await finishConnect(pool, coinpay, {
+            state,
+            code,
+            redirectUri: coinpayRedirectUri(config.publicUrl),
+        });
+        if (typeof done === 'string') {
+            return c.redirect(`/me?coinpay=${encodeURIComponent(done)}#billing`, 303);
+        }
+        const back = done.redirect ?? '/me#billing';
+        if (back.startsWith('/me'))
+            return c.redirect('/me?coinpay=connected#billing', 303);
+        return c.redirect(`${back}${back.includes('?') ? '&' : '?'}coinpay=connected`, 303);
+    });
+    /**
+     * CoinPay telling us a payment settled. Verified against the business's
+     * webhook secret; an unsigned or mis-signed body is dropped with a 401 and
+     * the invoice waits for the next page load to ask CoinPay directly.
+     */
+    api.post('/coinpay/webhook', async (c) => {
+        const { pool, coinpay } = c.get('deps');
+        if (coinpay === null)
+            return fail(c, 404, 'not_found', 'This board has no payment rail configured.');
+        const raw = await c.req.text();
+        if (!coinpay.verifyWebhook(raw, c.req.header('x-coinpay-signature'))) {
+            return fail(c, 401, 'bad_signature', "The signature does not match this board's webhook secret.");
+        }
+        let payload;
+        try {
+            const parsed = JSON.parse(raw);
+            payload = typeof parsed === 'object' && parsed !== null ? parsed : {};
+        }
+        catch {
+            return fail(c, 400, 'bad_request', 'The body is not JSON.');
+        }
+        const outcome = await applyWebhook(pool, payload);
+        return c.json({ received: true, outcome });
+    });
     // --- this instance ----------------------------------------------------
     api.get('/openapi.json', (c) => {
         const { config } = c.get('deps');