@volter/twin-hubspot 0.1.0

package/src/index.ts

@@ -0,0 +1,152 @@
+// @volter/twin-hubspot — the HubSpot CRM twin (one vendor, one package), built on the shared
+// @volter/world-core kernel. REST transport over HubSpot's real v3/v4 CRM paths, the vendor's own
+// `{ results, paging: { next: { after } } }` collection envelope and
+// `{ status:'error', message, correlationId, category }` error envelope, stateful CRM records
+// (contacts / companies / deals / tickets) with properties, associations, pipelines and owners.
+// The CRM API accepts any bearer; the OAuth install (consent and token endpoints) mints the tokens an app is given.
+// Served as a derived pack (Protocol 3, src/manifest.ts). Conformance tooling lives in
+// @volter/world-tooling (a dev dependency) — not shipped in the runtime API.
+export {
+  handleHubspotTwinRequest,
+  correlationIdFor,
+  resolveObjectType,
+  HUBSPOT_RATE_LIMIT_HEADERS,
+  LIST_LIMIT_MAX,
+  OBJECT_TYPES,
+  RESOURCE_TYPES,
+  SEARCH_FILTER_OPERATORS,
+  SEARCH_LIMIT_MAX,
+  SEARCH_MAX_FILTERS_PER_GROUP,
+  SEARCH_MAX_FILTERS_TOTAL,
+  SEARCH_MAX_FILTER_GROUPS,
+  SEARCH_RESULT_CAP,
+} from './hubspot-twin.ts';
+export type { HubspotRequest, HubspotResponse, ObjectType } from './hubspot-twin.ts';
+export { createHubspotTwinFetch, createHubspotTwinServer, type HubspotTwinFetchOptions } from './hubspot-server.ts';
+export {
+  hubspotRequestForAction,
+  liveHubspotExecute,
+  mapCrmObject,
+  mapOwner,
+  pollTimestamp,
+  pullHubspotAll,
+  pullHubspotObjects,
+  pullHubspotOwners,
+  pushPendingHubspotActions,
+  syncHubspotFromReal,
+} from './hubspot-connector.ts';
+export type { HubspotErrorBody, HubspotExecute, LiveHubspotOptions } from './hubspot-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveHubspotExecute` routes every live
+// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
+// here is HubSpot's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
+// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
+// `HubspotBudgetError` by type; there is deliberately no export that disables the guard.
+export {
+  HUBSPOT_BUDGET_CEILING,
+  HUBSPOT_BUDGET_MAX_RETRY_AFTER_S,
+  HUBSPOT_BUDGET_WINDOW_MS,
+  HUBSPOT_CALL_WEIGHTS,
+  HUBSPOT_RATE_BUDGET,
+  HubspotBudget,
+  HubspotBudgetError,
+  hubspotBudgetPath,
+  hubspotCallWeight,
+} from './hubspot-budget.ts';
+export type { HubspotBudgetErrorKind, HubspotBudgetOptions, HubspotBudgetReservation, HubspotBudgetSnapshot } from './hubspot-budget.ts';
+export {
+  MIRROR_SECTIONS,
+  SECTION_COLUMNS,
+  TITLE_PROPERTY,
+  buildHubspotMirrorClient,
+  createHubspotMirrorServer,
+  formatAmount,
+  groupByStage,
+  hubspotMirrorHtml,
+  recordTitle,
+  stageTone,
+} from './hubspot-mirror-ui.ts';
+export type { HubspotRow, MirrorSectionKey, PillTone } from './hubspot-mirror-ui.ts';
+
+// Registry descriptor: the pack self-describes so tooling can discover it.
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { performHubspotAction, syncHubspotFromRemote } from './hubspot-connector.ts';
+import { HUBSPOT_RATE_BUDGET as RATE_BUDGET } from './hubspot-budget.ts';
+export const pack: TwinPack = {
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of
+  // the real state system. Moved 2026-09-08.
+  protocol: '2',
+  // HubSpot publishes webhooks for CRM object changes, which is what actually moves; the refresh
+  // walks every object type and is the backstop.
+  refresh: { every: '15m', webhook: true, onDemand: { atMost: '30s' } },
+  stateSystem: { perform: performHubspotAction, refresh: syncHubspotFromRemote },
+  // The round trip is a CONTACT create — HubSpot's own write, and the portal mints a fresh record
+  // id for every one, so a second send on a branch is a second contact rather than a collision.
+  roundTrip: { method: 'POST', path: '/crm/v3/objects/contacts', body: { properties: { email: 'round@trip.test', firstname: 'Round', lastname: 'Trip' } }, headers: { authorization: 'Bearer twin' } },
+  parityOrigin: 'http://twin',
+
+  vendor: 'hubspot',
+  // The SAME object hubspot-budget.ts declares at module load — one source of truth, so
+  // registering the pack and importing the connector can never arm two different ceilings.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-hubspot',
+  // R2 adopted-as-debt, legibly: declared types no replay can create, each with its reason.
+  resourcesUnreachable: {
+    'owner': "a portal user provisioned in HubSpot's admin, never through the CRM API",
+  },
+  resources: ['crm_object', 'property', 'property_group', 'pipeline', 'association', 'owner'],
+  specSource:
+    "nine documents of HubSpot's public spec catalog (api.hubspot.com/public/api/spec/v1/specs): Contacts, Companies, "
+    + 'Deals, Tickets, Crm Owners, Properties and Pipelines v3, Associations v4 and OAuth v1, vendored under spec/openapi/ '
+    + '(provenance in spec/SOURCE.md) and read as their union; the calls dubinc/dub makes (apps/web/lib/integrations/hubspot/).',
+  description: 'HubSpot CRM twin — v3/v4 objects, properties, associations, pipelines and owners, with the vendor error envelope, paging.next.after and a CRM mirror.',
+  // A browser-side HubSpot call goes to api.hubapi.com/crm/… — the dev proxy forwards '/crm/'
+  // to the twin and strips the absolute host so calls come back same-origin.
+  browserRouting: { apiPathPrefix: '/crm/', loaderHost: 'https://api.hubapi.com' },
+
+  // ADOPTION — how an app repo betrays that it talks to HubSpot.
+  //  • `@hubspot/api-client` is the ONE official npm client of the surface modeled here.
+  //  • The `@hubspot/` scope is NOT claimed wholesale: it also carries the CMS/CLI toolchain
+  //    (`@hubspot/cli`, `@hubspot/local-dev-lib`, the `@hubspot/cms-components` family), which
+  //    are build tooling for a product area this twin explicitly does not model. Claiming the
+  //    scope would report a CMS-theme repo as covered by a CRM twin — the exact lie `covers`
+  //    exists to prevent (the `googleapis` precedent in covers.ts).
+  //  • `HUBSPOT` is the credential stem: HUBSPOT_ACCESS_TOKEN / HUBSPOT_API_KEY /
+  //    HUBSPOT_CLIENT_ID / HUBSPOT_CLIENT_SECRET all normalize to it under covers.ts's
+  //    ENV_SUFFIX rules (framework prefix stripped, suffix matched, remainder lowercased with
+  //    punctuation removed). `HUBSPOT_PRIVATE_APP_TOKEN` — the name HubSpot's own private-app
+  //    docs use — stems to `hubspotprivateapp` instead, because `_TOKEN` is the matched suffix,
+  //    so it is claimed explicitly rather than assumed.
+  adoption: {
+    // HubSpot's official Python client, the counterpart of `@hubspot/api-client`.
+    pypi: ['hubspot-api-client'],
+    sdks: ['@hubspot/api-client'],
+    envStems: ['HUBSPOT', 'HUBSPOTPRIVATEAPP'],
+  },
+
+  // INTERCEPTION — api.hubapi.com is the SDK's only API server: every generated
+  // `servers.ts` in @hubspot/api-client 14.0.1 declares exactly
+  // `new ServerConfiguration("https://api.hubapi.com", {})`, and a sweep of the whole published
+  // tarball finds no other API host. `app.hubspot.com` appears once, in
+  // `OauthDiscovery.getAuthorizationUrl`: the URL a person is sent to for consent, which the twin serves
+  // (hubspot-oauth.tsx).
+  // app.hubspot.com carries every page the twin builds (sign-in, consent, apps, records, forms, settings) and
+  // api.hsforms.com a form's submission (src/screens/).
+  hosts: [{ host: 'api.hubapi.com' }, { host: 'app.hubspot.com' }, { host: 'api.hsforms.com' }],
+
+  // WORLD WIRING — `endpointEnvNone`, and this is a ruling, not an omission. The SDK IS
+  // base-URL-configurable, but through a CONSTRUCTOR OPTION (`IConfiguration.basePath`, read by
+  // `ApiClientConfigurator.getBaseServer`), never an environment variable: nothing in
+  // @hubspot/api-client 14.0.1 reads `process.env`, and HubSpot documents no `HUBSPOT_BASE_URL`.
+  // Inventing one would make `covers` report a world covered while the app, reading no such var,
+  // still talked to the real portal. Interception is the `hosts` entry above.
+  endpointEnvNone:
+    'the @hubspot/api-client SDK takes its base URL from the `basePath` CONSTRUCTOR option '
+    + '(IConfiguration.basePath → ApiClientConfigurator.getBaseServer), not from any environment '
+    + 'variable — it reads no process.env at all, and HubSpot documents no base-URL env var. '
+    + 'Interception is the api.hubapi.com host entry; inventing a HUBSPOT_BASE_URL the app does '
+    + 'not read would report a world covered while its traffic still left the machine.',
+};
+
+registerPack(pack);

