@volter/twin-hubspot 0.1.0

package/dist/src/screens/developer.js

@@ -0,0 +1,191 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// 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 } from "../accounts.js";
+import { CSS, formOf, page, personFor, portalPage, redirect, who } from "./page.js";
+import { Consent } from '@volter/world-ui';
+const uuid = (seed) => { 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;
+/** The door standing in for `hs project upload`. */
+export async function uploadDoor(hubId, request, root, at) {
+    let body = {};
+    try {
+        body = JSON.parse(await request.text());
+    }
+    catch { /* refused below */ }
+    const refuse = (message) => 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;
+    const c = app?.config;
+    const auth = c?.auth;
+    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;
+    const settings = (hooks?.config?.settings ?? {});
+    const crmObjects = ((hooks?.config?.subscriptions ?? {}).crmObjects ?? []);
+    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 = {
+        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) => `/developer-projects/${String(a.hubId)}/project/${encodeURIComponent(String(a.project))}/component/${encodeURIComponent(String(a.uid))}`;
+function authPage(a, account, person) {
+    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.map((u) => ({ title: u })), empty: 'None.' },
+            { heading: 'Scopes', items: [...a.requiredScopes.map((s) => ({ title: s, detail: 'Required' })), ...a.optionalScopes.map((s) => ({ title: s, detail: 'Optional' }))] },
+        ],
+    });
+}
+function installUrl(a) {
+    const q = new URLSearchParams({ client_id: String(a.client_id), redirect_uri: a.redirectUrls[0] ?? '', scope: ['oauth', ...a.requiredScopes].join(' ') });
+    return `https://app.hubspot.com/oauth/authorize?${q.toString()}`;
+}
+function distributionPage(a, account, person, root, opts = {}) {
+    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' }] }
+                            : { 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' }] }] },
+            ...(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', 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, root, at) {
+    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, _jsx("main", { className: "portal-main", children: _jsx("h1", { children: "Only a super admin can manage this account's apps." }) }), 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, _jsx("main", { className: "portal-main", children: _jsx("h1", { children: "This project doesn't exist." }) }), 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, (_jsx(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.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/dist/src/screens/forms.d.ts

@@ -0,0 +1,5 @@
+export declare const FORMS_HOST = "api.hsforms.com";
+/** app.hubspot.com/forms/…, or undefined for another path. */
+export declare function formPages(request: Request, root: string | undefined, at: string): Promise<Response | undefined>;
+/** api.hsforms.com's submission, or undefined for another request. */
+export declare function formSubmission(request: Request, root: string | undefined, at: string): Promise<Response | undefined>;

package/dist/src/screens/forms.js

@@ -0,0 +1,126 @@
+// 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 } from "../accounts.js";
+import { handleHubspotTwinRequest } from "../hubspot-twin.js";
+import { inPortal } from "../portal.js";
+import { formOf, personFor, portalPage, redirect, who } from "./page.js";
+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, root) => stored('_form', root).filter((f) => f.hubId === hub && !f.archived);
+const uuid = (seed) => { 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, root, at) {
+    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.results ?? []).filter((p) => p.formField === true && p.archived !== true);
+    let notice;
+    if (request.method === 'POST') {
+        const wanted = (await formOf(request)).property;
+        const property = usable.find((p) => p.name === wanted);
+        const fields = form.fields;
+        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.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, account, person, root, notice, status = 200) {
+    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' }] })) }],
+        forms: [{ heading: 'Create form', action: `/forms/${hub}`, submit: { label: 'Create form' }, fields: [{ id: 'name', label: 'Form name' }] }] }, status);
+}
+const submitError = (errorType, message) => 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, root, at) {
+    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 = {};
+    try {
+        body = JSON.parse(await request.text());
+    }
+    catch {
+        return submitError('INVALID_METADATA', 'The request body is not valid JSON.');
+    }
+    const fields = Array.isArray(body.fields) ? body.fields : [];
+    const names = new Set(form.fields.map((f) => String(f.name)));
+    const properties = {};
+    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.results ?? [])[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/dist/src/screens/page.d.ts

@@ -0,0 +1,21 @@
+import type { ReactElement } from 'react';
+import { type PortalProps } from '@volter/world-ui';
+import { type Row } from '../accounts.js';
+export declare const SKIN = "\nbody { background: #ffffff; color: #33475b; font-family: \"Lexend Deca\", Helvetica, Arial, sans-serif; }\n.sign-in-mark, .consent-vendor { background: #ff7a59; }\n.sign-in-box, .consent-box { background: #ffffff; border-color: #cbd6e2; }\n.sign-in-error { background: #fdedee; border-color: #f2545b; }\n.sign-in-submit, .consent-allow, .portal-primary { background: #ff7a59; border-color: #ff7a59; color: #ffffff; }\n.consent-badge { background: #f5f8fa; border: 1px solid #cbd6e2; color: #33475b; }\n.consent-link, .consent-actions { border-color: #cbd6e2; }\n.consent-who small, .consent-permission summary small, .consent-note { color: #516f90; }\n.consent-deny { background: #ffffff; border-color: #cbd6e2; color: #33475b; }\n.portal-side { background: #f5f8fa; border-right: 1px solid #cbd6e2; }\n.portal-section h2 { border-color: #cbd6e2; color: #516f90; }\n.portal-notice { background: #e5f5f8; border: 1px solid #7fd1de; word-break: break-all; }\n.portal-button { background: #ffffff; border-color: #cbd6e2; color: #33475b; }\n.portal-danger { color: #d94c53; }\n";
+export declare const CSS: {
+    signIn: string[];
+    consent: string[];
+    portal: string[];
+};
+/** A settings or record page: the account and person on the left, the page's sections and forms. */
+export declare function portalPage(title: string, props: PortalProps, status?: number): Response;
+export declare function page(title: string, css: string[], body: ReactElement, status?: number): Response;
+export declare function redirect(location: string): Response;
+export declare function formOf(request: Request): Promise<Record<string, string>>;
+/** 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 declare function personFor(request: Request, hubId: number | undefined, root?: string): {
+    person: Row;
+    account: Row;
+} | Response;
+/** The left column every account page carries. */
+export declare const who: (account: Row, person: Row) => string;

package/dist/src/screens/page.js

@@ -0,0 +1,49 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { CONSENT_CSS, flowPage, Portal, PORTAL_CSS, SIGN_IN_CSS } from '@volter/world-ui';
+import { accountOf, signedIn } from "../accounts.js";
+// 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, props, status = 200) {
+    return flowPage({ title: `${title} | HubSpot`, css: CSS.portal, status, body: _jsx(Portal, { ...props }) });
+}
+export function page(title, css, body, status = 200) {
+    return flowPage({ title: `${title} | HubSpot`, css, status, body });
+}
+export function redirect(location) {
+    return new Response(null, { status: 302, headers: { location } });
+}
+export async function formOf(request) {
+    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, hubId, root) {
+    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, _jsx("main", { className: "portal-main", children: _jsx("h1", { children: "You don't have access to this account." }) }), 403);
+    if (account.closed_at)
+        return page('HubSpot', CSS.portal, _jsx("main", { className: "portal-main", children: _jsx("h1", { children: "This account has been closed." }) }), 403);
+    return { person, account };
+}
+/** The left column every account page carries. */
+export const who = (account, person) => `${String(account.name)} · ${String(person.email)}`;

