@volter/twin-hubspot 0.1.0

package/src/hubspot-connector.ts

@@ -0,0 +1,419 @@
+// HubSpot CONNECTOR — the live-vendor pull/push path that gives the HubSpot twin the full
+// "git for SaaS" lifecycle.
+//
+// PULL  (real → twin):  page real CRM records (contacts, companies, deals, tickets) plus the
+//                       portal's owners out of api.hubapi.com, map them → SyncResource[], and
+//                       fold into the observed-event log via observeResources (the kernel dedupes — a
+//                       re-pull of identical state appends nothing).
+// PUSH  (twin → real):  for every PENDING local action, call the real HubSpot CRM API and
+//                       confirmAction on success.
+//
+// The vendor I/O is an INJECTED executor (the auth boundary): the kernel and this pack hold NO
+// HubSpot token and import NO network client. Offline/tests pass a fake executor; live runs pass
+// `liveHubspotExecute(accessToken)`. Same code path either way.
+import { assertBudgetGuardIntact, confirmAction, deployableEntries, observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { HubspotBudget, HubspotBudgetError, hubspotCallWeight, type HubspotBudgetOptions } from './hubspot-budget.ts';
+import { OBJECT_TYPES, type ObjectType } from './hubspot-twin.ts';
+
+const SERVICE = 'hubspot';
+
+/** Subject types that are twin-internal state and are never pushed to a real portal. */
+const INTERNAL_SUBJECT_TYPES = new Set(['owner']);
+
+/** The HubSpot error envelope, as the vendor documents it. */
+export type HubspotErrorBody = { status?: string; message?: string; category?: string; correlationId?: string; errors?: unknown[] };
+
+/**
+ * The injected real-HubSpot boundary. `execute` issues ONE HubSpot REST call and returns the
+ * parsed JSON body together with the HTTP status, because HubSpot signals refusal with the STATUS
+ * (a 4xx carrying `{status:'error', …}`), and a body-only contract cannot tell a refusal from an
+ * empty account. A real client (a raw fetch wrapper) is structurally assignable; tests pass a fake.
+ */
+export type HubspotExecute = (
+  method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+) => Promise<{ httpStatus: number; body: unknown }>;
+
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveHubspotOptions = {
+  /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+  fetchImpl?: typeof fetch;
+  /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+  budget?: HubspotBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: HubspotBudgetOptions;
+};
+
+/**
+ * A live executor against the real HubSpot CRM API (the operator's own private-app token).
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `api.hubapi.com` request, and therefore the one
+ * place the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE
+ * the request goes out (`checkBudget`, which THROWS `HubspotBudgetError` instead of returning when
+ * the ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a
+ * `Retry-After` / 429 / `X-HubSpot-RateLimit-Remaining: 0` signal becomes a persisted cooldown that
+ * makes every later call fail fast WITHOUT touching HubSpot. There is deliberately no OPTION to
+ * disable the guard, and no value a caller can pass for `budget` that yields an unguarded client.
+ * That is NOT immunity from a caller who WANTS one: a fresh `budgetOptions.path` per construction,
+ * or an injected clock, restores the allowance, because the seam tests need cannot be denied to a
+ * determined caller in the same process. See `hubspot-budget.ts` and the kernel's own header.
+ */
+export function liveHubspotExecute(
+  accessToken: string,
+  base = 'https://api.hubapi.com',
+  opts: LiveHubspotOptions = {},
+): HubspotExecute {
+  const doFetch = opts.fetchImpl ?? fetch;
+  // `null`/`undefined` (or omitting it) build the default budget. Anything else must be an
+  // UNMODIFIED HubspotBudget: a duck-typed stand-in, a SUBCLASS that overrides `checkBudget`, and
+  // a Proxy that traps it are all refused, because all three are one-liners that would otherwise
+  // hand back a client with no ceiling at all. The default ledger is keyed by a hash of THIS
+  // token — HubSpot limits per app/token, so a cwd-scoped ledger would hand the same token a fresh
+  // allowance per checkout/worktree/CI leg.
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, HubspotBudget, 'liveHubspotExecute')
+    : new HubspotBudget({ token: accessToken, ...(opts.budgetOptions ?? {}) });
+  return async (method, path, body) => {
+    const headers: Record<string, string> = { Authorization: `Bearer ${accessToken}` };
+    const init: { method: string; headers: Record<string, string>; body?: string } = { method, headers };
+    if (method !== 'GET' && body !== undefined) {
+      headers['Content-Type'] = 'application/json';
+      init.body = JSON.stringify(body);
+    }
+    const weight = hubspotCallWeight(method, path);
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const res = await doFetch(`${base}${path}`, init);
+    const resHeaders: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => { resHeaders[k.toLowerCase()] = v; });
+    const text = await res.text();
+    let parsed: unknown = null;
+    if (text) { try { parsed = JSON.parse(text) as unknown; } catch { parsed = { status: 'error', message: text }; } }
+    // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+    // `Retry-After` beyond the cap is not something to sleep off) — the cooldown is persisted
+    // first either way, so the refusal survives the throw.
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer HubSpot ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof HubspotBudgetError) || !res.ok) throw error;
+    }
+    return { httpStatus: res.status, body: parsed };
+  };
+}
+
+// ── mapping ────────────────────────────────────────────────────────────────────────────────
+/**
+ * Map a HubSpot SimplePublicObject → a SyncResource the kernel can fold.
+ *
+ * The renames are load-bearing, not cosmetic: the kernel's META set (`control-plane/src/
+ * actions.ts`) silently DROPS resource fields named `type`, `id` or `updatedAt`, and HubSpot's
+ * record carries all three. A field literally named `id` would vanish from the projection with no
+ * error at all.
+ *
+ * `hsLocalMint: false` is equally load-bearing. The twin's own create handler stamps
+ * `hsLocalMint: true`, and `hubspotRequestForAction` reads that stamp to decide whether a record
+ * id addresses anything in the real portal. `observeResources` MERGES observed fields onto an existing
+ * subject, so if a portal record ever landed on a subject a local create had already minted, an
+ * absent stamp here would leave the stale `true` in place — and the now-genuinely-real record
+ * would be permanently unaddressable, pushing every later edit as a duplicate CREATE. Stamping it
+ * false makes the OBSERVED row win. (`HUBSPOT_LOCAL_ID_BASE` is what makes that collision
+ * implausible in the first place; this is the belt to its braces.)
+ */
+export function mapCrmObject(objectType: ObjectType, o: Record<string, unknown>): SyncResource {
+  return {
+    type: 'crm_object',
+    id: `${objectType}_${String(o.id)}`,
+    fields: {
+      objectType,
+      hsId: String(o.id),
+      hsCreatedAt: String(o.createdAt ?? ''),
+      hsUpdatedAt: String(o.updatedAt ?? ''),
+      archived: o.archived === true,
+      hsLocalMint: false,
+      props: (o.properties ?? {}) as Record<string, unknown>,
+    },
+  };
+}
+
+/**
+ * The properties a pull ASKS FOR, per object type.
+ *
+ * HubSpot's list endpoints return only a small default property set unless `?properties=` names
+ * more, so a pull that omitted it would land records with near-empty property maps against a real
+ * portal — while a fixture handing back rich properties would hide that. These are the
+ * HubSpot-defined names the twin models for each type; the portal's CUSTOM properties still need
+ * the schema pull filed as `hubspot.connector.pull_properties`.
+ */
+export const PULL_PROPERTIES: Record<ObjectType, string[]> = {
+  contacts: ['email', 'firstname', 'lastname', 'phone', 'company', 'lifecyclestage', 'hubspot_owner_id', 'createdate', 'lastmodifieddate', 'hs_object_id'],
+  companies: ['name', 'domain', 'city', 'industry', 'phone', 'hubspot_owner_id', 'createdate', 'hs_lastmodifieddate', 'hs_object_id'],
+  deals: ['dealname', 'amount', 'dealstage', 'pipeline', 'closedate', 'hubspot_owner_id', 'createdate', 'hs_lastmodifieddate', 'hs_object_id'],
+  tickets: ['subject', 'content', 'hs_pipeline', 'hs_pipeline_stage', 'hs_ticket_priority', 'hubspot_owner_id', 'createdate', 'hs_lastmodifieddate', 'hs_object_id'],
+};
+
+/** Map a HubSpot PublicOwner → a SyncResource. */
+export function mapOwner(o: Record<string, unknown>): SyncResource {
+  return {
+    type: 'owner',
+    id: `owner_${String(o.id)}`,
+    fields: {
+      ownerId: String(o.id), email: o.email ?? null, firstName: o.firstName ?? null,
+      lastName: o.lastName ?? null, userId: o.userId ?? null, ownerType: o.type ?? 'PERSON',
+      archived: o.archived === true, teams: o.teams ?? [],
+      hsCreatedAt: String(o.createdAt ?? ''), hsUpdatedAt: String(o.updatedAt ?? ''),
+    },
+  };
+}
+
+/**
+ * A STRICTLY INCREASING poll timestamp — the connector's `occurredAt` default.
+ *
+ * NOT a pinned constant, deliberately. The kernel hashes an observed event over
+ * (`occurredAt` + post-state), so under a fixed poll time a vendor value that REVERTS
+ * (A → B → A across polls) collides with its own earlier observation: `observeResources` reports
+ * `deltasAppended: 1` while nothing lands, and the projection keeps serving the stale value.
+ * Forced strictly increasing within the process so two polls in the same millisecond still get
+ * distinct stamps (`dynadot-connector.ts` is the precedent).
+ */
+let lastPollMs = 0;
+export function pollTimestamp(): string {
+  const now = Date.now();
+  lastPollMs = now > lastPollMs ? now : lastPollMs + 1;
+  return new Date(lastPollMs).toISOString();
+}
+
+/**
+ * Read one vendor reply, or THROW.
+ *
+ * A refused pull is NOT an empty account: a connector that maps a failure to an empty resource
+ * list hands the kernel an empty account to fold OVER real observed state, silently deleting it.
+ * HubSpot answers a refusal with a 4xx/5xx AND a `{status:'error', category, message}` body, so
+ * both are checked — a body-only check would miss a bare 401 and a status-only check would miss
+ * an error envelope that arrived with a 2xx.
+ */
+function unwrap(res: { httpStatus: number; body: unknown }, what: string): Record<string, unknown> {
+  const body = (res.body ?? {}) as HubspotErrorBody & Record<string, unknown>;
+  if (res.httpStatus < 200 || res.httpStatus >= 300) {
+    throw new Error(`hubspot ${what} refused: HTTP ${res.httpStatus} ${body.category ?? ''} ${body.message ?? ''}`.trim());
+  }
+  if (body.status === 'error') {
+    throw new Error(`hubspot ${what} refused: ${body.category ?? 'error'} ${body.message ?? ''}`.trim());
+  }
+  return body;
+}
+
+/** Page through one CRM object type, following `paging.next.after` until it is absent. */
+async function collectObjects(execute: HubspotExecute, objectType: ObjectType, pageSize = 100): Promise<SyncResource[]> {
+  const out: SyncResource[] = [];
+  let after: string | null = null;
+  // Bounded so a vendor (or a fake) that never stops advancing cannot loop forever.
+  for (let page = 0; page < 100; page += 1) {
+    const qs = `limit=${pageSize}&properties=${encodeURIComponent(PULL_PROPERTIES[objectType].join(','))}${after === null ? '' : `&after=${encodeURIComponent(after)}`}`;
+    const body = unwrap(await execute('GET', `/crm/v3/objects/${objectType}?${qs}`), `pull ${objectType}`);
+    const results = Array.isArray(body.results) ? (body.results as Record<string, unknown>[]) : [];
+    for (const r of results) out.push(mapCrmObject(objectType, r));
+    const paging = body.paging as { next?: { after?: unknown } } | undefined;
+    const next = paging?.next?.after;
+    if (next === undefined || next === null || String(next) === after) break;
+    after = String(next);
+  }
+  return out;
+}
+
+/** Read the portal's owners. */
+async function collectOwners(execute: HubspotExecute): Promise<SyncResource[]> {
+  const body = unwrap(await execute('GET', '/crm/v3/owners'), 'pull owners');
+  const results = Array.isArray(body.results) ? (body.results as Record<string, unknown>[]) : [];
+  return results.map(mapOwner);
+}
+
+/** PULL one CRM object type into the twin's observed log (idempotent). */
+export async function pullHubspotObjects(execute: HubspotExecute, objectType: ObjectType, root?: string, occurredAt?: string): Promise<number> {
+  const resources = await collectObjects(execute, objectType);
+  ((__at) => observeResources(SERVICE, resources, { ...(root !== undefined ? { root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt ?? pollTimestamp());
+  return resources.length;
+}
+
+/** PULL the portal's owners into the twin's observed log (idempotent). */
+export async function pullHubspotOwners(execute: HubspotExecute, root?: string, occurredAt?: string): Promise<number> {
+  const resources = await collectOwners(execute);
+  ((__at) => observeResources(SERVICE, resources, { ...(root !== undefined ? { root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt ?? pollTimestamp());
+  return resources.length;
+}
+
+/** Full pull: all four standard CRM object types + owners, folded record-type by record-type. */
+export async function pullHubspotAll(execute: HubspotExecute, root?: string, occurredAt?: string): Promise<Record<string, number>> {
+  const at = occurredAt ?? pollTimestamp();
+  const counts: Record<string, number> = {};
+  for (const objectType of OBJECT_TYPES) counts[objectType] = await pullHubspotObjects(execute, objectType, root, at);
+  counts.owners = await pullHubspotOwners(execute, root, at);
+  return counts;
+}
+
+/**
+ * D7 consumer-facing pull entry point: pull from real HubSpot (the four standard CRM objects +
+ * owners) and fold into the twin in ONE observation, returning the standard
+ * `{ observed, deltasAppended }` result. Idempotent — a re-pull of identical state appends
+ * nothing (deltasAppended drops to 0).
+ */
+export async function syncHubspotFromReal(
+  execute: HubspotExecute,
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const occurredAt = opts.occurredAt ?? pollTimestamp();
+  const resources: SyncResource[] = [];
+  for (const objectType of OBJECT_TYPES) resources.push(...(await collectObjects(execute, objectType)));
+  resources.push(...(await collectOwners(execute)));
+  const result = ((__at) => observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt);
+  return { observed: resources.length, deltasAppended: result.appended };
+}
+
+// ── push ───────────────────────────────────────────────────────────────────────────────────
+/** Translate one pending local action into the real HubSpot REST call it represents, or null. */
+export function hubspotRequestForAction(action: TwinAction): { method: 'POST' | 'PATCH' | 'PUT' | 'DELETE'; path: string; body?: Record<string, unknown> } | null {
+  if (INTERNAL_SUBJECT_TYPES.has(action.subject.type)) return null;
+  const fields = (action.fields ?? {}) as Record<string, unknown>;
+
+  if (action.subject.type === 'crm_object') {
+    const objectType = String(fields.objectType ?? '') as ObjectType;
+    if (!(OBJECT_TYPES as readonly string[]).includes(objectType)) return null;
+    const hsId = fields.hsId === undefined ? null : String(fields.hsId);
+    const props = (fields.props ?? {}) as Record<string, unknown>;
+    // A LOCALLY MINTED id must never be sent to the real portal as a real record id. The twin
+    // mints from `HUBSPOT_LOCAL_ID_BASE` (9e11) upward — an order of magnitude above the largest
+    // HubSpot record id this repo has observed — so such an id addresses NOTHING in a real
+    // account. A local create is therefore a CREATE upstream, and only a record whose id came
+    // from the real portal may be addressed by id. The two sides are told apart by an explicit
+    // stamp, in both directions: the twin's create handler sets `hsLocalMint: true` and every
+    // later write carries it forward, while `mapCrmObject` above sets it FALSE on anything a pull
+    // observed. Without this guard the archive branch below would fire
+    // `DELETE /crm/v3/objects/<type>/<a twin-minted id>` at the operator's real portal — the
+    // exact class of defect groq's round-two review found, one twin-minted id fired at a live
+    // account.
+    const addressable = fields.hsLocalMint !== true && hsId !== null;
+    if (fields.archived === true) {
+      if (!addressable) return null;
+      return { method: 'DELETE', path: `/crm/v3/objects/${objectType}/${hsId}` };
+    }
+    // Strip the system properties HubSpot mints itself — sending them back is rejected upstream.
+    const payload: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(props)) {
+      if (k === 'hs_object_id' || k === 'createdate' || k === 'lastmodifieddate' || k === 'hs_lastmodifieddate') continue;
+      payload[k] = v;
+    }
+    if (addressable) return { method: 'PATCH', path: `/crm/v3/objects/${objectType}/${hsId}`, body: { properties: payload } };
+    return { method: 'POST', path: `/crm/v3/objects/${objectType}`, body: { properties: payload } };
+  }
+
+  if (action.subject.type === 'property') {
+    const objectType = String(fields.objectType ?? '');
+    const name = String(fields.name ?? '');
+    if (!objectType || !name) return null;
+    if (fields.archived === true) return { method: 'DELETE', path: `/crm/v3/properties/${objectType}/${name}` };
+    return {
+      method: 'POST', path: `/crm/v3/properties/${objectType}`,
+      body: { name, label: fields.label, type: fields.propType, fieldType: fields.fieldType, groupName: fields.groupName, description: fields.description ?? '' },
+    };
+  }
+
+  if (action.subject.type === 'property_group') {
+    const objectType = String(fields.objectType ?? '');
+    const name = String(fields.name ?? '');
+    if (!objectType || !name) return null;
+    if (fields.archived === true) return { method: 'DELETE', path: `/crm/v3/properties/${objectType}/groups/${name}` };
+    return { method: 'POST', path: `/crm/v3/properties/${objectType}/groups`, body: { name, label: fields.label, displayOrder: fields.displayOrder ?? -1 } };
+  }
+
+  if (action.subject.type === 'pipeline') {
+    const objectType = String(fields.objectType ?? '');
+    if (!objectType) return null;
+    // Pipeline ids are minted locally (`pipeline_N`) and name nothing upstream, so a local
+    // pipeline is only ever a CREATE; an archive of one has no real target to address.
+    if (fields.archived === true) return null;
+    return { method: 'POST', path: `/crm/v3/pipelines/${objectType}`, body: { label: fields.label, displayOrder: fields.displayOrder ?? 0, stages: fields.stages ?? [] } };
+  }
+
+  // Associations address BOTH sides by id, so the same locally-minted-id rule applies: a twin
+  // association between two locally created records names nothing in the real portal.
+  if (action.subject.type === 'association') return null;
+  return null;
+}
+
+/** PUSH every pending local action to the real portal; confirm each on success. */
+export async function pushPendingHubspotActions(execute: HubspotExecute, root?: string, occurredAt?: string): Promise<number> {
+  const pending = deployableEntries(SERVICE, root);
+  const at = occurredAt ?? pollTimestamp();
+  let pushed = 0;
+  for (const action of pending) {
+    const req = hubspotRequestForAction(action);
+    // An action with no upstream representation is SKIPPED, never aborted — but it is also never
+    // confirmed, so it stays pending and visible rather than silently disappearing.
+    if (!req) continue;
+    const res = await execute(req.method, req.path, req.body);
+    const body = (res.body ?? {}) as HubspotErrorBody;
+    const succeeded = res.httpStatus >= 200 && res.httpStatus < 300 && body.status !== 'error';
+    if (!succeeded) continue;
+    confirmAction({ service: SERVICE, actionId: action.id, subject: action.subject, fields: (action.fields ?? {}) as Record<string, unknown>, occurredAt: at, ...(root !== undefined ? { root } : {}) });
+    pushed += 1;
+  }
+  return pushed;
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+
+/** A `HubspotExecute` over the kernel's executor. At a REAL boundary the kernel sets the sealed
+ *  credential over these headers (executor.ts); at the twin's own wire any credential is one. */
+export function hubspotExecuteOver(execute: RemoteExecute): HubspotExecute {
+  return async (method, path, body) => {
+    const res = await execute({
+      method, path,
+      headers: { accept: 'application/json', 'content-type': 'application/json', authorization: 'Bearer twin' },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    let parsed: unknown = {};
+    try { parsed = JSON.parse(res.body || '{}'); } catch { parsed = {}; }
+    return { httpStatus: res.status, body: parsed };
+  };
+}
+
+/** The refresh adapter: HubSpot enumerates every CRM object type this twin holds, so the whole
+ *  portal comes back without the world having to say what it has. */
+export async function syncHubspotFromRemote(
+  execute: RemoteExecute,
+  opts: { root?: string; origin?: string; occurredAt?: string } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  return syncHubspotFromReal(hubspotExecuteOver(execute), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+    occurredAt: opts.occurredAt ?? pollTimestamp(),
+  });
+}
+
+/**
+ * The perform adapter.
+ *
+ * `hubspotRequestForAction` already carries this pack's hard-won rule: a record stamped
+ * `hsLocalMint` has never been seen by the portal, so it CREATES rather than patching an id that
+ * account does not have. Protocol 2 adds the other half — `ctx.resolve` gives the id HubSpot minted
+ * for a subject this world already deployed, so the patch addresses the real record.
+ */
+export async function performHubspotAction(execute: RemoteExecute, action: TwinAction, ctx: PerformContext): Promise<PushOutcome> {
+  const req = hubspotRequestForAction(action);
+  if (!req) {
+    const op = action.operation ?? `${action.subject.type}.update`;
+    return { externalId: action.subject.id, data: { performed: false, reason: `${op} has no HubSpot mapping — it is this world's own record` } };
+  }
+  const resolved = ctx.resolve(action.subject.type, action.subject.id);
+  const path = resolved === action.subject.id ? req.path : req.path.replace(new RegExp(`/${action.subject.id}(?=$|[/?])`), `/${resolved}`);
+  const answered = await hubspotExecuteOver(execute)(req.method, path, req.body);
+  if (answered.httpStatus < 200 || answered.httpStatus >= 300) {
+    throw new Error(`hubspot ${req.method} ${path} refused: HTTP ${answered.httpStatus} ${JSON.stringify(answered.body).slice(0, 200)}`);
+  }
+  const body = (answered.body ?? {}) as Record<string, unknown>;
+  const externalId = typeof body.id === 'string' ? body.id : resolved;
+  return { externalId, data: body };
+}

package/src/hubspot-deferred-capabilities.ts

@@ -0,0 +1,99 @@
+// THE OTHER HALF OF HUBSPOT'S DENOMINATOR — split, deliberately, into two very different things.
+//
+// `api.hubapi.com` fronts eleven top-level API families and 936 generated operations in
+// @hubspot/api-client 14.0.1. This twin's scope is the CRM (see hubspot-areas.ts), and the rest of
+// the host is split here into two lists that read differently even though both are `todo`:
+//
+//   HUBSPOT_UNMODELED_CRM_CAPABILITIES — CRM surface this twin has not built. Engagements,
+//     commerce, custom-object schemas, lists, imports/exports and extensions all ride the same
+//     /crm/ routes this twin already serves.
+//
+//   HUBSPOT_DEFERRED_AREA_CAPABILITIES — separate HubSpot PRODUCTS behind the same host, each
+//     with its own object model and no handler here yet.
+//
+// Three things this file is deliberately NOT:
+//   • It is not denominator padding. Every entry names a SPECIFIC operation HubSpot really
+//     exposes, taken from the generated request factory that issues it, at the same granularity
+//     the modeled areas use.
+//   • It is not a promise dressed as coverage. Every deferred entry is a `todo`: nothing answers
+//     for it today, and `hubspot-areas.ts` records why the area is a separate product.
+//   • It is not unchecked. `hubspot.deferred.area_routes_refused` in the main manifest drives a
+//     real request at one route from each DEFERRED family and asserts the twin REFUSES it in
+//     HubSpot's own error envelope — never a fabricated success. It probes no /crm/ route,
+//     because the CRM is this pack's own declared scope.
+import type { CapabilitySpec } from '@volter/world-tooling';
+
+/** Not built yet. A plain todo. */
+const unbuilt = (id: string, area: string, title: string, tier: CapabilitySpec['tier']): CapabilitySpec => ({
+  id, area, title, dimension: 'api', tier, expected: 'todo',
+});
+
+/** CRM surface this twin has not built yet — inside the declared scope. */
+export const HUBSPOT_UNMODELED_CRM_CAPABILITIES: CapabilitySpec[] = [
+  // ── CRM engagements ───────────────────────────────────────────────────────────────────────
+  unbuilt('hubspot.engagements.notes', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/notes — note engagements', 'common'),
+  unbuilt('hubspot.engagements.tasks', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/tasks — task engagements', 'common'),
+  unbuilt('hubspot.engagements.calls', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/calls — call engagements', 'common'),
+  unbuilt('hubspot.engagements.emails', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/emails — logged email engagements', 'common'),
+  unbuilt('hubspot.engagements.meetings', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/meetings — meeting engagements', 'common'),
+  unbuilt('hubspot.engagements.leads', 'crm-engagements', 'POST/GET/PATCH/DELETE /crm/v3/objects/leads — the leads object', 'niche'),
+  unbuilt('hubspot.engagements.feedback_submissions', 'crm-engagements', 'GET /crm/v3/objects/feedback_submissions — NPS/CSAT submissions (read-only)', 'niche'),
+
+  // ── CRM commerce ──────────────────────────────────────────────────────────────────────────
+  unbuilt('hubspot.commerce.products', 'crm-commerce', 'POST/GET/PATCH/DELETE /crm/v3/objects/products — the product library', 'common'),
+  unbuilt('hubspot.commerce.line_items', 'crm-commerce', 'POST/GET/PATCH/DELETE /crm/v3/objects/line_items — deal line items', 'common'),
+  unbuilt('hubspot.commerce.quotes', 'crm-commerce', 'POST/GET/PATCH/DELETE /crm/v3/objects/quotes — quotes and their approval state', 'niche'),
+  unbuilt('hubspot.commerce.invoices', 'crm-commerce', 'GET /crm/v3/objects/invoices — invoices (read-only)', 'niche'),
+  unbuilt('hubspot.commerce.deal_splits', 'crm-commerce', 'POST /crm/v3/objects/deals/splits/batch/upsert — deal revenue splits', 'niche'),
+
+  // ── CRM custom object schemas ─────────────────────────────────────────────────────────────
+  unbuilt('hubspot.schemas.create', 'crm-schemas', 'POST /crm-object-schemas/v3/schemas — define a custom object type', 'common'),
+  unbuilt('hubspot.schemas.list', 'crm-schemas', 'GET /crm-object-schemas/v3/schemas — list the portal\'s object type definitions', 'common'),
+  unbuilt('hubspot.schemas.custom_object_records', 'crm-schemas', 'CRUD on /crm/v3/objects/{objectTypeId} records for a custom type (2-3453932 / p{portalId}_name)', 'common'),
+
+  // ── CRM lists ─────────────────────────────────────────────────────────────────────────────
+  unbuilt('hubspot.lists.create', 'crm-lists', 'POST /crm/v3/lists — create a static or dynamic list', 'common'),
+  unbuilt('hubspot.lists.memberships', 'crm-lists', 'GET/PUT/DELETE /crm/v3/lists/{listId}/memberships — list membership', 'common'),
+  unbuilt('hubspot.lists.search', 'crm-lists', 'POST /crm/v3/lists/search — search list definitions', 'niche'),
+
+  // ── CRM imports / exports ─────────────────────────────────────────────────────────────────
+  unbuilt('hubspot.imports.create', 'crm-imports-exports', 'POST /crm/v3/imports — start a bulk CSV import job', 'niche'),
+  unbuilt('hubspot.imports.status', 'crm-imports-exports', 'GET /crm/v3/imports/{importId} — poll an import job', 'niche'),
+  unbuilt('hubspot.exports.create', 'crm-imports-exports', 'POST /crm/v3/exports/export/async — start a bulk export job', 'niche'),
+
+  // ── CRM extensions ────────────────────────────────────────────────────────────────────────
+  unbuilt('hubspot.extensions.cards', 'crm-extensions', 'POST/GET/PATCH/DELETE /crm/v3/extensions/cards-dev/{appId} — CRM card definitions', 'niche'),
+  unbuilt('hubspot.extensions.calling', 'crm-extensions', 'GET/POST /crm/v3/extensions/calling/{appId}/settings — calling provider registration', 'niche'),
+  unbuilt('hubspot.extensions.videoconferencing', 'crm-extensions', 'PUT /crm/v3/extensions/videoconferencing/settings/{appId}', 'niche'),
+  unbuilt('hubspot.extensions.timeline', 'crm-extensions', 'POST /integrators/timeline/v3/events — timeline event ingest + templates', 'niche'),
+
+];
+
+/** Separate HubSpot PRODUCTS behind the same host — outside this pack's declared CRM scope, and
+ *  not built here; `hubspot-areas.ts` records why each is a separate product. */
+export const HUBSPOT_DEFERRED_AREA_CAPABILITIES: CapabilitySpec[] = [
+  // ── CMS ───────────────────────────────────────────────────────────────────────────────────
+  unbuilt('hubspot.cms.pages', 'cms', 'CRUD on /cms/v3/pages/site-pages and /landing-pages', 'niche'),
+  unbuilt('hubspot.cms.blog_posts', 'cms', 'CRUD on /cms/v3/blogs/posts', 'niche'),
+  unbuilt('hubspot.cms.hubdb', 'cms', 'CRUD on /cms/v3/hubdb/tables and their rows', 'niche'),
+  unbuilt('hubspot.cms.url_redirects', 'cms', 'CRUD on /cms/v3/url-redirects', 'niche'),
+  unbuilt('hubspot.cms.source_code', 'cms', 'GET/PUT/DELETE /cms/v3/source-code/{environment}/content/{path}', 'niche'),
+  unbuilt('hubspot.cms.domains', 'cms', 'GET /cms/v3/domains — connected domains', 'niche'),
+
+  // ── Marketing ─────────────────────────────────────────────────────────────────────────────
+  unbuilt('hubspot.marketing.emails', 'marketing', 'CRUD on /marketing/v3/emails — marketing email assets', 'niche'),
+  unbuilt('hubspot.marketing.forms', 'marketing', 'CRUD on /marketing/v3/forms — HubSpot forms', 'common'),
+  unbuilt('hubspot.marketing.events', 'marketing', 'CRUD on /marketing/v3/marketing-events — marketing event objects', 'niche'),
+  unbuilt('hubspot.marketing.transactional_send', 'marketing', 'POST /marketing/v3/transactional/single-email/send — send a real transactional email', 'niche'),
+
+  // ── the remaining families, one representative operation each ─────────────────────────────
+  unbuilt('hubspot.automation.custom_actions', 'automation', 'CRUD on /automation/v4/actions/{appId} — custom workflow action definitions', 'niche'),
+  unbuilt('hubspot.conversations.visitor_identification', 'conversations', 'POST /conversations/v3/visitor-identification/tokens/create', 'niche'),
+  unbuilt('hubspot.files.upload', 'files', 'POST /files/v3/files — upload a file to the file manager', 'niche'),
+  unbuilt('hubspot.analytics.send_event', 'analytics-events', 'POST /events/v3/send — send a custom behavioral event', 'niche'),
+  unbuilt('hubspot.analytics.event_definitions', 'analytics-events', 'CRUD on /events/v3/event-definitions', 'niche'),
+  unbuilt('hubspot.communication_preferences.status', 'communication-preferences', 'GET/POST /communication-preferences/v3/status/email/{emailAddress}', 'niche'),
+  unbuilt('hubspot.settings.users', 'settings', 'CRUD on /settings/v3/users — portal user seats', 'niche'),
+  unbuilt('hubspot.settings.business_units', 'settings', 'GET /settings/v3/business-units/user/{userId}', 'niche'),
+  unbuilt('hubspot.webhooks.subscriptions', 'webhooks', 'CRUD on /webhooks/v3/{appId}/subscriptions — app event subscriptions', 'niche'),
+];

package/src/hubspot-journey.uitest.ts

@@ -0,0 +1,104 @@
+// HUBSPOT UI JOURNEY — the mirror-navigability rung, driven by real headless Playwright
+// chromium with role/text locators only.
+//
+// Seeds records through the pack's OWN write path (the real vendor endpoints,
+// `POST /crm/v3/objects/{objectType}` — the same handler every other suite uses, never a
+// hand-written events.jsonl), boots the real mirror server on an ephemeral port, and drives it.
+//
+// Proves: the CRM opens on Contacts showing both seeded contacts; clicking a nav item (a real
+// <button>, role-reachable) switches the section and the previous section's records are GONE
+// from the DOM (a real re-fetch, not a hidden panel); and the Deals section's Board toggle
+// renders the seeded deals as cards grouped into their stage columns — the screen a sales rep
+// actually works in.
+//
+// Must never hard-fail on a browserless machine: `requireBrowser` skips cleanly with a loud
+// console line rather than reporting a pass over a rung that ran nothing.
+import { describe, test } from 'bun:test';
+import { JOURNEY_TIMEOUT_MS, gone, requireBrowser, runUiJourney, visible } from '@volter/world-tooling';
+import { createHubspotMirrorServer } from './hubspot-mirror-ui.ts';
+import { handleHubspotTwinRequest } from './hubspot-twin.ts';
+
+const JOURNEY_LABEL = 'hubspot UI journey';
+
+async function seedCrm(root: string) {
+  const create = (objectType: string, properties: Record<string, string>, at: string) =>
+    handleHubspotTwinRequest({ method: 'POST', path: `/crm/v3/objects/${objectType}`, body: JSON.stringify({ properties }), root, occurredAt: at });
+  await create('contacts', { email: 'ada@journey.test', firstname: 'Ada', lastname: 'JourneyContact' }, '2026-05-01T00:00:00.000Z');
+  await create('contacts', { email: 'bo@journey.test', firstname: 'Bo', lastname: 'SecondContact' }, '2026-05-01T00:00:01.000Z');
+  await create('companies', { name: 'JourneyCompany Ltd', domain: 'journey.test' }, '2026-05-01T00:00:02.000Z');
+  await create('deals', { dealname: 'JourneyWonDeal', amount: '7400', dealstage: 'closedwon' }, '2026-05-01T00:00:03.000Z');
+  await create('deals', { dealname: 'JourneyOpenDeal', amount: '1150', dealstage: 'qualifiedtobuy' }, '2026-05-01T00:00:04.000Z');
+}
+
+const serve = async (root: string) => {
+  const server = await createHubspotMirrorServer({ root, port: 0 });
+  return { url: server.url, stop: () => server.stop() };
+};
+
+describe('hubspot UI journey', () => {
+  test('the CRM opens on Contacts and the nav switches sections against live twin data', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    await runUiJourney({
+      label: 'hubspot the CRM opens on Contacts and the nav switches sections',
+      seed: seedCrm,
+      serve,
+      journey: async (page) => {
+        // 1. The default section is Contacts, and BOTH seeded contacts are on screen — data
+        //    that only exists because the seed above wrote it through the vendor's own API.
+        await visible(page, 'Ada JourneyContact');
+        await visible(page, 'Bo SecondContact');
+        await visible(page, 'ada@journey.test');
+        // A company seeded in the same root is NOT on the contacts screen.
+        await gone(page, 'JourneyCompany Ltd');
+
+        // 2. Click the Companies nav item — the company appears and the contacts UNMOUNT,
+        //    which is what distinguishes a real re-fetch from a hidden panel.
+        await page.getByRole('button', { name: /^Companies$/ }).click();
+        await visible(page, 'JourneyCompany Ltd');
+        await visible(page, 'journey.test');
+        await gone(page, 'Ada JourneyContact');
+
+        // 3. Click Deals — both deals render, with the mirror's own money formatting.
+        await page.getByRole('button', { name: /^Deals$/ }).click();
+        await visible(page, 'JourneyWonDeal');
+        await visible(page, 'JourneyOpenDeal');
+        await visible(page, '$7,400');
+        await gone(page, 'JourneyCompany Ltd');
+      },
+    });
+  }, JOURNEY_TIMEOUT_MS);
+
+  test('the deal board groups the seeded deals into their pipeline stage columns', async () => {
+    if (!(await requireBrowser(JOURNEY_LABEL))) return;
+
+    await runUiJourney({
+      label: 'hubspot the deal board groups the seeded deals into stage columns',
+      seed: seedCrm,
+      serve,
+      journey: async (page) => {
+        await page.getByRole('button', { name: /^Deals$/ }).click();
+        await visible(page, 'JourneyWonDeal');
+
+        // The Board toggle only exists on the Deals section — click it and the same live rows
+        // re-render as cards under their dealstage columns.
+        await page.getByRole('button', { name: /^Board$/ }).click();
+        await visible(page, 'closedwon');
+        await visible(page, 'qualifiedtobuy');
+        await visible(page, 'JourneyWonDeal');
+        await visible(page, 'JourneyOpenDeal');
+        await visible(page, '$1,150');
+
+        // …and back to the table view, which the board REPLACED rather than overlaid. The check
+        // is a landmark only the table renders — its `Record ID` column header — because a text
+        // check on a stage name proves nothing here: `closedwon` is rendered in BOTH views (the
+        // table shows `dealstage` as a column) and `closedlost` is seeded in NEITHER, so the
+        // original assertion could not fail in either direction (§9 round two).
+        await gone(page, 'Record ID');
+        await page.getByRole('button', { name: /^Table$/ }).click();
+        await visible(page, 'JourneyWonDeal');
+        await visible(page, 'Record ID');
+      },
+    });
+  }, JOURNEY_TIMEOUT_MS);
+});