package/src/manifest.ts

@@ -0,0 +1,96 @@
+// HubSpot's manifest: the vendor facts its published documents do not carry (docs/contributing/architecture.md,
+// "Protocol 3"). The surface is generated (./generated/surface.gen.json, from ../spec by scripts/derive-pack.ts): the
+// union of nine documents from HubSpot's public spec catalog (the eight CRM documents the pack serves and OAuth v1,
+// ../spec/SOURCE.md), their one OAuth scheme's scope lists made one (../spec/patches.json). The documents name every
+// operation, so an operation's id is HubSpot's own (`post-/crm/v3/properties/{objectType}/batch/create_create`).
+//
+// THE HANDLERS. Every operation the twin serves is a semantics handler (semantics/crm.ts) over the pack's request
+// handler (hubspot-twin.ts), whose store is the vendor's behaviour, or over the OAuth install's token endpoints
+// (hubspot-oauth.tsx). The derived core owns no operation, so no resource is declared here and no state candidate is
+// ruled: the spec's resources (a record, a property, a pipeline and its stages, an owner) are stored by the request
+// handler in its own shape. An operation no handler serves answers the gap (hubspot-server.ts).
+//
+// WHY NO `auth`. HubSpot reads `Authorization: Bearer <access token or static app token>`. A token the twin issued (an
+// install's access token, a static app's token) acts in its account (portal.ts) and is refused once expired, its app
+// uninstalled or its account closed (hubspot-oauth.tsx, tokenPortal); any other bearer acts in the World's own account,
+// as it did before accounts were modelled, and the kernel's `auth` names keys the twin refuses, never the ones it
+// accepts. Where the twin stops: no operation is refused for a scope its token lacks.
+//
+// THE ERROR BODY. `{status: "error", message, correlationId, category}`, HubSpot's documented error envelope
+// (https://developers.hubspot.com/docs/api-reference/error-handling), which the request handler answers with a
+// correlationId derived from the request (so a replay is byte-identical). The template below is the core's, which
+// serves nothing.
+//
+// THE STATE. The request handler's kernel subjects: `crm_object` (a record, keyed `<objectType>_<id>`), `property`,
+// `property_group`, `pipeline` (its stages inside), `owner` (pulled or the seeded portal owner) and `association`;
+// the OAuth install's `oauth_code` and `oauth_token`.
+import type { DerivedManifest } from '@volter/world-core';
+
+export const manifest: DerivedManifest = {
+  vendor: 'hubspot',
+  service: 'hubspot',
+  body: {},
+  // the core mints no id (it owns no operation); a record's id is the request handler's
+  ids: { template: '{prefix}_{n}' },
+  time: 'iso',
+  error: { status: 'error', message: '{message}', category: '{code}' },
+  readOnly: { status: 405, message: 'this twin was started read-only; omit readOnly to accept writes', code: 'TWIN_READ_ONLY' },
+  malformedBody: { status: 400, message: 'Invalid input JSON', code: 'VALIDATION_ERROR' },
+  notFound: { status: 404, message: 'resource not found', code: 'OBJECT_NOT_FOUND' },
+  // `{results, paging: {next: {after}}}`, paged by `after` and `limit` (10 by default, 100 at most: the documents'
+  // getPage operations). Required by the type; the core lists nothing.
+  list: { style: 'envelope', envelope: { results: '{data}' }, limit: { param: 'limit', default: 10, max: 100 }, after: 'after' },
+  deleted: {},
+  // HubSpot's pages the life walks (src/screens/, src/hubspot-oauth.tsx), each built from @volter/world-ui's pieces.
+  screens: [
+    {
+      id: 'sign-in', kind: 'flow', host: 'app.hubspot.com', path: '/login',
+      demand: 'every person on a HubSpot page is who signed in there', status: 'done', controls: ['Email address', 'Password', 'Log in'],
+      source: 'https://knowledge.hubspot.com/account-management/log-in-to-hubspot',
+    },
+    {
+      id: 'oauth-consent', kind: 'flow', host: 'app.hubspot.com', path: '/oauth/authorize',
+      demand: "Dub's HubSpot integration sends a workspace owner here to connect a portal (apps/web/lib/integrations/hubspot/oauth.ts, authUrl)",
+      status: 'done', controls: ['Select an account', 'Connect app', 'Cancel', 'Type I accept the risk', 'Connect'],
+      source: 'https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot',
+    },
+    {
+      id: 'app-auth', kind: 'workspace', host: 'app.hubspot.com', path: '/developer-projects/:hubId/project/:name/component/:uid/auth',
+      demand: "an app's client ID and secret are read here", status: 'done',
+      source: 'https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot',
+    },
+    {
+      id: 'app-distribution', kind: 'workspace', host: 'app.hubspot.com', path: '/developer-projects/:hubId/project/:name/component/:uid/distribution',
+      demand: 'an OAuth marketplace app is published (Begin publishing, the AUP) before any install; a static app is installed and its token shown here',
+      status: 'done', controls: ['Begin publishing', 'Sign', 'Install now', 'Show'],
+      source: 'https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot',
+    },
+    {
+      id: 'records', kind: 'workspace', host: 'app.hubspot.com', path: '/contacts/:hubId/record/:objectTypeId/:id',
+      demand: "reps create deals on a contact's record and move a deal's stage; account managers add companies", status: 'done',
+      controls: ['Create deal', 'Deal stage', 'Save', 'Create company'], source: 'https://knowledge.hubspot.com/records/create-records-on-the-updated-index-page',
+    },
+    {
+      id: 'pipelines', kind: 'workspace', host: 'app.hubspot.com', path: '/settings/:hubId/objects/deals/pipelines',
+      demand: "a custom pipeline's closed-won stage ID is read here (Dub's guide: \"enter the stage ID corresponding to your custom Closed Won stage\")",
+      status: 'done', source: 'https://knowledge.hubspot.com/object-settings/set-up-and-customize-pipelines',
+    },
+    {
+      id: 'forms', kind: 'workspace', host: 'app.hubspot.com', path: '/forms/:hubId',
+      demand: "Dub's guide: \"In the HubSpot form builder, add a hidden field and map it to the Dub Id contact property\"", status: 'done',
+      controls: ['Create form', 'Add hidden field'], source: 'https://dub.co/docs/integrations/hubspot',
+    },
+    {
+      id: 'connected-apps', kind: 'workspace', host: 'app.hubspot.com', path: '/connected-apps/:hubId/installed',
+      demand: 'a client uninstalls the app it connected', status: 'done', controls: ['Uninstall', 'Type uninstall'],
+      source: 'https://knowledge.hubspot.com/marketplace/install-apps-in-the-hubspot-marketplace',
+    },
+    {
+      id: 'account-and-billing', kind: 'workspace', host: 'app.hubspot.com', path: '/account-and-billing/:hubId/subscriptions',
+      demand: "a company leaving HubSpot cancels its subscription's auto-renewal, then deletes the account once the subscription has ended",
+      status: 'done', controls: ['Cancel auto-renewal', 'Next', 'Delete account', 'Enter your Hub ID to confirm', 'Yes, delete'],
+      source: 'https://knowledge.hubspot.com/account/how-do-i-cancel-my-hubspot-account',
+    },
+  ],
+  resources: {},
+};

