@volter/twin-hubspot 0.1.0

package/src/screens/developer.tsx

@@ -0,0 +1,181 @@
+// AN ACCOUNT'S APPS — the developer projects an account builds and the pages it manages each app on
+// (https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot).
+//
+// - POST /_twin/accounts/:hubId/projects {name, uploadedBy, platformVersion, app, webhooks?}: stands in for `hs project
+//   upload`, the HubSpot CLI's upload of a project to the account's developer file system, whose API HubSpot does not
+//   document (the CLI's requests are its own: a zip of the project and the intermediate representation
+//   @hubspot/project-parsing-lib makes of it, then a build and a deploy it polls). `app` is the project's
+//   `app-hsmeta.json` and `webhooks` its `webhooks/*-hsmeta.json`, as the configuration pages define them
+//   (https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration,
+//   https://developers.hubspot.com/docs/apps/developer-platform/add-features/configure-webhooks); a second upload of a
+//   project updates its app, keeping the app's id, client ID and secret. 201 with the build's app.
+// - /developer-projects/:hubId/project/:name/component/:uid/auth: the app's authentication details, "Your app's
+//   *Client ID* and *Client secret* will appear in the *Client credentials* section", and its redirect URLs and scopes.
+// - /developer-projects/:hubId/project/:name/component/:uid/distribution: for an OAuth marketplace app, **Begin
+//   publishing** and the Acceptable Use Policy ("Until the AUP is signed, you won't be able to install your app in
+//   accounts other than developer test accounts"), then the sample install URL and the installed accounts ("Until your
+//   app is reviewed … you'll be limited to 25 installs"); for a static-token app, **Install now**, HubSpot's consent
+//   (**Connect app**), and the access token, which **Show** reveals.
+// - POST /developer-projects/:hubId/project/:name/delete: deletes the project and its app.
+//
+// Where the documentation stops and the twin decides: the pages' paths and layout; an app id counts from 30000001; a
+// client ID and secret are UUIDs (the OAuth page's `client_id=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`), a static token is
+// `pat-na1-` and a UUID (the authentication overview masks one as `***-***-*********-…`); only a super admin of the
+// account may manage its apps; the AUP panel's text is the twin's summary, not HubSpot's policy; no app the World builds
+// is ever reviewed, so every install of a marketplace app is of an unverified app.
+import { accountOf, appsOf, hex, installOf, keep, personOf, stored, type Row } from '../accounts.ts';
+import { CSS, formOf, page, personFor, portalPage, redirect, who } from './page.tsx';
+import { Consent } from '@volter/world-ui';
+
+const uuid = (seed: string): string => { const h = hex(seed); return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`; };
+const INSTALL_CAP = 25;
+
+type Hsmeta = { uid?: unknown; type?: unknown; config?: Row };
+
+/** The door standing in for `hs project upload`. */
+export async function uploadDoor(hubId: number, request: Request, root: string | undefined, at: string): Promise<Response> {
+  let body: Row = {};
+  try { body = JSON.parse(await request.text()) as Row; } catch { /* refused below */ }
+  const refuse = (message: string): Response => Response.json({ status: 'error', message, category: 'VALIDATION_ERROR' }, { status: 400 });
+  const account = accountOf(hubId, root);
+  const uploader = personOf(String(body.uploadedBy ?? ''), root);
+  if (!account || account.closed_at) return refuse(`no open account ${hubId}`);
+  if (!uploader || uploader.hubId !== hubId || uploader.superAdmin !== true) return refuse('uploadedBy must be a super admin of the account');
+  const name = typeof body.name === 'string' ? body.name.trim() : '';
+  const app = body.app as Hsmeta | undefined;
+  const c = app?.config;
+  const auth = c?.auth as Row | undefined;
+  if (!name || !app || app.type !== 'app' || typeof app.uid !== 'string' || !c) return refuse('a project name and its app component (app-hsmeta.json: uid, type "app", config) are required');
+  if (typeof c.name !== 'string' || typeof c.description !== 'string') return refuse('app config requires name and description');
+  if (c.distribution !== 'marketplace' && c.distribution !== 'private') return refuse('distribution must be marketplace or private');
+  if (!auth || (auth.type !== 'oauth' && auth.type !== 'static')) return refuse('auth.type must be oauth or static');
+  if (c.distribution === 'marketplace' && auth.type !== 'oauth') return refuse('a marketplace app must use oauth');
+  const redirectUrls = Array.isArray(auth.redirectUrls) ? auth.redirectUrls.map(String) : [];
+  // "Each app must have at least one auth redirect URL, and it must use HTTPS. The only exception is that http://localhost is allowed"
+  if (auth.type === 'oauth' && (!redirectUrls.length || redirectUrls.some((u) => !u.startsWith('https://') && !u.startsWith('http://localhost')))) return refuse('an oauth app needs at least one redirect URL, each HTTPS (or http://localhost)');
+  const requiredScopes = Array.isArray(auth.requiredScopes) ? auth.requiredScopes.map(String) : [];
+  if (!requiredScopes.length) return refuse('an app must include at least one required scope');
+  const hooks = body.webhooks as Hsmeta | undefined;
+  const settings = (hooks?.config?.settings ?? {}) as Row;
+  const crmObjects = (((hooks?.config?.subscriptions ?? {}) as Row).crmObjects ?? []) as Row[];
+  if (hooks && (hooks.type !== 'webhooks' || typeof settings.targetUrl !== 'string')) return refuse('the webhooks component needs type "webhooks" and settings.targetUrl');
+  const existing = stored('_app', root).find((a) => a.hubId === hubId && a.project === name && !a.deleted_at);
+  const appId = existing ? Number(existing.appId) : 30000000 + stored('_app', root).length + 1;
+  const fields: Row = {
+    appId, hubId, project: name, uid: app.uid, name: c.name, description: c.description, distribution: c.distribution,
+    authType: auth.type, redirectUrls, requiredScopes,
+    optionalScopes: Array.isArray(auth.optionalScopes) ? auth.optionalScopes.map(String) : [],
+    platformVersion: typeof body.platformVersion === 'string' ? body.platformVersion : '2026.03',
+    client_id: existing?.client_id ?? uuid(`hubspot-client:${appId}`),
+    client_secret: existing?.client_secret ?? uuid(`hubspot-secret:${appId}:${at}`),
+    webhooks: hooks ? {
+      targetUrl: settings.targetUrl,
+      subscriptions: crmObjects.map((s, i) => ({ id: appId * 100 + i + 1, subscriptionType: s.subscriptionType, objectType: s.objectType, ...(s.propertyName ? { propertyName: s.propertyName } : {}), active: s.active !== false })),
+    } : null,
+    publishing: existing?.publishing ?? null, aup_signed_at: existing?.aup_signed_at ?? null, aup_signed_by: existing?.aup_signed_by ?? null,
+    created_at: existing?.created_at ?? at, uploaded_at: at, uploaded_by: uploader.email, deleted_at: null,
+  };
+  await keep('_app', `app:${appId}`, fields, root, at, String(uploader.email));
+  return Response.json({ project: name, appId, uid: app.uid, url: `/developer-projects/${hubId}/project/${encodeURIComponent(name)}/component/${encodeURIComponent(String(app.uid))}/auth` }, { status: 201 });
+}
+
+const base = (a: Row): string => `/developer-projects/${String(a.hubId)}/project/${encodeURIComponent(String(a.project))}/component/${encodeURIComponent(String(a.uid))}`;
+
+function authPage(a: Row, account: Row, person: Row): Response {
+  return portalPage(`${String(a.name)} · Auth`, {
+    merchant: who(account, person), back: { href: `${base(a)}/distribution`, label: 'Distribution' },
+    sections: [
+      { heading: 'Client credentials', items: a.authType === 'oauth'
+        ? [{ title: 'Client ID', detail: String(a.client_id) }, { title: 'Client secret', detail: String(a.client_secret) }]
+        : [], empty: 'A static-token app has no client credentials; its access token is on the Distribution tab.' },
+      { heading: 'Redirect URLs', items: (a.redirectUrls as string[]).map((u) => ({ title: u })), empty: 'None.' },
+      { heading: 'Scopes', items: [...(a.requiredScopes as string[]).map((s) => ({ title: s, detail: 'Required' })), ...(a.optionalScopes as string[]).map((s) => ({ title: s, detail: 'Optional' }))] },
+    ],
+  });
+}
+
+function installUrl(a: Row): string {
+  const q = new URLSearchParams({ client_id: String(a.client_id), redirect_uri: (a.redirectUrls as string[])[0] ?? '', scope: ['oauth', ...(a.requiredScopes as string[])].join(' ') });
+  return `https://app.hubspot.com/oauth/authorize?${q.toString()}`;
+}
+
+function distributionPage(a: Row, account: Row, person: Row, root: string | undefined, opts: { notice?: string; show?: boolean; aup?: boolean } = {}): Response {
+  const installs = stored('_install', root).filter((i) => i.appId === a.appId && !i.uninstalled_at);
+  const d = `${base(a)}/distribution`;
+  if (a.authType === 'static') {
+    const install = installOf(Number(a.appId), Number(a.hubId), root);
+    return portalPage(`${String(a.name)} · Distribution`, {
+      merchant: who(account, person), back: { href: `${base(a)}/auth`, label: 'Auth' }, ...(opts.notice ? { notice: opts.notice } : {}),
+      sections: [{ heading: 'Manage distribution', items: [install
+        ? { title: String(account.name), detail: `Access token: ${opts.show ? String(install.static_token) : `${String(install.static_token).slice(0, 8)}${'•'.repeat(12)}`}`, note: `Installed ${String(install.installed_at).slice(0, 10)}`, actions: opts.show ? [] : [{ label: 'Show', action: `${d}?show=token`, method: 'get' as const }] }
+        : { title: String(account.name), detail: 'Not installed', actions: [{ label: 'Install now', action: `${d}/install` }] }] }],
+    });
+  }
+  const published = !!a.publishing;
+  const signed = !!a.aup_signed_at;
+  return portalPage(`${String(a.name)} · Distribution`, {
+    merchant: who(account, person), back: { href: `${base(a)}/auth`, label: 'Auth' }, ...(opts.notice ? { notice: opts.notice } : {}),
+    sections: [
+      { heading: 'Distribution', items: [signed
+        ? { title: 'Unlisted marketplace app', detail: `Install URL: ${installUrl(a)}`, note: `${installs.length} of ${INSTALL_CAP} installs before listing` }
+        : { title: 'Not published', detail: 'Until the AUP is signed, you won\'t be able to install your app in accounts other than developer test accounts.', actions: [{ label: published ? 'Continue publishing' : 'Begin publishing', action: `${d}/begin-publishing`, tone: 'primary' as const }] }] },
+      ...(opts.aup && !signed ? [{ heading: 'Acceptable Use Policy', items: [{ title: 'HubSpot App Acceptable Use Policy', detail: 'Review and sign the policy to install this app in accounts other than developer test accounts.', actions: [{ label: 'Sign', action: `${d}/aup`, tone: 'primary' as const, fields: { accept: 'yes' } }] }] }] : []),
+      { heading: 'Installed accounts', items: installs.map((i) => ({ title: String(accountOf(Number(i.hubId), root)?.name ?? i.hubId), note: `Installed ${String(i.installed_at).slice(0, 10)}` })), empty: 'No installs yet.' },
+    ],
+  });
+}
+
+/** app.hubspot.com/developer-projects/…, or undefined for another path. */
+export async function developerPages(request: Request, root: string | undefined, at: string): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const m = /^\/developer-projects\/(\d+)\/project\/([^/]+)(?:\/component\/([^/]+)\/(auth|distribution)(?:\/(begin-publishing|aup|install|install\/confirm))?|\/(delete))$/.exec(url.pathname.replace(/\/+$/, ''));
+  if (!m) return undefined;
+  const hubId = Number(m[1]);
+  const got = personFor(request, hubId, root);
+  if (got instanceof Response) return got;
+  const { person, account } = got;
+  if (person.superAdmin !== true) return page('HubSpot', CSS.portal, <main className="portal-main"><h1>Only a super admin can manage this account's apps.</h1></main>, 403);
+  const app = appsOf(hubId, root).find((a) => a.project === decodeURIComponent(m[2]!) && (m[3] === undefined || a.uid === decodeURIComponent(m[3])));
+  if (!app) return page('HubSpot', CSS.portal, <main className="portal-main"><h1>This project doesn't exist.</h1></main>, 404);
+  const actor = String(person.email);
+  if (m[6] === 'delete') {
+    if (request.method !== 'POST') return undefined;
+    await keep('_app', `app:${String(app.appId)}`, { ...app, deleted_at: at, deleted_by: actor }, root, at, actor);
+    return portalPage('Projects', { merchant: who(account, person), notice: `Project ${String(app.project)} deleted.`, sections: [] });
+  }
+  const tab = m[4]!;
+  const act = m[5];
+  if (!act) {
+    if (request.method !== 'GET') return undefined;
+    return tab === 'auth' ? authPage(app, account, person) : distributionPage(app, account, person, root, { show: url.searchParams.get('show') === 'token' });
+  }
+  if (request.method !== 'POST' || tab !== 'distribution') return undefined;
+  if (act === 'begin-publishing' && app.distribution === 'marketplace') {
+    const withPanel = { ...app, publishing: app.publishing ?? at };
+    if (!app.publishing) await keep('_app', `app:${String(app.appId)}`, withPanel, root, at, actor);
+    return distributionPage(withPanel, account, person, root, { aup: true });
+  }
+  if (act === 'aup' && app.distribution === 'marketplace' && app.publishing) {
+    if ((await formOf(request)).accept !== 'yes') return distributionPage(app, account, person, root, { aup: true, notice: 'Sign the Acceptable Use Policy to continue.' });
+    const signed = { ...app, aup_signed_at: at, aup_signed_by: actor };
+    await keep('_app', `app:${String(app.appId)}`, signed, root, at, actor);
+    return distributionPage(signed, account, person, root, { notice: 'Acceptable Use Policy signed. You can install this app with its install URL.' });
+  }
+  if (act === 'install' && app.authType === 'static') {
+    return page(`Connect ${String(app.name)}`, CSS.consent, (
+      <Consent heading={`Connect ${String(app.name)} to ${String(account.name)}`} app={{ name: String(app.name) }}
+        request={`${String(account.name)} · Hub ID ${hubId}`}
+        permissions={(app.requiredScopes as string[]).map((s) => ({ title: s, detail: 'Requested scope' }))}
+        action={`${base(app)}/distribution/install/confirm`} fields={{}}
+        deny={{ name: 'answer', value: 'cancel', label: 'Cancel' }} allow={{ name: 'answer', value: 'allow', label: 'Connect app' }} />
+    ));
+  }
+  if (act === 'install/confirm' && app.authType === 'static') {
+    if ((await formOf(request)).answer !== 'allow') return redirect(`${base(app)}/distribution`);
+    if (installOf(Number(app.appId), hubId, root)) return distributionPage(app, account, person, root, { notice: 'This app is already installed.' });
+    const token = `pat-na1-${uuid(`hubspot-static:${String(app.appId)}:${at}`)}`;
+    await keep('_install', `install:${String(app.appId)}:${hubId}:${at}`, { appId: app.appId, hubId, installed_by: actor, scopes: app.requiredScopes, installed_at: at, uninstalled_at: null, static_token: token }, root, at, actor);
+    return redirect(`${base(app)}/distribution`);
+  }
+  return undefined;
+}

package/src/screens/forms.tsx

@@ -0,0 +1,117 @@
+// HUBSPOT FORMS — an account's forms, built on its form builder and filled in on a website
+// (https://knowledge.hubspot.com/forms/create-forms; Dub's guide, https://dub.co/docs/integrations/hubspot, "Option 1: Using HubSpot
+// Forms": "In the HubSpot form builder, add a hidden field and map it to the **Dub Id** contact property").
+//
+// - app.hubspot.com/forms/:hubId: the account's forms, and **Create form** with its name (a form starts with Email,
+//   First name and Last name, contact fields).
+// - app.hubspot.com/forms/:hubId/editor/:formGuid/edit: the form's fields, and **Add hidden field** mapped to a contact
+//   property a form may use (a property with `formField`, as Dub makes its Dub Click ID: `formField: true`, "Allow the
+//   property to be used in a HubSpot form").
+// - POST https://api.hsforms.com/submissions/v3/integration/submit/:portalId/:formGuid: a visitor's submission, as HubSpot's
+//   Forms API takes it ("Submit data to a form (unauthenticated)",
+//   https://developers.hubspot.com/docs/api-reference/legacy/marketing/forms/v3-legacy/submit-data-unauthenticated):
+//   `fields`, each `{objectTypeId, name, value}`, and `context`; a field the form does not have is refused
+//   (`FIELD_NOT_IN_FORM_DEFINITION`), and an accepted submission answers `inlineMessage`. It makes or updates the
+//   contact with that email in the form's account (portal.ts: `FORM`), whose webhook events follow.
+//
+// Where the documentation stops and the twin decides: the builder's paths and layout; a new form's three fields and its
+// thank-you message ("Thanks for submitting the form."); the embed Dub's guide puts on a site (js.hsforms.net) submits
+// through a request HubSpot does not document, so a visitor's submission is the Forms API's documented one; a submission
+// without an email, or with one that is not an address, is refused as `INVALID_EMAIL`; a contact is found by its email
+// to be updated, as HubSpot deduplicates contacts by email.
+import { accountOf, hex, keep, stored, type Row } from '../accounts.ts';
+import { handleHubspotTwinRequest } from '../hubspot-twin.ts';
+import { inPortal } from '../portal.ts';
+import { formOf, personFor, portalPage, redirect, who } from './page.tsx';
+
+export const FORMS_HOST = 'api.hsforms.com';
+const DEFAULT_FIELDS = [
+  { name: 'email', label: 'Email', hidden: false },
+  { name: 'firstname', label: 'First name', hidden: false },
+  { name: 'lastname', label: 'Last name', hidden: false },
+];
+
+const formsOf = (hub: number, root?: string): Row[] => stored('_form', root).filter((f) => f.hubId === hub && !f.archived);
+const uuid = (seed: string): string => { const h = hex(seed); return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20, 32)}`; };
+
+/** app.hubspot.com/forms/…, or undefined for another path. */
+export async function formPages(request: Request, root: string | undefined, at: string): Promise<Response | undefined> {
+  const path = new URL(request.url).pathname.replace(/\/+$/, '');
+  const m = /^\/forms\/(\d+)(?:\/editor\/([0-9a-f-]+)\/edit)?$/.exec(path);
+  if (!m) return undefined;
+  const hub = Number(m[1]);
+  const got = personFor(request, hub, root);
+  if (got instanceof Response) return got;
+  const { person, account } = got;
+  const actor = String(person.email);
+  if (!m[2]) {
+    if (request.method === 'POST') {
+      const name = ((await formOf(request)).name ?? '').trim();
+      if (!name) return listPage(hub, account, person, root, 'A form needs a name.', 422);
+      const guid = uuid(`hubspot-form:${hub}:${name}:${at}`);
+      await keep('_form', `form:${guid}`, { guid, hubId: hub, name, fields: DEFAULT_FIELDS, created_at: at, created_by: actor, archived: false }, root, at, actor);
+      return redirect(`/forms/${hub}/editor/${guid}/edit`);
+    }
+    return listPage(hub, account, person, root);
+  }
+  const form = formsOf(hub, root).find((f) => f.guid === m[2]);
+  if (!form) return portalPage('Forms', { merchant: who(account, person), notice: 'This form does not exist.', sections: [] }, 404);
+  const properties = await inPortal({ hub, source: 'CRM_UI' }, () => handleHubspotTwinRequest({ method: 'GET', path: '/crm/v3/properties/contacts', root, occurredAt: at }));
+  const usable = (((properties.body as Row).results ?? []) as Row[]).filter((p) => p.formField === true && p.archived !== true);
+  let notice: string | undefined;
+  if (request.method === 'POST') {
+    const wanted = (await formOf(request)).property;
+    const property = usable.find((p) => p.name === wanted);
+    const fields = form.fields as Row[];
+    if (!property) notice = 'Choose a contact property that can be used in forms.';
+    else if (fields.some((f) => f.name === property.name)) notice = `${String(property.label)} is already on this form.`;
+    else {
+      await keep('_form', `form:${String(form.guid)}`, { ...form, fields: [...fields, { name: property.name, label: property.label, hidden: true }], updated_at: at }, root, at, actor);
+      return redirect(`/forms/${hub}/editor/${String(form.guid)}/edit`);
+    }
+  }
+  return portalPage(String(form.name), { merchant: who(account, person), back: { href: `/forms/${hub}`, label: 'Forms' }, ...(notice ? { notice } : {}),
+    sections: [{ heading: 'Fields', items: (form.fields as Row[]).map((f) => ({ title: String(f.label), detail: String(f.name), ...(f.hidden ? { badge: 'Hidden' } : {}) })) },
+      { heading: 'Embed', items: [{ title: 'Form ID', detail: String(form.guid) }, { title: 'Portal ID', detail: String(hub) }] }],
+    forms: [{ heading: 'Add hidden field', action: `/forms/${hub}/editor/${String(form.guid)}/edit`, submit: { label: 'Add' },
+      fields: [{ id: 'property', label: 'Contact property', options: usable.map((p) => ({ value: String(p.name), label: String(p.label) })) }] }] });
+}
+
+function listPage(hub: number, account: Row, person: Row, root: string | undefined, notice?: string, status = 200): Response {
+  return portalPage('Forms', { merchant: who(account, person), ...(notice ? { notice } : {}),
+    sections: [{ heading: 'Forms', empty: 'No forms yet.', items: formsOf(hub, root).map((f) => ({ title: String(f.name), detail: String(f.guid), actions: [{ label: 'Edit', action: `/forms/${hub}/editor/${String(f.guid)}/edit`, method: 'get' as const }] })) }],
+    forms: [{ heading: 'Create form', action: `/forms/${hub}`, submit: { label: 'Create form' }, fields: [{ id: 'name', label: 'Form name' }] }] }, status);
+}
+
+const submitError = (errorType: string, message: string): Response => Response.json({ status: 'error', message: 'The request is not valid', errors: [{ message, errorType }] }, { status: 400 });
+
+/** api.hsforms.com's submission, or undefined for another request. */
+export async function formSubmission(request: Request, root: string | undefined, at: string): Promise<Response | undefined> {
+  const m = /^\/submissions\/v3\/integration\/submit\/(\d+)\/([0-9a-f-]+)$/.exec(new URL(request.url).pathname.replace(/\/+$/, ''));
+  if (!m || request.method !== 'POST') return undefined;
+  const hub = Number(m[1]);
+  const form = accountOf(hub, root)?.closed_at ? undefined : formsOf(hub, root).find((f) => f.guid === m[2]);
+  if (!form) return Response.json({ status: 'error', message: 'Form not found', category: 'OBJECT_NOT_FOUND' }, { status: 404 });
+  let body: Row = {};
+  try { body = JSON.parse(await request.text()) as Row; } catch { return submitError('INVALID_METADATA', 'The request body is not valid JSON.'); }
+  const fields = Array.isArray(body.fields) ? (body.fields as Row[]) : [];
+  const names = new Set((form.fields as Row[]).map((f) => String(f.name)));
+  const properties: Record<string, string> = {};
+  for (const f of fields) {
+    if (!names.has(String(f.name))) return submitError('FIELD_NOT_IN_FORM_DEFINITION', `${String(f.name)} is not a field of this form.`);
+    properties[String(f.name)] = String(f.value ?? '');
+  }
+  const email = (properties.email ?? '').trim().toLowerCase();
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) return submitError('INVALID_EMAIL', 'Email address is invalid.');
+  properties.email = email;
+  await inPortal({ hub, source: 'FORM', sourceId: String(form.guid) }, async () => {
+    const found = await handleHubspotTwinRequest({ method: 'POST', path: '/crm/v3/objects/contacts/search', body: JSON.stringify({ filterGroups: [{ filters: [{ propertyName: 'email', operator: 'EQ', value: email }] }], limit: 1 }), root, occurredAt: at });
+    const id = ((((found.body as Row).results ?? []) as Row[])[0])?.id;
+    await handleHubspotTwinRequest(id === undefined
+      ? { method: 'POST', path: '/crm/v3/objects/contacts', body: JSON.stringify({ properties }), root, occurredAt: at }
+      : { method: 'PATCH', path: `/crm/v3/objects/contacts/${String(id)}`, body: JSON.stringify({ properties }), root, occurredAt: at });
+  });
+  const n = stored('_form_submission', root).length + 1;
+  await keep('_form_submission', `submission:${n}`, { n, formGuid: form.guid, hubId: hub, fields, context: body.context ?? null, submitted_at: at }, root, at, email);
+  return Response.json({ inlineMessage: 'Thanks for submitting the form.' });
+}

package/src/screens/page.tsx

@@ -0,0 +1,55 @@
+// What every HubSpot page the twin serves shares: HubSpot's skin over @volter/world-ui's pieces, the signed-in person a
+// page requires, and a form body. Nothing of HubSpot's pages is copied.
+import type { ReactElement } from 'react';
+import { CONSENT_CSS, flowPage, Portal, PORTAL_CSS, SIGN_IN_CSS, type PortalProps } from '@volter/world-ui';
+import { accountOf, signedIn, type Row } from '../accounts.ts';
+
+// HubSpot's skin: its slate ink, light grey panels and orange primary buttons
+export const SKIN = `
+body { background: #ffffff; color: #33475b; font-family: "Lexend Deca", Helvetica, Arial, sans-serif; }
+.sign-in-mark, .consent-vendor { background: #ff7a59; }
+.sign-in-box, .consent-box { background: #ffffff; border-color: #cbd6e2; }
+.sign-in-error { background: #fdedee; border-color: #f2545b; }
+.sign-in-submit, .consent-allow, .portal-primary { background: #ff7a59; border-color: #ff7a59; color: #ffffff; }
+.consent-badge { background: #f5f8fa; border: 1px solid #cbd6e2; color: #33475b; }
+.consent-link, .consent-actions { border-color: #cbd6e2; }
+.consent-who small, .consent-permission summary small, .consent-note { color: #516f90; }
+.consent-deny { background: #ffffff; border-color: #cbd6e2; color: #33475b; }
+.portal-side { background: #f5f8fa; border-right: 1px solid #cbd6e2; }
+.portal-section h2 { border-color: #cbd6e2; color: #516f90; }
+.portal-notice { background: #e5f5f8; border: 1px solid #7fd1de; word-break: break-all; }
+.portal-button { background: #ffffff; border-color: #cbd6e2; color: #33475b; }
+.portal-danger { color: #d94c53; }
+`;
+export const CSS = { signIn: [SIGN_IN_CSS, SKIN], consent: [CONSENT_CSS, SKIN], portal: [PORTAL_CSS, SKIN] };
+
+/** A settings or record page: the account and person on the left, the page's sections and forms. */
+export function portalPage(title: string, props: PortalProps, status = 200): Response {
+  return flowPage({ title: `${title} | HubSpot`, css: CSS.portal, status, body: <Portal {...props} /> });
+}
+
+export function page(title: string, css: string[], body: ReactElement, status = 200): Response {
+  return flowPage({ title: `${title} | HubSpot`, css, status, body });
+}
+
+export function redirect(location: string): Response {
+  return new Response(null, { status: 302, headers: { location } });
+}
+
+export async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+/** The person a page needs, signed in to the account the page is of; a redirect to the sign-in, or a refusal, if not. */
+export function personFor(request: Request, hubId: number | undefined, root?: string): { person: Row; account: Row } | Response {
+  const person = signedIn(request, root);
+  const url = new URL(request.url);
+  if (!person) return redirect(`/login?loginRedirectUrl=${encodeURIComponent(url.pathname + url.search)}`);
+  const account = accountOf(Number(person.hubId), root);
+  if (!account || (hubId !== undefined && Number(person.hubId) !== hubId)) return page('HubSpot', CSS.portal, <main className="portal-main"><h1>You don't have access to this account.</h1></main>, 403);
+  if (account.closed_at) return page('HubSpot', CSS.portal, <main className="portal-main"><h1>This account has been closed.</h1></main>, 403);
+  return { person, account };
+}
+
+/** The left column every account page carries. */
+export const who = (account: Row, person: Row): string => `${String(account.name)} · ${String(person.email)}`;

package/src/screens/session.tsx

@@ -0,0 +1,36 @@
+// HUBSPOT'S SIGN-IN — app.hubspot.com/login (docs/contributing/architecture.md, "Who is on a screen"): a person gives
+// the email and password the World gave them (accounts.ts's sign-up door), and the session cookie names them to every
+// page after; a page asked for by nobody signed in sends its visitor here with `loginRedirectUrl`, and the sign-in returns
+// them there. Built from @volter/world-ui's sign-in under HubSpot's skin.
+//
+// Where the documentation stops and the twin decides: the cookie is `hs_session`; a refused sign-in shows the form again
+// with "The email or password you entered is incorrect." (200); HubSpot's own sign-in also offers Google, Microsoft and
+// single sign-on, which the twin does not model.
+import { SignIn } from '@volter/world-ui';
+import { hex, keep, passwordHash, personOf, SESSION_COOKIE, stored } from '../accounts.ts';
+import { CSS, formOf, page } from './page.tsx';
+
+/** A return address on app.hubspot.com, never another site. */
+const back = (raw: string | null | undefined): string => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : '/');
+
+function signInPage(to: string, email?: string, error?: string): Response {
+  return page('Log in', CSS.signIn, (
+    <SignIn heading="Log in to HubSpot" action="/login" fields={{ loginRedirectUrl: to }}
+      account={{ name: 'email', label: 'Email address', ...(email ? { value: email } : {}) }}
+      password={{ name: 'password', label: 'Password' }} submit="Log in" {...(error ? { error } : {})} />
+  ));
+}
+
+export async function signIn(request: Request, root: string | undefined, at: string): Promise<Response> {
+  if (request.method === 'GET') return signInPage(back(new URL(request.url).searchParams.get('loginRedirectUrl')));
+  const f = await formOf(request);
+  const email = (f.email ?? '').trim().toLowerCase();
+  const to = back(f.loginRedirectUrl);
+  const person = personOf(email, root);
+  if (!person || person.hash !== passwordHash(email, f.password ?? '')) return signInPage(to, email, 'The email or password you entered is incorrect.');
+  const token = hex(`hubspot-session:${email}:${at}:${stored('_web_session', root).length + 1}`).slice(0, 40);
+  await keep('_web_session', `session:${token}`, { token, email, created_at: at }, root, at, email);
+  const headers = new Headers({ location: to });
+  headers.append('set-cookie', `${SESSION_COOKIE}=${token}; Path=/; HttpOnly; Secure; SameSite=Lax`);
+  return new Response(null, { status: 302, headers });
+}

package/src/semantics/crm.ts

@@ -0,0 +1,116 @@
+// HubSpot's handlers, by operationId (docs/contributing/architecture.md, "The semantics layer"): every operation of the
+// nine documents' union (../generated/surface.gen.json) the twin serves. Each CRM operation delegates to the pack's
+// request handler (../hubspot-twin.ts), which keeps HubSpot's records, properties, pipelines, owners and associations
+// and answers in HubSpot's `{status: "error", message, correlationId, category}` body; each OAuth operation to the
+// install's token endpoints (../hubspot-oauth.tsx). An operation of the surface not named here is the gap: a contact's
+// GDPR delete, the properties' batch read and batch archive, the pipeline and stage audits, the associations' batch
+// default and label-archive calls and high-usage report, and the refresh-token reads and deletes.
+//
+// These are dispatch handlers, not `bindSemantics` ones, as turbopuffer's are: a record write is one kernel action
+// over the record and the associations it names, which a semantics context's single-subject write cannot make, and the
+// request handler's store is the vendor's behaviour.
+import type { DerivedCall, DerivedHandler } from '@volter/world-core';
+
+/** The operations served by the pack's request handler, every CRM operation the twin serves. */
+export const CRM_HANDLED = [
+  // /crm/v3/objects
+  'delete-/crm/v3/objects/0-3/{dealId}_archive',
+  'delete-/crm/v3/objects/companies/{companyId}_archive',
+  'delete-/crm/v3/objects/contacts/{contactId}_archive',
+  'delete-/crm/v3/objects/tickets/{ticketId}_archive',
+  'get-/crm/v3/objects/0-3_getPage',
+  'get-/crm/v3/objects/0-3/{dealId}_getById',
+  'get-/crm/v3/objects/companies_getPage',
+  'get-/crm/v3/objects/companies/{companyId}_getById',
+  'get-/crm/v3/objects/contacts_getPage',
+  'get-/crm/v3/objects/contacts/{contactId}_getById',
+  'get-/crm/v3/objects/tickets_getPage',
+  'get-/crm/v3/objects/tickets/{ticketId}_getById',
+  'patch-/crm/v3/objects/0-3/{dealId}_update',
+  'patch-/crm/v3/objects/companies/{companyId}_update',
+  'patch-/crm/v3/objects/contacts/{contactId}_update',
+  'patch-/crm/v3/objects/tickets/{ticketId}_update',
+  'post-/crm/v3/objects/0-3_create',
+  'post-/crm/v3/objects/0-3/batch/archive_archive',
+  'post-/crm/v3/objects/0-3/batch/create_create',
+  'post-/crm/v3/objects/0-3/batch/read_read',
+  'post-/crm/v3/objects/0-3/batch/update_update',
+  'post-/crm/v3/objects/0-3/batch/upsert_upsert',
+  'post-/crm/v3/objects/0-3/merge_merge',
+  'post-/crm/v3/objects/0-3/search_doSearch',
+  'post-/crm/v3/objects/companies_create',
+  'post-/crm/v3/objects/companies/batch/archive_archive',
+  'post-/crm/v3/objects/companies/batch/create_create',
+  'post-/crm/v3/objects/companies/batch/read_read',
+  'post-/crm/v3/objects/companies/batch/update_update',
+  'post-/crm/v3/objects/companies/batch/upsert_upsert',
+  'post-/crm/v3/objects/companies/merge_merge',
+  'post-/crm/v3/objects/companies/search_doSearch',
+  'post-/crm/v3/objects/contacts_create',
+  'post-/crm/v3/objects/contacts/batch/archive_archive',
+  'post-/crm/v3/objects/contacts/batch/create_create',
+  'post-/crm/v3/objects/contacts/batch/read_read',
+  'post-/crm/v3/objects/contacts/batch/update_update',
+  'post-/crm/v3/objects/contacts/batch/upsert_upsert',
+  'post-/crm/v3/objects/contacts/merge_merge',
+  'post-/crm/v3/objects/contacts/search_doSearch',
+  'post-/crm/v3/objects/tickets_create',
+  'post-/crm/v3/objects/tickets/batch/archive_archive',
+  'post-/crm/v3/objects/tickets/batch/create_create',
+  'post-/crm/v3/objects/tickets/batch/read_read',
+  'post-/crm/v3/objects/tickets/batch/update_update',
+  'post-/crm/v3/objects/tickets/batch/upsert_upsert',
+  'post-/crm/v3/objects/tickets/merge_merge',
+  'post-/crm/v3/objects/tickets/search_doSearch',
+  // /crm/v3/owners
+  'get-/crm/v3/owners/{ownerId}_getById',
+  'get-/crm/v3/owners_/crm/v3/owners',
+  // /crm/v3/pipelines
+  'delete-/crm/v3/pipelines/{objectType}/{pipelineId}_archive',
+  'delete-/crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}_archive',
+  'get-/crm/v3/pipelines/{objectType}_getAll',
+  'get-/crm/v3/pipelines/{objectType}/{pipelineId}_getById',
+  'get-/crm/v3/pipelines/{objectType}/{pipelineId}/stages_getAll',
+  'get-/crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}_getById',
+  'patch-/crm/v3/pipelines/{objectType}/{pipelineId}_update',
+  'patch-/crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}_update',
+  'post-/crm/v3/pipelines/{objectType}_create',
+  'post-/crm/v3/pipelines/{objectType}/{pipelineId}/stages_create',
+  'put-/crm/v3/pipelines/{objectType}/{pipelineId}_replace',
+  'put-/crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}_replace',
+  // /crm/v3/properties
+  'delete-/crm/v3/properties/{objectType}/{propertyName}_archive',
+  'delete-/crm/v3/properties/{objectType}/groups/{groupName}_archive',
+  'get-/crm/v3/properties/{objectType}_getAll',
+  'get-/crm/v3/properties/{objectType}/{propertyName}_getByName',
+  'get-/crm/v3/properties/{objectType}/groups_getAll',
+  'get-/crm/v3/properties/{objectType}/groups/{groupName}_getByName',
+  'patch-/crm/v3/properties/{objectType}/{propertyName}_update',
+  'patch-/crm/v3/properties/{objectType}/groups/{groupName}_update',
+  'post-/crm/v3/properties/{objectType}_create',
+  'post-/crm/v3/properties/{objectType}/batch/create_create',
+  'post-/crm/v3/properties/{objectType}/groups_create',
+  // /crm/v4/associations
+  'post-/crm/v4/associations/{fromObjectType}/{toObjectType}/batch/archive_archive',
+  'post-/crm/v4/associations/{fromObjectType}/{toObjectType}/batch/create_create',
+  'post-/crm/v4/associations/{fromObjectType}/{toObjectType}/batch/read_getPage',
+  // /crm/v4/objects
+  'delete-/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}_archive',
+  'get-/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}_getPage',
+  'put-/crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}_createDefault',
+  'put-/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}_create',
+] as const;
+
+/** The operations served by the OAuth install's token endpoints. */
+export const OAUTH_HANDLED = [
+  'get-/oauth/v1/access-tokens/{token}_get',
+  'post-/oauth/v1/token_create',
+] as const;
+
+/** A handler per operation above: the CRM ones answer through `answer` (the pack's request handler as a fetch), the
+ *  OAuth ones through `oauth`. */
+export function hubspotHandlers(answer: (request: Request) => Promise<Response>, oauth: (request: Request) => Promise<Response>): Record<string, DerivedHandler> {
+  const crm: DerivedHandler = ({ request }: DerivedCall) => answer(request);
+  const token: DerivedHandler = ({ request }: DerivedCall) => oauth(request);
+  return { ...Object.fromEntries(CRM_HANDLED.map((id) => [id, crm])), ...Object.fromEntries(OAUTH_HANDLED.map((id) => [id, token])) };
+}

package/src/webhooks.ts

@@ -0,0 +1,80 @@
+// HUBSPOT'S WEBHOOK EVENTS — what HubSpot sends an installed app when a record changes in the account it is installed
+// in (docs/contributing/architecture.md, "Events and webhooks"). An app declares its subscriptions in its project's
+// webhooks component: a `targetUrl` and, in `crmObjects`, the `object.*` events it wants by `subscriptionType`,
+// `objectType` and, for a property change, `propertyName`
+// (https://developers.hubspot.com/docs/apps/developer-platform/add-features/configure-webhooks). Every write the request
+// handler stores (hubspot-twin.ts, whoever made it: an app's API call, a person on a record's page, a form's submission)
+// is announced here, and each live install in the account whose app subscribes to it is sent a POST to its target URL:
+// a JSON array of events, each with `objectId`, `eventId`, `subscriptionId`, `portalId`, `appId`, `occurredAt`,
+// `attemptNumber`, `changeSource`, `subscriptionType`, `objectTypeId`, `sourceId`, and for a property change
+// `propertyName` and `propertyValue` (the generic payload's fields,
+// https://developers.hubspot.com/docs/apps/legacy-apps/public-apps/create-generic-webhook-subscriptions).
+//
+// Signed as HubSpot's request-validation page says: `X-HubSpot-Signature-v3`, the base64 HMAC SHA-256 of the method,
+// the URI, the body and `X-HubSpot-Request-Timestamp` with the app's client secret, and "for backwards compatibility"
+// the older signature, `X-HubSpot-Signature` with `X-HubSpot-Signature-Version: v1`, the SHA-256 of "Client secret +
+// request body" (https://developers.hubspot.com/docs/apps/developer-platform/build-apps/authentication/request-validation).
+//
+// The app's server is outside HubSpot, so what it received is read at a door, `GET /_twin/deliveries?to=<target URL>`,
+// as slack's deliveries are; each delivery is also POSTed to the target URL where the World lets it out.
+//
+// Where the documentation stops and the twin decides: one event per request (HubSpot may batch up to a hundred); the
+// event's `eventId` counts the account's events; `subscriptionId` is the subscription's index in the app, from the app's
+// id; `changeSource` is `CRM_UI` for a person on a page, `FORM` for a form's submission, `INTEGRATION` for an app's API
+// call and `API` otherwise, and `sourceId` is `userId:<id>` or `<appId>`; the v1 signature is sent on every event, which
+// the page does not promise for a developer-platform app's `object.*` event.
+import { createHash, createHmac } from 'node:crypto';
+import { worldEgressRefusal } from '@volter/world-core/network-policy';
+import { appById, installsIn, keep, stored, type Row } from './accounts.ts';
+import { currentPortal } from './portal.ts';
+
+const OBJECT_TYPE_ID: Record<string, string> = { contacts: '0-1', companies: '0-2', deals: '0-3', tickets: '0-5' };
+const SUBSCRIPTION_OBJECT: Record<string, string> = { contacts: 'contact', companies: 'company', deals: 'deal', tickets: 'ticket' };
+
+export type WriteEvent = { objectType: string; objectId: string; kind: 'creation' | 'propertyChange'; propertyName?: string; propertyValue?: string | null };
+
+/** Announce a stored write to every app installed in the request's account that subscribes to it. */
+export async function announceWrite(e: WriteEvent, root: string | undefined, at: string): Promise<void> {
+  const { hub, source, sourceId } = currentPortal();
+  for (const install of installsIn(hub, root)) {
+    const app = appById(Number(install.appId), root);
+    const hooks = app?.webhooks as { targetUrl?: string; subscriptions?: Row[] } | undefined;
+    if (!app || !hooks?.targetUrl) continue;
+    const subscription = (hooks.subscriptions ?? []).find((s) => s.active !== false
+      && s.subscriptionType === `object.${e.kind}` && s.objectType === SUBSCRIPTION_OBJECT[e.objectType]
+      && (e.kind !== 'propertyChange' || s.propertyName === e.propertyName));
+    if (!subscription) continue;
+    const eventId = stored('_webhook_delivery', root).filter((d) => d.portalId === hub).length + 1;
+    const event: Row = {
+      objectId: Number(e.objectId), eventId, subscriptionId: Number(subscription.id), portalId: hub, appId: app.appId,
+      occurredAt: Date.parse(at), attemptNumber: 0, changeSource: source, subscriptionType: `object.${e.kind}`,
+      objectTypeId: OBJECT_TYPE_ID[e.objectType], ...(sourceId ? { sourceId } : {}),
+      ...(e.kind === 'propertyChange' ? { propertyName: e.propertyName, propertyValue: e.propertyValue ?? '' } : {}),
+    };
+    await deliver(String(hooks.targetUrl), String(app.client_secret), [event], hub, root, at);
+  }
+}
+
+async function deliver(to: string, secret: string, events: Row[], hub: number, root: string | undefined, at: string): Promise<void> {
+  const body = JSON.stringify(events);
+  const timestamp = String(Date.parse(at));
+  const headers: Record<string, string> = {
+    'content-type': 'application/json',
+    'x-hubspot-signature': createHash('sha256').update(secret + body).digest('hex'),
+    'x-hubspot-signature-version': 'v1',
+    'x-hubspot-signature-v3': createHmac('sha256', secret).update(`POST${to}${body}${timestamp}`).digest('base64'),
+    'x-hubspot-request-timestamp': timestamp,
+  };
+  const n = stored('_webhook_delivery', root).length + 1;
+  await keep('_webhook_delivery', `delivery:${n}`, { n, to, portalId: hub, body, headers, delivered_at: at }, root, at);
+  if (worldEgressRefusal(to) === null) await fetch(to, { method: 'POST', headers, body }).then((r) => r.text()).catch(() => undefined);
+}
+
+/** GET /_twin/deliveries?to=<url>: what an app's server received from HubSpot, oldest first — each request's headers,
+ *  its body as sent, and the events in it. */
+export function deliveriesDoor(request: Request, root?: string): Response {
+  const to = new URL(request.url).searchParams.get('to') ?? '';
+  const deliveries = stored('_webhook_delivery', root).filter((d) => d.to === to).sort((a, b) => Number(a.n) - Number(b.n))
+    .map((d) => ({ n: d.n, delivered_at: d.delivered_at, headers: d.headers, body: d.body, events: JSON.parse(String(d.body)) as unknown }));
+  return Response.json({ to, deliveries });
+}