@volter/twin-hubspot 0.1.0

package/dist/src/hubspot-mirror-ui.d.ts

@@ -0,0 +1,62 @@
+/** One rendered CRM record, as the vendor's own API returns it (SimplePublicObject). */
+export type HubspotRow = {
+    id: string;
+    properties: Record<string, string | null>;
+    createdAt?: string;
+    updatedAt?: string;
+    archived?: boolean;
+};
+/** The four record sections the mirror shows, keyed by HubSpot's own object-type path segment. */
+export declare const MIRROR_SECTIONS: readonly [{
+    readonly key: "contacts";
+    readonly label: "Contacts";
+    readonly path: "/crm/v3/objects/contacts?limit=100&properties=email,firstname,lastname,phone,lifecyclestage";
+}, {
+    readonly key: "companies";
+    readonly label: "Companies";
+    readonly path: "/crm/v3/objects/companies?limit=100&properties=name,domain,city,industry";
+}, {
+    readonly key: "deals";
+    readonly label: "Deals";
+    readonly path: "/crm/v3/objects/deals?limit=100&properties=dealname,amount,dealstage,pipeline,closedate";
+}, {
+    readonly key: "tickets";
+    readonly label: "Tickets";
+    readonly path: "/crm/v3/objects/tickets?limit=100&properties=subject,content,hs_pipeline_stage,hs_ticket_priority";
+}];
+export type MirrorSectionKey = (typeof MIRROR_SECTIONS)[number]['key'];
+/** The columns each section's table shows — HubSpot property names, in display order. */
+export declare const SECTION_COLUMNS: Record<MirrorSectionKey, {
+    prop: string;
+    label: string;
+}[]>;
+/** The property whose value titles a record in the list — HubSpot's own primary display property. */
+export declare const TITLE_PROPERTY: Record<MirrorSectionKey, string[]>;
+/** The label a row shows for a record — the vendor's primary display properties, joined. */
+export declare function recordTitle(section: MirrorSectionKey, properties: Record<string, string | null> | undefined): string;
+/** Status pill tone for a deal stage. Closed-won reads good, closed-lost bad, anything open warn. */
+export type PillTone = 'ok' | 'warn' | 'bad' | '';
+export declare function stageTone(dealstage: unknown): PillTone;
+/** Format a deal amount the way a CRM list does: `$1,250` / `—` when unset. */
+export declare function formatAmount(amount: unknown): string;
+/** Group deal rows by their `dealstage` property — the pipeline board's own projection. */
+export declare function groupByStage(rows: HubspotRow[]): {
+    stage: string;
+    rows: HubspotRow[];
+}[];
+/** Build the React/TSX CRM client to browser JS (Bun bundles TSX); cached at module scope, so a
+ *  pack running on its own does exactly ONE build. */
+export declare function buildHubspotMirrorClient(): Promise<string>;
+/** Serve the HubSpot CRM mirror UI (React app) + its backing CRM REST API. */
+export declare function createHubspotMirrorServer(options: {
+    root?: string;
+    port?: number;
+}): Promise<{
+    port: number;
+    url: string;
+    stop: () => void;
+}>;
+/** The app-shell HTML (pure, for tests). The CRM itself is the React client. */
+export declare function hubspotMirrorHtml(): string;
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export declare function hubspotMirrorStyles(): Promise<string>;

package/dist/src/hubspot-mirror-ui.js