package/src/portal.ts

@@ -0,0 +1,40 @@
+// THE PORTAL A REQUEST ACTS IN — HubSpot keeps each account's CRM apart: a record, a property, a pipeline and an owner
+// belong to one account ("portal", its Hub ID), a token acts in the account its app was installed in (the token
+// exchange answers that account's `hub_id`), and a webhook event names the account where it occurred in its `portalId`
+// (https://developers.hubspot.com/docs/apps/legacy-apps/public-apps/create-generic-webhook-subscriptions).
+//
+// The request handler (hubspot-twin.ts) reads and writes through `inPortal`'s scope: a subject of an account other than
+// the World's own is stored under the account's id and read only in its scope. A request whose credential the twin
+// never issued acts in the World's own account, `TWIN_HUB_ID`, as every request did before accounts were modelled, so a
+// World pointing an app at the twin with a token of its own keeps working.
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/** The World's own account: every request whose credential names no account the twin made acts here. */
+export const TWIN_HUB_ID = 2953265;
+
+/** Who is acting, in which account, for a write's webhook events: `changeSource` and `sourceId` as HubSpot names
+ *  them in an event ("The source of the change", "The user or source of the triggered webhook event"). */
+export type PortalScope = { hub: number; source: string; sourceId?: string };
+
+const scope = new AsyncLocalStorage<PortalScope>();
+
+/** Run `fn` acting in `hub`. */
+export function inPortal<T>(s: PortalScope, fn: () => T): T {
+  return scope.run(s, fn);
+}
+
+/** The scope the current request acts in; the World's own account, through the API, when none was opened. */
+export function currentPortal(): PortalScope {
+  return scope.getStore() ?? { hub: TWIN_HUB_ID, source: 'API' };
+}
+
+/** A subject's kernel id in an account: the World's own account keeps the ids it always had. */
+export function scopedId(hub: number, id: string): string {
+  return hub === TWIN_HUB_ID ? id : `p${hub}~${id}`;
+}
+
+/** A stored subject's id as its account sees it, and the account it belongs to. */
+export function unscoped(id: string): { hub: number; id: string } {
+  const m = /^p(\d+)~(.*)$/.exec(id);
+  return m ? { hub: Number(m[1]), id: m[2]! } : { hub: TWIN_HUB_ID, id };
+}