package/dist/src/screens/session.d.ts

@@ -0,0 +1 @@
+export declare function signIn(request: Request, root: string | undefined, at: string): Promise<Response>;

package/dist/src/screens/session.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// 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.js";
+import { CSS, formOf, page } from "./page.js";
+/** A return address on app.hubspot.com, never another site. */
+const back = (raw) => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : '/');
+function signInPage(to, email, error) {
+    return page('Log in', CSS.signIn, (_jsx(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, root, at) {
+    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/dist/src/semantics/crm.d.ts

@@ -0,0 +1,8 @@
+import type { DerivedHandler } from '@volter/world-core';
+/** The operations served by the pack's request handler, every CRM operation the twin serves. */
+export declare const CRM_HANDLED: readonly ["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", "get-/crm/v3/owners/{ownerId}_getById", "get-/crm/v3/owners_/crm/v3/owners", "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", "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", "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", "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"];
+/** The operations served by the OAuth install's token endpoints. */
+export declare const OAUTH_HANDLED: readonly ["get-/oauth/v1/access-tokens/{token}_get", "post-/oauth/v1/token_create"];
+/** 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 declare function hubspotHandlers(answer: (request: Request) => Promise<Response>, oauth: (request: Request) => Promise<Response>): Record<string, DerivedHandler>;

package/dist/src/semantics/crm.js

@@ -0,0 +1,101 @@
+/** 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',
+];
+/** 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',
+];
+/** 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, oauth) {
+    const crm = ({ request }) => answer(request);
+    const token = ({ request }) => oauth(request);
+    return { ...Object.fromEntries(CRM_HANDLED.map((id) => [id, crm])), ...Object.fromEntries(OAUTH_HANDLED.map((id) => [id, token])) };
+}

package/dist/src/webhooks.d.ts

@@ -0,0 +1,12 @@
+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 declare function announceWrite(e: WriteEvent, root: string | undefined, at: string): Promise<void>;
+/** 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 declare function deliveriesDoor(request: Request, root?: string): Response;