@@ -0,0 +1,152 @@
+// HubSpot MIRROR UI — a HubSpot-CRM-like view served as a React/TSX app (bundled by Bun).
+//
+// WHY THIS PACK MIRRORS AT ALL (docs/contributing/adding-a-twin.md, "Does this vendor get a mirror?"): the
+// question is not "does HubSpot have a UI" but "when someone does this vendor's core job, do
+// they open a browser or write code?" A sales rep works a deal by DRAGGING IT ACROSS THE
+// PIPELINE BOARD and a support agent works a ticket in the ticket view — the CRM screen IS the
+// product, the way a board is Jira's product. So: mirror.
+//
+// ARCHETYPE A (API passthrough), the recipe's default and the strongest parity claim available:
+// non-asset requests fall through to the pack's OWN fetch adapter, and the browser client fetches
+// HubSpot's REAL API paths (`/crm/v3/objects/contacts`, …). There is exactly ONE code path, so
+// API↔UI parity cannot drift — it is not "kept in sync", it is structurally the same read.
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the pack's
+// fetch adapter as its API backend and reads every byte of state back over the wire.
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createHubspotTwinFetch } from "./hubspot-server.js";
+const CLIENT_ENTRY = () => new URL('../client/hubspot-mirror.tsx', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => new URL('../client/hubspot-mirror.css', import.meta.url).pathname; // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+/** The four record sections the mirror shows, keyed by HubSpot's own object-type path segment. */
+export const MIRROR_SECTIONS = [
+    { key: 'contacts', label: 'Contacts', path: '/crm/v3/objects/contacts?limit=100&properties=email,firstname,lastname,phone,lifecyclestage' },
+    { key: 'companies', label: 'Companies', path: '/crm/v3/objects/companies?limit=100&properties=name,domain,city,industry' },
+    { key: 'deals', label: 'Deals', path: '/crm/v3/objects/deals?limit=100&properties=dealname,amount,dealstage,pipeline,closedate' },
+    { key: 'tickets', label: 'Tickets', path: '/crm/v3/objects/tickets?limit=100&properties=subject,content,hs_pipeline_stage,hs_ticket_priority' },
+];
+/** The columns each section's table shows — HubSpot property names, in display order. */
+export const SECTION_COLUMNS = {
+    contacts: [
+        { prop: 'firstname', label: 'First name' }, { prop: 'lastname', label: 'Last name' },
+        { prop: 'email', label: 'Email' }, { prop: 'phone', label: 'Phone' }, { prop: 'lifecyclestage', label: 'Lifecycle stage' },
+    ],
+    companies: [
+        { prop: 'name', label: 'Name' }, { prop: 'domain', label: 'Domain' },
+        { prop: 'city', label: 'City' }, { prop: 'industry', label: 'Industry' },
+    ],
+    deals: [
+        { prop: 'dealname', label: 'Deal name' }, { prop: 'amount', label: 'Amount' },
+        { prop: 'dealstage', label: 'Stage' }, { prop: 'closedate', label: 'Close date' },
+    ],
+    tickets: [
+        { prop: 'subject', label: 'Ticket name' }, { prop: 'hs_ticket_priority', label: 'Priority' },
+        { prop: 'hs_pipeline_stage', label: 'Status' },
+    ],
+};
+/** The property whose value titles a record in the list — HubSpot's own primary display property. */
+export const TITLE_PROPERTY = {
+    contacts: ['firstname', 'lastname', 'email'],
+    companies: ['name', 'domain'],
+    deals: ['dealname'],
+    tickets: ['subject'],
+};
+/** The label a row shows for a record — the vendor's primary display properties, joined. */
+export function recordTitle(section, properties) {
+    const props = properties ?? {};
+    const parts = TITLE_PROPERTY[section].map((p) => props[p]).filter((v) => typeof v === 'string' && v !== '');
+    return parts.length ? parts.join(' ') : '(no name)';
+}
+export function stageTone(dealstage) {
+    const s = String(dealstage ?? '').toLowerCase();
+    if (s === '')
+        return '';
+    if (s === 'closedwon')
+        return 'ok';
+    if (s === 'closedlost')
+        return 'bad';
+    return 'warn';
+}
+/** Format a deal amount the way a CRM list does: `$1,250` / `—` when unset. */
+export function formatAmount(amount) {
+    const n = Number(amount);
+    if (amount === null || amount === undefined || amount === '' || !Number.isFinite(n))
+        return '—';
+    return `$${n.toLocaleString('en-US', { maximumFractionDigits: 2 })}`;
+}
+/** Group deal rows by their `dealstage` property — the pipeline board's own projection. */
+export function groupByStage(rows) {
+    const buckets = new Map();
+    for (const r of rows) {
+        const stage = String(r.properties?.dealstage ?? '') || 'unstaged';
+        const list = buckets.get(stage);
+        if (list)
+            list.push(r);
+        else
+            buckets.set(stage, [r]);
+    }
+    return [...buckets.entries()].sort((a, b) => a[0].localeCompare(b[0])).map(([stage, list]) => ({ stage, rows: list }));
+}
+const APP_SHELL = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<base href="/"><title>HubSpot CRM mirror (twin)</title><link rel="stylesheet" href="assets/styles.css"></head>
+<body><div id="root"></div><script type="module" src="assets/app.js"></script></body></html>`;
+let clientBundle = null;
+/** Build the React/TSX CRM client to browser JS (Bun bundles TSX); cached at module scope, so a
+ *  pack running on its own does exactly ONE build. */
+export function buildHubspotMirrorClient() {
+    if (!clientBundle) {
+        clientBundle = bundleClient(CLIENT_ENTRY())
+            .catch((error) => { clientBundle = null; throw error; });
+    }
+    return clientBundle;
+}
+/** Serve the HubSpot CRM mirror UI (React app) + its backing CRM REST API. */
+export async function createHubspotMirrorServer(options) {
+    const twin = createHubspotTwinFetch(options);
+    const server = await serveHttp({
+        // LOOPBACK-SPECIFIC bind: with the default wildcard hostname, `port: 0` can be handed a port
+        // some long-running app already LISTENS on at 127.0.0.1 (SO_REUSEADDR allows the overlapping
+        // non-identical bind), and the more specific loopback listener then shadows this server for
+        // every 127.0.0.1 fetch — the verify would talk to a STRANGER. Binding 127.0.0.1 makes the
+        // kernel allocate a port that is actually free on loopback.
+        hostname: '127.0.0.1',
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        async fetch(request) {
+            const url = new URL(request.url);
+            if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+                try {
+                    return new Response(await buildHubspotMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } });
+                }
+                catch (error) {
+                    return new Response(String(error), { status: 500 });
+                }
+            }
+            if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+                return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+            }
+            if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+                return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+            }
+            // Everything else → the twin's OWN FETCH ADAPTER (composition, R2/R3): the React client
+            // fetches HubSpot's real endpoints, and the adapter is the same closure
+            // `createHubspotTwinServer` serves, so there is exactly ONE serving code path — the world
+            // instant on every write (the kernel dedupes an action by content + millisecond, so a
+            // pinned stamp would swallow an A→B→A revert as `replayed`), the rate-limit response
+            // headers, an honorable `readOnly` and contained handler throws all come from it, and the
+            // mirror port cannot drift from the API port.
+            return twin(request);
+        },
+    });
+    const port = server.port ?? options.port ?? 0;
+    return { port, url: `http://127.0.0.1:${port}`, stop: () => server.stop(true) };
+}
+/** The app-shell HTML (pure, for tests). The CRM itself is the React client. */
+export function hubspotMirrorHtml() {
+    return APP_SHELL;
+}
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function hubspotMirrorStyles() {
+    return readFile(CLIENT_CSS(), 'utf8');
+}