package/src/screens/account.tsx

@@ -0,0 +1,129 @@
+// AN ACCOUNT'S OWN SETTINGS — its home, the apps connected to it (where a super admin uninstalls one), and its account
+// and billing pages (where a super admin cancels a subscription's auto-renewal, and deletes the account).
+//
+// - app.hubspot.com/ : the signed-in person's account, with the pages the twin serves for it.
+// - app.hubspot.com/connected-apps/:hubId/installed : the apps installed in the account. "Click Actions on the app you
+//   want to disconnect, then click Uninstall. In the dialog box, type "uninstall" in the text field and click Uninstall"
+//   (https://knowledge.hubspot.com/marketplace/install-apps-in-the-hubspot-marketplace, Uninstall an app). An
+//   uninstalled app's tokens stop working and it is sent no more webhook events (oauth: tokenPortal; webhooks.ts).
+// - app.hubspot.com/account-and-billing/:hubId/subscriptions : the account's subscription and its auto-renewal terms;
+//   **Cancel auto-renewal**, choosing the products and a cancellation reason, then reviewing and confirming. "Mid-contract
+//   cancellations are not permitted": the subscription ends on its renewal date, when "your account will be downgraded to
+//   HubSpot's free tools" (accounts.ts, subscriptionAt).
+// - app.hubspot.com/account-and-billing/:hubId/delete-account : the Delete Account tab. "Click Delete account. You'll be
+//   prompted to enter your Hub ID to confirm the deletion. Click Yes, delete"; "You cannot delete your account if any
+//   HubSpot subscriptions still have active commitments"
+//   (https://knowledge.hubspot.com/account/how-do-i-cancel-my-hubspot-account). A deleted account's pages, tokens and
+//   forms stop answering.
+//
+// Where the documentation stops and the twin decides: the pages' paths and layout; only a super admin may uninstall an
+// app, cancel auto-renewal or delete the account (the page also admits billing admins, whom the twin does not model); a
+// cancelled subscription ends at 00:00 UTC on its renewal date; the cancellation reasons offered; HubSpot's words for a
+// refused deletion.
+import { appById, installsIn, keep, subscriptionAt, type Row } from '../accounts.ts';
+import { formOf, personFor, portalPage, who } from './page.tsx';
+
+export async function accountPages(request: Request, root: string | undefined, at: string): Promise<Response | undefined> {
+  const path = new URL(request.url).pathname.replace(/\/+$/, '') || '/';
+  if (path === '/' && request.method === 'GET') {
+    const got = personFor(request, undefined, root);
+    if (got instanceof Response) return got;
+    const hub = Number(got.person.hubId);
+    const links: Array<[string, string]> = [['Contacts', `/contacts/${hub}/objects/0-1/views/all/list`], ['Companies', `/contacts/${hub}/objects/0-2/views/all/list`],
+      ['Forms', `/forms/${hub}`], ['Deal pipelines', `/settings/${hub}/objects/deals/pipelines`], ['Connected apps', `/connected-apps/${hub}/installed`], ['Account & billing', `/account-and-billing/${hub}/subscriptions`]];
+    return portalPage('Home', { merchant: who(got.account, got.person), sections: [{ heading: `${String(got.account.name)} · Hub ID ${hub}`, items: links.map(([title, href]) => ({ title, actions: [{ label: 'Open', action: href, method: 'get' as const }] })) }] });
+  }
+  const m = /^\/(connected-apps|account-and-billing)\/(\d+)(?:\/(installed|installed\/uninstall|subscriptions|subscriptions\/cancel-auto-renewal|delete-account|delete-account\/delete|delete-account\/confirm))?$/.exec(path);
+  if (!m) return undefined;
+  const hub = Number(m[2]);
+  const got = personFor(request, hub, root);
+  if (got instanceof Response) return got;
+  const { person, account } = got;
+  const actor = String(person.email);
+  const admin = person.superAdmin === true;
+  if (m[1] === 'connected-apps') {
+    let notice: string | undefined;
+    if (m[3] === 'installed/uninstall' && request.method === 'POST') {
+      const f = await formOf(request);
+      const appId = Number(f.appId);
+      const install = installsIn(hub, root).find((i) => i.appId === appId);
+      const name = String(appById(appId, root)?.name ?? appId);
+      if (!admin) notice = 'Only a super admin can uninstall apps.';
+      else if (!install) notice = 'This app is not installed.';
+      else if (f.confirm !== 'uninstall') {
+        return portalPage(`Uninstall ${name}`, { merchant: who(account, person), notice: `Uninstall ${name}? Its access to this account ends.`, sections: [],
+          forms: [{ heading: `Uninstall ${name}`, action: `/connected-apps/${hub}/installed/uninstall`, submit: { label: 'Uninstall' },
+            fields: [{ id: 'appId', label: '', type: 'hidden', value: String(appId) }, { id: 'confirm', label: 'Type uninstall' }] }] }, f.confirm === undefined ? 200 : 422);
+      } else {
+        await keep('_install', String(install.id), { ...ownOf(install), uninstalled_at: at, uninstalled_by: actor }, root, at, actor);
+        notice = `${name} was uninstalled.`;
+      }
+    } else if (m[3] !== 'installed' || request.method !== 'GET') return undefined;
+    return portalPage('Connected apps', { merchant: who(account, person), ...(notice ? { notice } : {}), sections: [{ heading: 'Connected apps', empty: 'No apps are connected to this account.',
+      items: installsIn(hub, root).map((i) => ({ title: String(appById(Number(i.appId), root)?.name ?? i.appId), note: `Installed ${String(i.installed_at).slice(0, 10)} by ${String(i.installed_by ?? '')}`,
+        actions: [{ label: 'Uninstall', action: `/connected-apps/${hub}/installed/uninstall`, tone: 'danger' as const, fields: { appId: String(i.appId) } }] })) }] });
+  }
+  const billing = `/account-and-billing/${hub}`;
+  const tab = m[3];
+  if (tab === undefined) return request.method === 'GET' ? subscriptionsPage(hub, account, person, at) : undefined;
+  if (tab === 'subscriptions' && request.method === 'GET') return subscriptionsPage(hub, account, person, at);
+  if (tab === 'subscriptions/cancel-auto-renewal' && request.method === 'POST') {
+    const f = await formOf(request);
+    const paid = subscriptionAt(account, at);
+    if (!admin) return subscriptionsPage(hub, account, person, at, 'Only a super admin can cancel auto-renewal.', 403);
+    if (paid === 'free' || account.auto_renew === false) return subscriptionsPage(hub, account, person, at, 'No subscription renews automatically.', 422);
+    if (f.product !== paid || !f.reason) {
+      return portalPage('Cancel auto-renewal', { merchant: who(account, person), ...(f.product !== undefined ? { notice: 'Select the products to cancel and a cancellation reason.' } : {}),
+        sections: [{ heading: 'Features you lose', items: [{ title: paid, detail: `Your account will be downgraded to HubSpot's free tools on ${String(account.renews_on)}.` }] }],
+        forms: [{ heading: 'Cancel auto-renewal', action: `${billing}/subscriptions/cancel-auto-renewal`, submit: { label: 'Next' }, fields: [
+          { id: 'product', label: 'Products to cancel', options: [{ value: paid, label: paid }] },
+          { id: 'reason', label: 'Cancellation reason', options: REASONS.map((r) => ({ value: r, label: r })) },
+        ] }] }, f.product === undefined ? 200 : 422);
+    }
+    if (f.confirm !== 'yes') {
+      return portalPage('Cancel auto-renewal', { merchant: who(account, person), notice: `${paid} will be canceled on ${String(account.renews_on)}, the end of its commitment term. Reason: ${f.reason}.`, sections: [],
+        forms: [{ heading: 'Review the cancellation', action: `${billing}/subscriptions/cancel-auto-renewal`, submit: { label: 'Cancel auto-renewal' }, fields: [
+          { id: 'product', label: '', type: 'hidden', value: paid }, { id: 'reason', label: '', type: 'hidden', value: f.reason }, { id: 'confirm', label: '', type: 'hidden', value: 'yes' },
+        ] }] });
+    }
+    await keep('_account', String(account.id), { ...ownOf(account), auto_renew: false, cancellation_reason: f.reason, auto_renew_cancelled_at: at, auto_renew_cancelled_by: actor }, root, at, actor);
+    return subscriptionsPage(hub, { ...account, auto_renew: false }, person, at, `Auto-renewal canceled. ${paid} ends on ${String(account.renews_on)}; a notice of non-renewal was sent to the billing admin.`);
+  }
+  if (tab === 'delete-account' && request.method === 'GET') return deletePage(hub, account, person);
+  if ((tab === 'delete-account/delete' || tab === 'delete-account/confirm') && request.method === 'POST') {
+    const paid = subscriptionAt(account, at);
+    if (!admin) return deletePage(hub, account, person, 'Only a super admin can delete this account.', 403);
+    if (paid !== 'free') return deletePage(hub, account, person, `You cannot delete your account while ${paid} still has an active commitment (it renews on ${String(account.renews_on)}).`, 422);
+    const typed = ((await formOf(request)).hubId ?? '').trim();
+    if (tab === 'delete-account/delete' || typed !== String(hub)) {
+      return portalPage('Delete account', { merchant: who(account, person), ...(tab === 'delete-account/confirm' ? { notice: 'Enter this account\'s Hub ID to confirm.' } : {}), sections: [],
+        forms: [{ heading: `Delete ${String(account.name)}?`, action: `${billing}/delete-account/confirm`, submit: { label: 'Yes, delete' }, fields: [{ id: 'hubId', label: 'Enter your Hub ID to confirm' }] }] }, tab === 'delete-account/confirm' ? 422 : 200);
+    }
+    await keep('_account', String(account.id), { ...ownOf(account), closed_at: at, closed_by: actor }, root, at, actor);
+    return portalPage('Account deleted', { merchant: String(account.name), notice: `${String(account.name)} (Hub ID ${hub}) has been deleted.`, sections: [] });
+  }
+  return undefined;
+}
+
+const REASONS = ['Business is closing or merging', 'Moving to another product', 'Too expensive', 'Not using it enough', 'Other'];
+
+function subscriptionsPage(hub: number, account: Row, person: Row, at: string, notice?: string, status = 200): Response {
+  const now = subscriptionAt(account, at);
+  const billing = `/account-and-billing/${hub}`;
+  return portalPage('Account & billing', { merchant: who(account, person), back: { href: `${billing}/delete-account`, label: 'Delete Account' }, ...(notice ? { notice } : {}),
+    sections: [{ heading: 'Subscriptions', items: [{ title: now === 'free' ? "HubSpot's free tools" : now, detail: `Hub ID ${hub}`,
+      ...(now !== 'free' ? { note: account.auto_renew === false ? `Canceled: ends on ${String(account.renews_on)}` : `Renews automatically on ${String(account.renews_on)}` } : {}),
+      ...(now !== 'free' && account.auto_renew !== false ? { actions: [{ label: 'Cancel auto-renewal', action: `${billing}/subscriptions/cancel-auto-renewal` }] } : {}) }] }] }, status);
+}
+
+function deletePage(hub: number, account: Row, person: Row, notice?: string, status = 200): Response {
+  return portalPage('Delete Account', { merchant: who(account, person), back: { href: `/account-and-billing/${hub}/subscriptions`, label: 'Subscriptions' }, ...(notice ? { notice } : {}),
+    sections: [{ heading: 'Delete Account', items: [{ title: String(account.name), detail: `Hub ID ${hub}`, note: 'Deleting the account permanently removes it and its data.',
+      actions: [{ label: 'Delete account', action: `/account-and-billing/${hub}/delete-account/delete`, tone: 'danger' as const }] }] }] }, status);
+}
+
+/** A stored row's own fields, without the kernel's. */
+function ownOf(r: Row): Row {
+  const { id: _id, type: _type, updatedAt: _u, deleted: _d, ...rest } = r;
+  return rest;
+}

