@volter/twin-hubspot 0.1.0

package/dist/src/webhooks.js

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

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@volter/twin-hubspot",
+  "version": "0.1.0",
+  "description": "Local HubSpot CRM twin — a faithful, stateful local HubSpot v3/v4 CRM API your @hubspot/api-client integration talks to unmodified. Mirror, simulate, and fork. Built on @volter/world-core.",
+  "keywords": [
+    "twin",
+    "local",
+    "mock",
+    "mirror",
+    "simulator",
+    "fixtures",
+    "testing",
+    "api",
+    "crm",
+    "hubspot",
+    "hubapi",
+    "contacts",
+    "deals"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "client",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/hubspot"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/hubspot#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-hubspot": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "@volter/world-ui": "0.1.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "@hubspot/api-client": "^14.0.1",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/accounts.ts

@@ -0,0 +1,127 @@
+// HUBSPOT ACCOUNTS, THEIR USERS, AND WHAT THEY HOLD OUTSIDE THE CRM — the state HubSpot's pages and its OAuth install
+// keep, which no CRM operation reads or writes: an account (its Hub ID, name and subscription, closed or not), the
+// people who sign in to it (each a user, and so an owner of its records), their browser sessions, the apps an account
+// builds as developer projects (each with its client ID and secret, redirect URLs, scopes and webhook subscriptions),
+// and each app's installs in accounts (who installed it, when, which scopes, uninstalled or not). Kept in the kernel's
+// log under `_`-prefixed types that never reach the wire.
+//
+// Where HubSpot's documentation stops and the twin decides: an account the World makes has a Hub ID from 146000001 up,
+// a user id from 80000001 and an owner id from 90000001 (HubSpot documents their existence, not their ranges); every
+// user of an account the story names is its super admin or one of its users with the seats the story gives them, and
+// the twin keeps no finer permission than super admin or not.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+
+const SERVICE = 'hubspot';
+export type Row = Record<string, unknown>;
+
+export const hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+
+/** Every live stored subject of a bookkeeping type (these are not scoped to an account: each names its own). */
+export function stored(type: string, root?: string): Row[] {
+  return (projectResources(SERVICE, root) as unknown as Row[]).filter((r) => r.type === type && r.deleted !== true);
+}
+
+/** Write a bookkeeping subject. */
+export async function keep(type: string, id: string, fields: Row, root: string | undefined, at: string, actor = 'hubspot'): Promise<void> {
+  await applyTwinWrite(SERVICE, { operation: `hubspot.${type}`, subjectType: type, subjectId: id, fields, occurredAt: at, actor: { kind: 'human', id: actor } }, root);
+}
+
+// ── accounts and users ─────────────────────────────────────────────────────────────────────
+export const passwordHash = (email: string, password: string): string => hex(`hubspot-password:${email.toLowerCase()}:${password}`);
+
+export function accountOf(hubId: number, root?: string): Row | undefined {
+  return stored('_account', root).find((a) => a.hubId === hubId);
+}
+
+export function personOf(email: string, root?: string): Row | undefined {
+  return stored('_person', root).find((p) => p.email === email.toLowerCase());
+}
+
+export function usersOf(hubId: number, root?: string): Row[] {
+  return stored('_person', root).filter((p) => p.hubId === hubId).sort((a, b) => Number(a.userId) - Number(b.userId));
+}
+
+/** An account's owners, as GET /crm/v3/owners answers them (the spec's PublicOwner): one per user. */
+export function ownersOf(hubId: number, root?: string): Row[] {
+  return usersOf(hubId, root).map((p) => ({
+    id: String(p.ownerId), email: p.email, firstName: p.firstName, lastName: p.lastName, userId: p.userId,
+    userIdIncludingInactive: p.userId, type: 'PERSON', archived: false, teams: [],
+    createdAt: p.created_at, updatedAt: p.created_at,
+  }));
+}
+
+/** POST /_twin/users/:email/password {password, firstName, lastName, account?, subscription?, renewsOn?, hubId?} — stands in for two pages the
+ *  twin does not build: HubSpot's sign-up (a new account, named `account`, whose first user is its super admin) and a
+ *  user's acceptance of an invitation from an account's Users & Teams settings (`hubId`: the user joins that account).
+ *  The World keeps the password's hash, never the password; 201 with the account's Hub ID and the user's ids. */
+export async function signUpDoor(email: string, request: Request, root: string | undefined, at: string): Promise<Response> {
+  let body: Row = {};
+  try { body = JSON.parse(await request.text()) as Row; } catch { /* refused below */ }
+  const password = typeof body.password === 'string' ? body.password : '';
+  const firstName = typeof body.firstName === 'string' ? body.firstName : '';
+  const lastName = typeof body.lastName === 'string' ? body.lastName : '';
+  const refuse = (message: string): Response => Response.json({ status: 'error', message, category: 'VALIDATION_ERROR' }, { status: 400 });
+  if (!/^[^@\s]+@[^@\s]+$/.test(email) || password.length < 8 || !firstName || !lastName) return refuse('an email, a password of at least 8 characters, a firstName and a lastName are required');
+  if (personOf(email, root)) return refuse(`${email} already has a HubSpot login`);
+  let hubId: number;
+  let superAdmin: boolean;
+  if (body.hubId !== undefined) {
+    hubId = Number(body.hubId);
+    const account = accountOf(hubId, root);
+    if (!account || account.closed_at) return refuse(`no open account ${String(body.hubId)}`);
+    superAdmin = body.superAdmin === true;
+  } else {
+    const name = typeof body.account === 'string' ? body.account.trim() : '';
+    if (!name) return refuse('an account name (a new account) or a hubId (an account to join) is required');
+    hubId = 146000000 + stored('_account', root).length + 1;
+    const subscription = typeof body.subscription === 'string' ? body.subscription : 'free';
+    // a paid subscription's commitment term ends on `renewsOn` (a date), when it renews unless its auto-renewal was cancelled
+    const renewsOn = typeof body.renewsOn === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(body.renewsOn) ? body.renewsOn : null;
+    if (subscription !== 'free' && !renewsOn) return refuse('a paid subscription needs the date its commitment term ends (renewsOn)');
+    await keep('_account', `account:${hubId}`, { hubId, name, subscription, renews_on: renewsOn, auto_renew: subscription !== 'free', created_at: at, closed_at: null }, root, at, email);
+    superAdmin = true;
+  }
+  const n = stored('_person', root).length + 1;
+  const person = { email: email.toLowerCase(), hash: passwordHash(email, password), hubId, userId: 80000000 + n, ownerId: String(90000000 + n), firstName, lastName, superAdmin, created_at: at };
+  await keep('_person', `person:${email.toLowerCase()}`, person, root, at, email);
+  return Response.json({ hubId, userId: person.userId, ownerId: person.ownerId }, { status: 201 });
+}
+
+/** The subscription an account has at `at`: a paid one whose auto-renewal was cancelled ends on its renewal date, when
+ *  "your account will be downgraded to HubSpot's free tools"
+ *  (https://knowledge.hubspot.com/account/how-do-i-cancel-my-hubspot-account); one that renews carries on. */
+export function subscriptionAt(account: Row, at: string): string {
+  const paid = String(account.subscription ?? 'free');
+  if (paid === 'free' || account.auto_renew !== false || !account.renews_on) return paid;
+  return Date.parse(at) >= Date.parse(`${String(account.renews_on)}T00:00:00Z`) ? 'free' : paid;
+}
+
+// ── sessions ───────────────────────────────────────────────────────────────────────────────
+export const SESSION_COOKIE = 'hs_session';
+
+/** The person the request's session cookie names, or undefined. */
+export function signedIn(request: Request, root?: string): Row | undefined {
+  const cookie = request.headers.get('cookie') ?? '';
+  const token = new RegExp(`(?:^|;\\s*)${SESSION_COOKIE}=([^;]+)`).exec(cookie)?.[1];
+  const session = token ? stored('_web_session', root).find((s) => s.token === token) : undefined;
+  return session ? personOf(String(session.email), root) : undefined;
+}
+
+// ── apps and installs ──────────────────────────────────────────────────────────────────────
+export function appByClientId(clientId: string, root?: string): Row | undefined {
+  return stored('_app', root).find((a) => a.client_id === clientId && !a.deleted_at);
+}
+export function appById(appId: number, root?: string): Row | undefined {
+  return stored('_app', root).find((a) => a.appId === appId && !a.deleted_at);
+}
+export function appsOf(hubId: number, root?: string): Row[] {
+  return stored('_app', root).filter((a) => a.hubId === hubId && !a.deleted_at);
+}
+/** The live installs in an account. */
+export function installsIn(hubId: number, root?: string): Row[] {
+  return stored('_install', root).filter((i) => i.hubId === hubId && !i.uninstalled_at);
+}
+export function installOf(appId: number, hubId: number, root?: string): Row | undefined {
+  return installsIn(hubId, root).find((i) => i.appId === appId);
+}

package/src/cli.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-hubspot CLI: serve the HubSpot CRM API twin, the CRM mirror UI, or run conformance.
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createHubspotTwinServer } from './hubspot-server.ts';
+import { createHubspotMirrorServer } from './hubspot-mirror-ui.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+
+if (cmd === 'serve') {
+  const s = await createHubspotTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`hubspot twin (CRM v3/v4)${readOnly ? ' [read-only]' : ''} at ${s.url}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'mirror') {
+  const s = await createHubspotMirrorServer({ ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`hubspot mirror UI (CRM) at ${s.url}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  // dev-only; lazy so the bin runs without @volter/world-tooling in the runtime graph
+  const { checkHubspotConformance } = await import('./hubspot-conformance.ts');
+  const report = await checkHubspotConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-hubspot serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}