package/dist/src/hubspot-oauth.d.ts

@@ -0,0 +1,8 @@
+import { TWIN_HUB_ID, type PortalScope } from './portal.js';
+export { TWIN_HUB_ID };
+/** The account a CRM request's bearer acts in: an access token the install issued (refused once expired, its app
+ *  uninstalled or its account closed), a static app's token, or, for a credential the twin never issued, undefined (the
+ *  World's own account). Where the documentation stops: HubSpot's refusal words for a revoked token are the twin's. */
+export declare function tokenPortal(authorization: string | null, root: string | undefined, at: string): PortalScope | Response | undefined;
+/** app.hubspot.com's consent and api.hubapi.com's OAuth v1 endpoints, or undefined for any other request. */
+export declare function hubspotOAuth(request: Request, root: string | undefined, now: () => string): Promise<Response | undefined>;

package/dist/src/hubspot-oauth.js

@@ -0,0 +1,291 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// HUBSPOT OAUTH — the install an app's "Connect HubSpot" starts (docs/contributing/architecture.md, "Screens": a hosted
+// flow). From HubSpot's OAuth guide (developers.hubspot.com/docs/api/oauth-quickstart-guide):
+//   - the app sends a person to https://app.hubspot.com/oauth/authorize with `client_id`, `scope` (space-separated),
+//     `redirect_uri`, and optionally `optional_scope` and `state`; its consent shows "the name of your app and a short
+//     description of the HubSpot API services it's requesting permission to access", and on approval HubSpot redirects
+//     to the redirect_uri "with a `code` query parameter";
+//   - the app exchanges the code at POST https://api.hubapi.com/oauth/v1/token with `grant_type=authorization_code`,
+//     client_id, client_secret, redirect_uri and code, and later refreshes with `grant_type=refresh_token`;
+//   - both answer `token_type`, `refresh_token`, `hub_id`, `scopes`, `access_token` and `expires_in` (1800) (HubSpot's
+//     changelog, "Additional details returned when generating OAuth access tokens");
+//   - GET /oauth/v1/access-tokens/{token} answers the token's metadata (token, user, hub_domain, scopes, hub_id,
+//     app_id, expires_in, user_id, token_type "access"), and a bad refresh token is `invalid_grant` with status
+//     BAD_REFRESH_TOKEN (the v1 OAuth tokens guide).
+// The consent is authored from @volter/world-ui's piece under HubSpot's skin; nothing of HubSpot's page is copied.
+//
+// AN APP AN ACCOUNT BUILT (screens/developer.tsx) is installed as HubSpot's install page describes
+// (https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot, "Install an OAuth
+// marketplace app"): the person is signed in (screens/session.tsx), the redirect URL is one the app registered, an
+// OAuth marketplace app installs outside test accounts only once its AUP is signed and at most 25 times before it is
+// listed, the person selects the account to install it in, reviews the scopes and clicks **Connect app**, and for an
+// app HubSpot has not verified confirms in a dialog ("type **I accept the risk**, and click **Connect**"). The code is
+// the account's; its exchange checks the app's client secret, installs the app in the account (the page's
+// "TOKEN_EXCHANGE: … At this point, the app is installed in the user's account"), and answers the account's `hub_id`;
+// every token it issues acts in that account (portal.ts) until it expires, the install is uninstalled or the account
+// is closed (tokenPortal).
+//
+// Where the documentation stops and the twin decides, for an app no account of the World built: the portal is the
+// World's own (hub 2953265, user twin@hubspot.local), so a World pointing an app at the twin with a client_id of its own
+// keeps working: any redirect_uri may start an install and the client_secret is not checked; the consent lists each scope by its name (the twin has no table of HubSpot's scope
+// descriptions); a code is redeemed once, within ten minutes, by the app it was issued to at the redirect it
+// named, and a bad code is `invalid_grant` with status BAD_AUTH_CODE; each refresh mints a new refresh token and the
+// earlier ones stay valid; another grant type, and the metadata of an unknown or expired token (401 in the API's error
+// envelope), are worded by the twin; a denial redirects with `error=access_denied` (RFC 6749 §4.1.2.1); the consent is
+// served only on HubSpot's app hosts (*.hubspot.com), the token endpoints on the API host; the rest of the API accepts
+// any bearer, as it did before (hubspot-server.ts), so a minted token is not required there.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import { Consent, CONSENT_CSS, flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import { accountOf, appByClientId, installOf, keep, signedIn, stored } from "./accounts.js";
+import { TWIN_HUB_ID } from "./portal.js";
+export { TWIN_HUB_ID };
+const SERVICE = 'hubspot';
+const TWIN_USER = { id: 1, email: 'twin@hubspot.local', domain: 'twin.hubspot.local' };
+const CODE_TTL_MS = 10 * 60_000;
+const EXPIRES_IN = 1800;
+const INSTALL_CAP = 25;
+const ACCEPT_RISK = 'I accept the risk';
+const SKIN = `
+body { background: #ffffff; color: #33475b; font-family: "Lexend Deca", Helvetica, Arial, sans-serif; }
+.consent-badge { background: #f5f8fa; border: 1px solid #cbd6e2; color: #33475b; }
+.consent-vendor { background: #ff7a59; }
+.consent-link, .consent-box, .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; }
+.consent-allow, .portal-primary { background: #ff7a59; border-color: #ff7a59; color: #ffffff; }
+.portal-side { background: #f5f8fa; border-right: 1px solid #cbd6e2; }
+.portal-notice { background: #fef8f0; border: 1px solid #f5c26b; }
+`;
+const hex = (s) => createHash('sha256').update(s).digest('hex');
+const rows = (type, root) => projectResources(SERVICE, root).filter((r) => r.type === type);
+async function write(type, id, fields, root, at, actor = TWIN_USER.email) {
+    await applyTwinWrite(SERVICE, { operation: `oauth.${type}`, subjectType: type, subjectId: id, fields, occurredAt: at, actor: { kind: 'human', id: actor } }, root);
+}
+async function fieldsOf(request) {
+    const out = Object.fromEntries(new URL(request.url).searchParams);
+    if (request.method !== 'POST')
+        return out;
+    const text = await request.text();
+    if ((request.headers.get('content-type') ?? '').includes('json')) {
+        try {
+            for (const [k, v] of Object.entries(JSON.parse(text)))
+                if (v != null)
+                    out[k] = String(v);
+            return out;
+        }
+        catch { /* read as a form */ }
+    }
+    return { ...out, ...Object.fromEntries(new URLSearchParams(text)) };
+}
+const scopesOf = (raw) => [...new Set((raw ?? '').split(/[\s,+]+/).filter(Boolean))];
+const parses = (u) => { try {
+    return !!u && !!new URL(u);
+}
+catch {
+    return false;
+} };
+const errorPage = (status, message) => flowPage({ title: 'HubSpot', status, css: [CONSENT_CSS, SKIN], body: _jsx("main", { className: "consent", children: _jsx("h1", { className: "consent-heading", children: message }) }) });
+function redirect(to, params) {
+    const url = new URL(to);
+    for (const [k, v] of Object.entries(params))
+        if (v !== undefined)
+            url.searchParams.set(k, v);
+    return new Response(null, { status: 302, headers: { location: url.toString() } });
+}
+const tokenError = (status, message) => Response.json({ error: 'invalid_grant', error_description: message, status, message }, { status: 400 });
+/** The fields the consent carries from the install URL to its answer. */
+function carried(p) {
+    return { client_id: p.client_id, redirect_uri: p.redirect_uri, scope: scopesOf(p.scope).join(' '), ...(p.optional_scope ? { optional_scope: p.optional_scope } : {}), ...(p.state !== undefined ? { state: p.state } : {}) };
+}
+// ── an app no account of the World built: the World's own portal ────────────────────────────
+async function consent(request) {
+    const p = await fieldsOf(request);
+    if (!p.client_id)
+        return errorPage(400, 'Missing client_id');
+    if (!parses(p.redirect_uri))
+        return errorPage(400, 'Missing or invalid redirect_uri');
+    const scopes = [...scopesOf(p.scope), ...scopesOf(p.optional_scope)];
+    if (!scopes.length)
+        return errorPage(400, 'Missing scope');
+    return flowPage({
+        title: `Connect ${p.client_id} to HubSpot | HubSpot`,
+        css: [CONSENT_CSS, SKIN],
+        body: (_jsx(Consent, { heading: `Connect ${p.client_id} to your HubSpot account`, app: { name: p.client_id }, request: `${TWIN_USER.domain} · Hub ID ${TWIN_HUB_ID}`, permissions: scopes.map((s) => ({ title: s, detail: 'Requested scope' })), action: "/oauth/authorize", fields: carried(p), deny: { name: 'answer', value: 'cancel', label: 'Cancel' }, allow: { name: 'answer', value: 'allow', label: 'Connect app' }, note: `You will be sent to ${new URL(p.redirect_uri).origin}` })),
+    });
+}
+async function answer(request, root, at) {
+    const p = await fieldsOf(request);
+    if (!p.client_id || !parses(p.redirect_uri))
+        return errorPage(400, 'Missing client_id or redirect_uri');
+    if (p.answer !== 'allow')
+        return redirect(p.redirect_uri, { error: 'access_denied', state: p.state });
+    const scopes = [...scopesOf(p.scope), ...scopesOf(p.optional_scope)];
+    const code = await mintCode(p.client_id, p.redirect_uri, scopes, { hubId: TWIN_HUB_ID }, root, at);
+    return redirect(p.redirect_uri, { code, state: p.state });
+}
+async function mintCode(clientId, redirectUri, scopes, extra, root, at, actor) {
+    const n = rows('oauth_code', root).length + 1;
+    const code = `na1-${hex(`hubspotcode:${clientId}:${at}:${n}`).slice(0, 32)}`;
+    await write('oauth_code', code, { code, client_id: clientId, redirect_uri: redirectUri, scopes, created_at: at, used: false, ...extra }, root, at, actor);
+    return code;
+}
+// ── an app an account of the World built ───────────────────────────────────────────────────
+/** Why the app cannot be installed from this URL, or undefined. */
+function refusalFor(app, p, root) {
+    if (!app.redirectUrls.includes(p.redirect_uri ?? ''))
+        return 'The redirect URL is not one this app allows.';
+    const scopes = scopesOf(p.scope);
+    const missing = app.requiredScopes.filter((s) => !scopes.includes(s));
+    if (missing.length)
+        return `The install URL is missing required scopes: ${missing.join(', ')}.`;
+    if (app.distribution === 'marketplace' && !app.aup_signed_at)
+        return 'This app can only be installed in developer test accounts.';
+    if (app.distribution === 'marketplace' && stored('_install', root).filter((i) => i.appId === app.appId && !i.uninstalled_at).length >= INSTALL_CAP)
+        return 'This app has reached its install limit.';
+    return undefined;
+}
+function appConsent(app, person, p, root) {
+    const account = accountOf(Number(person.hubId), root);
+    return flowPage({
+        title: `Connect ${String(app.name)} | HubSpot`,
+        css: [CONSENT_CSS, SKIN],
+        body: (_jsx(Consent, { heading: `Connect ${String(app.name)} to HubSpot`, app: { name: String(app.name) }, request: `${String(person.email)} · This app has not been verified by HubSpot`, permissions: ['oauth', ...app.requiredScopes].filter((s, i, all) => all.indexOf(s) === i).map((s) => ({ title: s, detail: 'Required' })), action: "/oauth/authorize", fields: carried(p), choices: [{ id: 'account', label: 'Select an account', value: String(account.hubId), options: [{ value: String(account.hubId), label: `${String(account.name)} (${String(account.hubId)})` }] }], deny: { name: 'answer', value: 'cancel', label: 'Cancel' }, allow: { name: 'answer', value: 'allow', label: 'Connect app' }, note: `You will be sent to ${new URL(p.redirect_uri).origin}` })),
+    });
+}
+/** The dialog an unverified app's install asks a person to confirm in. */
+function acceptRisk(app, p, notice) {
+    const fields = { ...carried(p), account: p.account ?? '', answer: 'allow' };
+    return flowPage({
+        title: `Connect ${String(app.name)} | HubSpot`,
+        css: [PORTAL_CSS, SKIN],
+        body: (_jsx(Portal, { merchant: `Connect ${String(app.name)}`, notice: notice ?? 'This app has not been verified by HubSpot. Double-check all details of the app to confirm that it matches what you expect.', sections: [{ heading: 'App details', items: [{ title: String(app.name), detail: String(app.description ?? ''), note: `Requests: ${['oauth', ...app.requiredScopes].join(', ')}` }] }], forms: [{ heading: 'Connect unverified app', action: '/oauth/authorize', fields: [
+                        ...Object.entries(fields).map(([id, value]) => ({ id, label: '', type: 'hidden', value })),
+                        { id: 'confirm', label: `Type ${ACCEPT_RISK}` },
+                    ], submit: { label: 'Connect' } }] })),
+    });
+}
+async function appAnswer(app, request, p, root, at) {
+    if (p.answer !== 'allow')
+        return redirect(p.redirect_uri, { error: 'access_denied', state: p.state });
+    const person = signedIn(request, root);
+    if (!person)
+        return errorPage(401, 'Log in to HubSpot to connect this app.');
+    const hubId = Number(p.account);
+    if (hubId !== Number(person.hubId) || accountOf(hubId, root)?.closed_at)
+        return errorPage(403, "You don't have access to this account.");
+    if (p.confirm === undefined)
+        return acceptRisk(app, p);
+    if (p.confirm !== ACCEPT_RISK)
+        return acceptRisk(app, p, `Type ${ACCEPT_RISK} to connect this app.`);
+    const code = await mintCode(String(app.client_id), p.redirect_uri, ['oauth', ...app.requiredScopes].filter((s, i, all) => all.indexOf(s) === i), { hubId, appId: app.appId, person: person.email }, root, at, String(person.email));
+    return redirect(p.redirect_uri, { code, state: p.state });
+}
+async function authorize(request, root, at) {
+    const p = await fieldsOf(request);
+    const app = p.client_id ? appByClientId(p.client_id, root) : undefined;
+    if (!app)
+        return request.method === 'GET' ? consent(new Request(request.url)) : answer(new Request(request.url, { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams(p).toString() }), root, at);
+    if (!parses(p.redirect_uri))
+        return errorPage(400, 'Missing or invalid redirect_uri');
+    const refused = refusalFor(app, p, root);
+    if (refused)
+        return errorPage(400, refused);
+    if (request.method === 'POST')
+        return appAnswer(app, request, p, root, at);
+    const person = signedIn(request, root);
+    const url = new URL(request.url);
+    if (!person)
+        return new Response(null, { status: 302, headers: { location: `/login?loginRedirectUrl=${encodeURIComponent(url.pathname + url.search)}` } });
+    return appConsent(app, person, p, root);
+}
+// ── the token endpoints ────────────────────────────────────────────────────────────────────
+async function issue(clientId, scopes, seed, extra, root, at) {
+    const access = `CN${hex(`hubspotaccess:${seed}`).slice(0, 48)}`;
+    const refresh = `na1-${hex(`hubspotrefresh:${seed}`).slice(0, 8)}-${hex(`hubspotrefresh2:${seed}`).slice(0, 28)}`;
+    const hubId = Number(extra.hubId ?? TWIN_HUB_ID);
+    await write('oauth_token', access, { access_token: access, refresh_token: refresh, client_id: clientId, scopes, issued_at: at, ...extra }, root, at);
+    return Response.json({ token_type: 'bearer', refresh_token: refresh, hub_id: hubId, scopes, access_token: access, expires_in: EXPIRES_IN });
+}
+async function token(request, root, at) {
+    const p = await fieldsOf(request);
+    const app = p.client_id ? appByClientId(p.client_id, root) : undefined;
+    // a built app's client secret is checked; where the documentation stops, HubSpot's words for a wrong one are the twin's
+    if (app && p.client_secret !== app.client_secret)
+        return Response.json({ error: 'invalid_client', error_description: 'client_id or client_secret is invalid', status: 'BAD_CLIENT_ID', message: 'client_id or client_secret is invalid' }, { status: 400 });
+    if (p.grant_type === 'authorization_code') {
+        const code = rows('oauth_code', root).find((r) => r.code === p.code);
+        if (!code || code.used === true || code.client_id !== p.client_id || code.redirect_uri !== p.redirect_uri || Date.parse(at) - Date.parse(String(code.created_at)) > CODE_TTL_MS) {
+            return tokenError('BAD_AUTH_CODE', 'auth code is invalid, expired or already used');
+        }
+        await write('oauth_code', String(code.code), { used: true }, root, at);
+        const extra = { hubId: code.hubId ?? TWIN_HUB_ID, ...(app ? { appId: app.appId } : {}) };
+        if (app) {
+            const hubId = Number(code.hubId);
+            const live = installOf(Number(app.appId), hubId, root);
+            if (!live)
+                await keep('_install', `install:${String(app.appId)}:${hubId}:${at}`, { appId: app.appId, hubId, installed_by: code.person, scopes: code.scopes, installed_at: at, uninstalled_at: null }, root, at, String(code.person));
+        }
+        return issue(String(p.client_id), code.scopes ?? [], `${code.code}`, extra, root, at);
+    }
+    if (p.grant_type === 'refresh_token') {
+        const held = rows('oauth_token', root).filter((r) => r.refresh_token === p.refresh_token && r.client_id === p.client_id);
+        const first = held[0];
+        if (!first || (app && !installOf(Number(app.appId), Number(first.hubId), root)))
+            return tokenError('BAD_REFRESH_TOKEN', 'refresh token is invalid, expired or revoked');
+        return issue(String(p.client_id), first.scopes ?? [], `${p.refresh_token}:${at}:${held.length}`, { hubId: first.hubId ?? TWIN_HUB_ID, ...(app ? { appId: app.appId } : {}) }, root, at);
+    }
+    return Response.json({ error: 'unsupported_grant_type', error_description: 'grant_type must be authorization_code or refresh_token', status: 'BAD_GRANT_TYPE', message: 'grant_type must be authorization_code or refresh_token' }, { status: 400 });
+}
+function tokenInfo(access, root, at) {
+    const t = rows('oauth_token', root).find((r) => r.access_token === access);
+    const expiresIn = t ? EXPIRES_IN - Math.floor((Date.parse(at) - Date.parse(String(t.issued_at))) / 1000) : -1;
+    if (!t || expiresIn <= 0)
+        return Response.json({ status: 'error', message: 'The OAuth token used to make this call expired', category: 'EXPIRED_AUTHENTICATION' }, { status: 401 });
+    const hubId = Number(t.hubId ?? TWIN_HUB_ID);
+    return Response.json({ token: access, user: TWIN_USER.email, hub_domain: TWIN_USER.domain, scopes: t.scopes, hub_id: hubId, app_id: t.appId ?? Number.parseInt(hex(String(t.client_id)).slice(0, 6), 16), expires_in: expiresIn, user_id: TWIN_USER.id, token_type: 'access' });
+}
+/** The account a CRM request's bearer acts in: an access token the install issued (refused once expired, its app
+ *  uninstalled or its account closed), a static app's token, or, for a credential the twin never issued, undefined (the
+ *  World's own account). Where the documentation stops: HubSpot's refusal words for a revoked token are the twin's. */
+export function tokenPortal(authorization, root, at) {
+    const bearer = /^Bearer\s+(.+)$/i.exec(authorization ?? '')?.[1]?.trim();
+    if (!bearer)
+        return undefined;
+    const refuse = (category, message) => Response.json({ status: 'error', message, correlationId: hex(`${category}:${bearer}:${at}`).replace(/^(.{8})(.{4})(.{4})(.{4})(.{12}).*$/, '$1-$2-$3-$4-$5'), category }, { status: 401 });
+    const staticInstall = stored('_install', root).find((i) => i.static_token === bearer);
+    if (staticInstall) {
+        if (staticInstall.uninstalled_at || accountOf(Number(staticInstall.hubId), root)?.closed_at)
+            return refuse('INVALID_AUTHENTICATION', 'Authentication credentials not found. This API supports OAuth 2.0 authentication.');
+        return { hub: Number(staticInstall.hubId), source: 'INTEGRATION', sourceId: String(staticInstall.appId) };
+    }
+    const t = rows('oauth_token', root).find((r) => r.access_token === bearer);
+    if (!t || t.appId === undefined)
+        return undefined;
+    const hubId = Number(t.hubId);
+    const ago = Math.floor((Date.parse(at) - Date.parse(String(t.issued_at))) / 1000) - EXPIRES_IN;
+    if (ago >= 0)
+        return refuse('EXPIRED_AUTHENTICATION', `The OAuth token used to make this call expired ${ago} second(s) ago.`);
+    if (!installOf(Number(t.appId), hubId, root) || accountOf(hubId, root)?.closed_at)
+        return refuse('INVALID_AUTHENTICATION', 'Authentication credentials not found. This API supports OAuth 2.0 authentication.');
+    return { hub: hubId, source: 'INTEGRATION', sourceId: String(t.appId) };
+}
+/** app.hubspot.com's consent and api.hubapi.com's OAuth v1 endpoints, or undefined for any other request. */
+export async function hubspotOAuth(request, root, now) {
+    const url = new URL(request.url);
+    const path = url.pathname.replace(/\/+$/, '');
+    // the vendor host a redirected request names (the injector, a hosted World), else its Host, else the URL's
+    const host = (request.headers.get('x-volter-twin-original-host') ?? request.headers.get('host') ?? url.host).split(':')[0].toLowerCase();
+    const appHost = host === 'hubspot.com' || host.endsWith('.hubspot.com') || url.hostname.endsWith('.hubspot.com');
+    if (path === '/oauth/authorize' && appHost) {
+        if (request.method === 'GET' || request.method === 'POST')
+            return authorize(request, root, now());
+        return undefined;
+    }
+    if (path === '/oauth/v1/token' && request.method === 'POST')
+        return token(request, root, now());
+    const info = /^\/oauth\/v1\/access-tokens\/([^/]+)$/.exec(path);
+    if (info && request.method === 'GET')
+        return tokenInfo(decodeURIComponent(info[1]), root, now());
+    return undefined;
+}