package/src/screens/crm.tsx

@@ -0,0 +1,154 @@
+// THE CRM PAGES PEOPLE WORK IN — an account's contacts, a contact's record (where a rep creates a deal for the contact),
+// a deal's record (where a rep moves its stage), its companies (where an account manager adds one), and its deal
+// pipelines' settings (where a stage's internal ID is read). HubSpot's record pages live at
+// app.hubspot.com/contacts/:hubId/record/:objectTypeId/:id; the twin builds only the acts the life takes on them, from
+// @volter/world-ui's portal piece under HubSpot's skin. Every act is the request handler's own operation, in the
+// account, as the signed-in user (portal.ts: `CRM_UI`, `userId:<id>`), so its webhook events are the API's.
+//
+// Where the documentation stops and the twin decides: the pages' layout and paths other than a record's; a deal made
+// on a contact's record is associated with it (HubSpot's default deal-to-contact association, type 3) and owned by the
+// rep who made it; the pipelines settings page is at /settings/:hubId/objects/deals/pipelines and shows each stage's
+// internal ID beside its label; a pipeline made there takes its stages in order, separated by commas, and names its closed won and closed
+// lost stages.
+import { handleHubspotTwinRequest } from '../hubspot-twin.ts';
+import { inPortal } from '../portal.ts';
+import type { Row } from '../accounts.ts';
+import { formOf, personFor, portalPage, redirect, who } from './page.tsx';
+
+type Call = (method: string, path: string, body?: unknown) => Promise<{ status: number; body: Row }>;
+
+function caller(hub: number, person: Row, root: string | undefined, at: string): Call {
+  return async (method, path, body) => {
+    const res = await inPortal({ hub, source: 'CRM_UI', sourceId: `userId:${String(person.userId)}` }, () =>
+      handleHubspotTwinRequest({ method, path, ...(body !== undefined ? { body: JSON.stringify(body) } : {}), root, occurredAt: at }));
+    return { status: res.status, body: (res.body ?? {}) as Row };
+  };
+}
+
+const CONTACT_PROPS = ['email', 'firstname', 'lastname', 'lifecyclestage', 'dub_id', 'dub_link', 'dub_partner_email'];
+const nameOf = (p: Row): string => [p.firstname, p.lastname].filter(Boolean).join(' ') || String(p.email ?? '');
+
+async function stageOptions(call: Call): Promise<Array<{ value: string; label: string }>> {
+  const pipelines = ((await call('GET', '/crm/v3/pipelines/deals')).body.results ?? []) as Row[];
+  return pipelines.flatMap((p) => ((p.stages ?? []) as Row[]).map((s) => ({ value: `${String(p.id)}/${String(s.id)}`, label: `${String(p.label)} · ${String(s.label)}` })));
+}
+
+/** app.hubspot.com/contacts/… and /settings/…/pipelines, or undefined for another path. */
+export async function crmPages(request: Request, root: string | undefined, at: string): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const path = url.pathname.replace(/\/+$/, '');
+  const m = /^\/(contacts|settings)\/(\d+)\/(.*)$/.exec(path);
+  if (!m) return undefined;
+  const hub = Number(m[2]);
+  const rest = m[3]!;
+  const got = personFor(request, hub, root);
+  if (got instanceof Response) return got;
+  const { person, account } = got;
+  const call = caller(hub, person, root, at);
+  const side = who(account, person);
+  const R = `/contacts/${hub}`;
+
+  if (m[1] === 'settings') {
+    if (rest !== 'objects/deals/pipelines') return undefined;
+    if (request.method === 'POST') {
+      const f = await formOf(request);
+      const labels = (f.stages ?? '').split(/\r?\n|,/).map((s) => s.trim()).filter(Boolean);
+      const stages = labels.map((label, i) => ({ label, displayOrder: i, metadata: label === f.won ? { isClosed: 'true', probability: '1.0' } : label === f.lost ? { isClosed: 'true', probability: '0.0' } : { isClosed: 'false', probability: String(Math.round(((i + 1) / (labels.length + 1)) * 10) / 10) } }));
+      const made = await call('POST', '/crm/v3/pipelines/deals', { label: f.label, displayOrder: 1, stages });
+      if (made.status !== 201) return pipelinesPage(call, side, hub, String(made.body.message ?? 'The pipeline could not be created.'), 422);
+      return pipelinesPage(call, side, hub, `Pipeline ${String(f.label)} created.`);
+    }
+    return pipelinesPage(call, side, hub);
+  }
+
+  if (rest === 'objects/0-1/views/all/list' && request.method === 'GET') {
+    const list = ((await call('GET', `/crm/v3/objects/contacts?limit=100&properties=${CONTACT_PROPS.join(',')}`)).body.results ?? []) as Row[];
+    return portalPage('Contacts', { merchant: side, sections: [{ heading: 'Contacts', empty: 'No contacts yet.', items: list.map((c) => {
+      const p = c.properties as Row;
+      return { title: nameOf(p), detail: String(p.email ?? ''), note: `Record ID ${String(c.id)}`, actions: [{ label: 'Open', action: `${R}/record/0-1/${String(c.id)}`, method: 'get' as const }] };
+    }) }] });
+  }
+  if (rest === 'objects/0-2/views/all/list') {
+    let notice: string | undefined;
+    if (request.method === 'POST') {
+      const f = await formOf(request);
+      const properties = Object.fromEntries(Object.entries(f).filter(([, v]) => v !== ''));
+      const made = await call('POST', '/crm/v3/objects/companies', { properties });
+      notice = made.status === 201 ? `Company ${String(f.name)} created.` : String(made.body.message ?? 'The company could not be created.');
+    }
+    const list = ((await call('GET', '/crm/v3/objects/companies?limit=100')).body.results ?? []) as Row[];
+    const owners = ((await call('GET', '/crm/v3/owners')).body.results ?? []) as Row[];
+    const custom = ((await call('GET', '/crm/v3/properties/companies')).body.results ?? []) as Row[];
+    return portalPage('Companies', { merchant: side, ...(notice ? { notice } : {}),
+      sections: [{ heading: 'Companies', empty: 'No companies yet.', items: list.map((c) => ({ title: String((c.properties as Row).name ?? ''), detail: String((c.properties as Row).domain ?? ''), note: `Record ID ${String(c.id)}` })) }],
+      forms: [{ heading: 'Create company', action: `${R}/objects/0-2/views/all/list`, submit: { label: 'Create' }, fields: [
+        { id: 'name', label: 'Company name' }, { id: 'domain', label: 'Company domain name' },
+        { id: 'hubspot_owner_id', label: 'Company owner', options: owners.map((o) => ({ value: String(o.id), label: `${String(o.firstName)} ${String(o.lastName)}` })) },
+        ...custom.filter((p) => p.hubspotDefined !== true && p.archived !== true).map((p) => ({ id: String(p.name), label: String(p.label) })),
+      ] }] });
+  }
+  const rec = /^record\/(0-1|0-3)\/(\d+)(?:\/(deals|stage))?$/.exec(rest);
+  if (!rec) return undefined;
+  const [, type, id, act] = rec;
+  if (type === '0-1') {
+    if (act === 'deals' && request.method === 'POST') {
+      const f = await formOf(request);
+      const [pipeline, dealstage] = (f.stage ?? '').split('/');
+      const made = await call('POST', '/crm/v3/objects/0-3', {
+        properties: { dealname: f.dealname, amount: f.amount, pipeline, dealstage, hubspot_owner_id: String(person.ownerId) },
+        associations: [{ to: { id }, types: [{ associationCategory: 'HUBSPOT_DEFINED', associationTypeId: 3 }] }],
+      });
+      if (made.status !== 201) return contactPage(call, side, hub, id!, String(made.body.message ?? 'The deal could not be created.'), 422);
+      return redirect(`${R}/record/0-3/${String(made.body.id)}`);
+    }
+    if (act || request.method !== 'GET') return undefined;
+    return contactPage(call, side, hub, id!);
+  }
+  if (act === 'stage' && request.method === 'POST') {
+    const f = await formOf(request);
+    const [pipeline, dealstage] = (f.stage ?? '').split('/');
+    const moved = await call('PATCH', `/crm/v3/objects/0-3/${id!}`, { properties: { pipeline, dealstage } });
+    if (moved.status !== 200) return dealPage(call, side, hub, id!, String(moved.body.message ?? 'The deal could not be saved.'), 422);
+    return redirect(`${R}/record/0-3/${id!}`);
+  }
+  if (act || request.method !== 'GET') return undefined;
+  return dealPage(call, side, hub, id!);
+}
+
+async function contactPage(call: Call, side: string, hub: number, id: string, notice?: string, status = 200): Promise<Response> {
+  const got = await call('GET', `/crm/v3/objects/contacts/${id}?properties=${CONTACT_PROPS.join(',')}&associations=deals`);
+  if (got.status !== 200) return portalPage('Contact', { merchant: side, notice: 'This record does not exist.', sections: [] }, 404);
+  const p = got.body.properties as Row;
+  const deals = (((got.body.associations as Row | undefined)?.deals as Row | undefined)?.results ?? []) as Row[];
+  return portalPage(nameOf(p), { merchant: side, back: { href: `/contacts/${hub}/objects/0-1/views/all/list`, label: 'Contacts' }, ...(notice ? { notice } : {}), sections: [
+    { heading: 'About this contact', items: CONTACT_PROPS.filter((k) => p[k] !== undefined && p[k] !== null).map((k) => ({ title: k, detail: String(p[k]) })) },
+    { heading: 'Deals', empty: 'No deals.', items: deals.map((d) => ({ title: `Deal ${String(d.id)}`, actions: [{ label: 'Open', action: `/contacts/${hub}/record/0-3/${String(d.id)}`, method: 'get' as const }] })) },
+  ], forms: [{ heading: 'Create deal', action: `/contacts/${hub}/record/0-1/${id}/deals`, submit: { label: 'Create' }, fields: [
+    { id: 'dealname', label: 'Deal name' }, { id: 'amount', label: 'Amount' },
+    { id: 'stage', label: 'Pipeline and deal stage', options: await stageOptions(call) },
+  ] }] }, status);
+}
+
+async function dealPage(call: Call, side: string, hub: number, id: string, notice?: string, status = 200): Promise<Response> {
+  const got = await call('GET', `/crm/v3/objects/0-3/${id}?properties=dealname,amount,pipeline,dealstage,closedate&associations=contacts`);
+  if (got.status !== 200) return portalPage('Deal', { merchant: side, notice: 'This record does not exist.', sections: [] }, 404);
+  const p = got.body.properties as Row;
+  const contacts = (((got.body.associations as Row | undefined)?.contacts as Row | undefined)?.results ?? []) as Row[];
+  return portalPage(String(p.dealname ?? 'Deal'), { merchant: side, ...(notice ? { notice } : {}), sections: [
+    { heading: 'About this deal', items: ['dealname', 'amount', 'pipeline', 'dealstage'].map((k) => ({ title: k, detail: String(p[k] ?? '') })) },
+    { heading: 'Contacts', empty: 'No contacts.', items: contacts.map((c) => ({ title: `Contact ${String(c.id)}`, actions: [{ label: 'Open', action: `/contacts/${hub}/record/0-1/${String(c.id)}`, method: 'get' as const }] })) },
+  ], forms: [{ heading: 'Deal stage', action: `/contacts/${hub}/record/0-3/${id}/stage`, submit: { label: 'Save' }, fields: [
+    { id: 'stage', label: 'Deal stage', value: `${String(p.pipeline)}/${String(p.dealstage)}`, options: await stageOptions(call) },
+  ] }] }, status);
+}
+
+async function pipelinesPage(call: Call, side: string, hub: number, notice?: string, status = 200): Promise<Response> {
+  const pipelines = ((await call('GET', '/crm/v3/pipelines/deals')).body.results ?? []) as Row[];
+  return portalPage('Deal pipelines', { merchant: side, ...(notice ? { notice } : {}),
+    sections: pipelines.map((p) => ({ heading: `${String(p.label)} (pipeline ID ${String(p.id)})`, items: ((p.stages ?? []) as Row[]).map((s) => ({
+      title: String(s.label), detail: `Stage ID: ${String(s.id)}`, note: (s.metadata as Row | undefined)?.isClosed === 'true' ? `Closed (probability ${String((s.metadata as Row).probability)})` : 'Open' })) })),
+    forms: [{ heading: 'Create pipeline', action: `/settings/${hub}/objects/deals/pipelines`, submit: { label: 'Create pipeline' }, fields: [
+      { id: 'label', label: 'Pipeline name' }, { id: 'stages', label: 'Stages, in order, separated by commas' },
+      { id: 'won', label: 'Closed won stage' }, { id: 'lost', label: 'Closed lost stage' },
+    ] }] }, status);
+}