package/dist/src/hubspot-server.d.ts

@@ -0,0 +1,24 @@
+import { type DerivedFetch } from '@volter/world-core';
+/** Options every HubSpot-twin HTTP surface needs, independent of who owns the socket. */
+export interface HubspotTwinFetchOptions {
+    root?: string;
+    readOnly?: boolean;
+}
+/**
+ * The pack's wire: the twin's discovery door (`GET /twin`) and HubSpot's OAuth consent (app.hubspot.com's
+ * /oauth/authorize, a hosted flow: hubspot-oauth.tsx) in front, then the derived dispatch over the nine documents'
+ * union. A /crm/v3/objects/ path naming its object type in the spelling the spec's paths do not use (`deals` for the
+ * Deals document's `0-3`, `0-1` for `contacts`) is dispatched as the spelling they use (`specObjectPath`). The
+ * operations the twin serves go to their handlers (semantics/crm.ts); every other one, and a path no document has,
+ * is the gap.
+ */
+export declare function createHubspotTwinFetch(options: HubspotTwinFetchOptions): DerivedFetch;
+export declare function createHubspotTwinServer(options: {
+    root?: string;
+    port?: number;
+    readOnly?: boolean;
+}): Promise<{
+    port: number;
+    url: string;
+    stop: () => void;
+}>;