@volter/twin-hubspot 0.1.0

package/dist/client/hubspot-mirror.css

@@ -0,0 +1,43 @@
+:root {
+  --bg: #f5f8fa;
+  --panel: #ffffff;
+  --line: #dfe3eb;
+  --text: #33475b;
+  --muted: #7c98b6;
+  --accent: #eaf0f6;
+  --brand: #ff7a59;
+  --ok: #00bda5;
+  --warn: #f5c26b;
+  --bad: #f2545b;
+}
+* { box-sizing: border-box; }
+body { margin: 0; font-family: -apple-system, system-ui, "Helvetica Neue", sans-serif; background: var(--bg); color: var(--text); }
+.app { display: grid; grid-template-columns: 220px 1fr; grid-template-rows: 56px 1fr; min-height: 100vh; }
+.topbar { grid-column: 1 / 3; display: flex; align-items: center; justify-content: space-between; padding: 0 20px; border-bottom: 1px solid var(--line); background: var(--panel); }
+.brand { font-weight: 700; color: var(--brand); letter-spacing: 0.2px; }
+.view-toggle { border: 1px solid var(--line); background: var(--panel); color: var(--text); border-radius: 4px; padding: 6px 14px; cursor: pointer; font-size: 13px; }
+.view-toggle:hover { background: var(--accent); }
+.sidebar { border-right: 1px solid var(--line); padding: 14px 10px; background: var(--panel); }
+.nav-item { display: block; width: 100%; text-align: left; background: none; border: none; color: var(--muted); padding: 9px 12px; border-radius: 4px; cursor: pointer; font-size: 14px; }
+.nav-item.active, .nav-item:hover { background: var(--accent); color: var(--text); }
+.content { padding: 24px; overflow: auto; }
+table { width: 100%; border-collapse: collapse; background: var(--panel); border: 1px solid var(--line); border-radius: 6px; }
+th { text-align: left; color: var(--muted); font-size: 11px; text-transform: uppercase; letter-spacing: 0.4px; padding: 10px 12px; border-bottom: 1px solid var(--line); }
+td { padding: 12px; border-bottom: 1px solid var(--line); font-size: 14px; }
+tr:last-child td { border-bottom: none; }
+.cell-title { font-weight: 600; }
+.cell-id { color: var(--muted); font-variant-numeric: tabular-nums; }
+.cell-prop-name { color: var(--muted); font-size: 12px; width: 40%; }
+.pill { display: inline-block; padding: 3px 10px; border-radius: 999px; font-size: 12px; background: var(--accent); }
+.pill-ok { background: rgba(0, 189, 165, 0.16); color: var(--ok); }
+.pill-warn { background: rgba(245, 194, 107, 0.22); color: #b07d1a; }
+.pill-bad { background: rgba(242, 84, 91, 0.16); color: var(--bad); }
+.empty { color: var(--muted); padding: 28px; background: var(--panel); border: 1px dashed var(--line); border-radius: 6px; }
+.deal-board { display: flex; gap: 14px; align-items: flex-start; overflow-x: auto; padding-bottom: 8px; }
+.board-column { min-width: 220px; background: var(--panel); border: 1px solid var(--line); border-radius: 6px; padding: 12px; }
+.board-column-head { display: flex; align-items: center; justify-content: space-between; margin-bottom: 10px; }
+.board-count { color: var(--muted); font-size: 12px; }
+.deal-card { border: 1px solid var(--line); border-radius: 4px; padding: 10px; margin-bottom: 8px; }
+.deal-amount { color: var(--muted); font-size: 13px; margin-top: 4px; }
+.record-detail { background: var(--panel); border: 1px solid var(--line); border-radius: 6px; padding: 20px; }
+.detail-title { margin: 0 0 14px; font-size: 20px; }

package/dist/client/hubspot-mirror.d.ts

@@ -0,0 +1,15 @@
+import { type HubspotRow, type MirrorSectionKey } from '../src/hubspot-mirror-ui.js';
+/** A CRM record list — one `list-row` landmark per record, carrying its HubSpot record id. */
+export declare function RecordsTable({ section, rows }: {
+    section: MirrorSectionKey;
+    rows: HubspotRow[];
+}): import("react").JSX.Element;
+/** The deal pipeline board — the screen a sales rep actually works in, one column per stage. */
+export declare function DealBoard({ rows }: {
+    rows: HubspotRow[];
+}): import("react").JSX.Element;
+/** Record detail — the property sheet HubSpot shows on the right of a record. */
+export declare function RecordDetail({ section, rows }: {
+    section: MirrorSectionKey;
+    rows: HubspotRow[];
+}): import("react").JSX.Element;

package/dist/client/hubspot-mirror.js

@@ -0,0 +1,59 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+// HubSpot mirror — React/TSX CRM client. Renders the twin's contacts, companies, deals and
+// tickets by fetching the twin's OWN CRM REST API on the same origin
+// (`/crm/v3/objects/contacts`, …) — HubSpot's real paths, the same ones the SDK calls.
+// API↔UI parity: the screen shows real twin state, not a hardcoded shell.
+import { createRoot } from 'react-dom/client';
+import { useEffect, useState } from 'react';
+import { MIRROR_SECTIONS, SECTION_COLUMNS, formatAmount, groupByStage, recordTitle, stageTone, } from "../src/hubspot-mirror-ui.js";
+// WHERE THIS MIRROR LIVES. Served at a vendor root the base is '' (fetches are root-relative, as
+// before); served under a path prefix with a <base> tag every read and write resolves inside that
+// prefix instead of escaping it.
+const WIRE_BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
+// Map a tone to a STATIC literal class name (a template-literal class is erased by the
+// minifier, so `pill-${tone}` would vanish from the bundle — assert these instead).
+const PILL_CLASS = { ok: 'pill pill-ok', warn: 'pill pill-warn', bad: 'pill pill-bad', '': 'pill' };
+/** Unwrap HubSpot's collection envelope (`{ results, paging }`) to its results array. */
+async function fetchRows(path) {
+    const res = await fetch(`${WIRE_BASE}${path}`);
+    const body = (await res.json());
+    return Array.isArray(body.results) ? body.results : [];
+}
+/** A CRM record list — one `list-row` landmark per record, carrying its HubSpot record id. */
+export function RecordsTable({ section, rows }) {
+    if (rows.length === 0)
+        return _jsxs("div", { className: "empty", children: ["No ", section, " yet."] });
+    const columns = SECTION_COLUMNS[section];
+    return (_jsxs("table", { className: "records-table", children: [_jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { children: "Name" }), columns.map((c) => _jsx("th", { children: c.label }, c.prop)), _jsx("th", { children: "Record ID" })] }) }), _jsx("tbody", { children: rows.map((r) => (_jsxs("tr", { className: "list-row", "data-record-id": r.id, children: [_jsx("td", { className: "cell-title", children: recordTitle(section, r.properties) }), columns.map((c) => (_jsx("td", { className: "cell-prop", children: c.prop === 'amount' ? formatAmount(r.properties?.amount)
+                                : c.prop === 'dealstage'
+                                    ? _jsx("span", { className: PILL_CLASS[stageTone(r.properties?.dealstage)], children: r.properties?.dealstage ?? '—' })
+                                    : (r.properties?.[c.prop] ?? '—') }, c.prop))), _jsx("td", { className: "cell-id", children: r.id })] }, r.id))) })] }));
+}
+/** The deal pipeline board — the screen a sales rep actually works in, one column per stage. */
+export function DealBoard({ rows }) {
+    const groups = groupByStage(rows);
+    if (groups.length === 0)
+        return _jsx("div", { className: "empty", children: "No deals yet." });
+    return (_jsx("div", { className: "deal-board", children: groups.map((g) => (_jsxs("section", { className: "board-column", "data-stage": g.stage, children: [_jsxs("header", { className: "board-column-head", children: [_jsx("span", { className: PILL_CLASS[stageTone(g.stage)], children: g.stage }), _jsx("span", { className: "board-count", children: g.rows.length })] }), g.rows.map((r) => (_jsxs("article", { className: "deal-card list-row", "data-record-id": r.id, children: [_jsx("div", { className: "cell-title", children: recordTitle('deals', r.properties) }), _jsx("div", { className: "deal-amount", children: formatAmount(r.properties?.amount) })] }, r.id)))] }, g.stage))) }));
+}
+/** Record detail — the property sheet HubSpot shows on the right of a record. */
+export function RecordDetail({ section, rows }) {
+    const r = rows[0];
+    if (!r)
+        return _jsx("div", { className: "empty", children: "No record." });
+    const entries = Object.entries(r.properties ?? {});
+    return (_jsxs("section", { className: "record-detail", "data-record-id": r.id, children: [_jsx("h2", { className: "detail-title", children: recordTitle(section, r.properties) }), _jsx("table", { className: "property-table", children: _jsx("tbody", { children: entries.map(([k, v]) => (_jsxs("tr", { className: "list-row", "data-prop": k, children: [_jsx("td", { className: "cell-prop-name", children: k }), _jsx("td", { className: "cell-prop-value", children: v ?? '—' })] }, k))) }) })] }));
+}
+function App() {
+    const [section, setSection] = useState('contacts');
+    const [board, setBoard] = useState(false);
+    const [rows, setRows] = useState([]);
+    useEffect(() => {
+        const sec = MIRROR_SECTIONS.find((s) => s.key === section);
+        fetchRows(sec.path).then(setRows).catch(() => setRows([]));
+    }, [section]);
+    return (_jsxs("div", { className: "app", children: [_jsxs("header", { className: "topbar", children: [_jsx("span", { className: "brand", children: "HubSpot twin" }), section === 'deals' ? (_jsx("button", { className: "view-toggle", onClick: () => setBoard((b) => !b), children: board ? 'Table' : 'Board' })) : null] }), _jsx("nav", { className: "sidebar", children: MIRROR_SECTIONS.map((s) => (_jsx("button", { className: `nav-item${s.key === section ? ' active' : ''}`, onClick: () => { setSection(s.key); setBoard(false); }, children: s.label }, s.key))) }), _jsx("main", { className: "content", children: section === 'deals' && board ? _jsx(DealBoard, { rows: rows }) : _jsx(RecordsTable, { section: section, rows: rows }) })] }));
+}
+const el = typeof document !== 'undefined' ? document.getElementById('root') : null;
+if (el)
+    createRoot(el).render(_jsx(App, {}));

package/dist/client/hubspot-mirror.tsx

@@ -0,0 +1,132 @@
+// HubSpot mirror — React/TSX CRM client. Renders the twin's contacts, companies, deals and
+// tickets by fetching the twin's OWN CRM REST API on the same origin
+// (`/crm/v3/objects/contacts`, …) — HubSpot's real paths, the same ones the SDK calls.
+// API↔UI parity: the screen shows real twin state, not a hardcoded shell.
+import { createRoot } from 'react-dom/client';
+import { useEffect, useState } from 'react';
+import {
+  MIRROR_SECTIONS, SECTION_COLUMNS, formatAmount, groupByStage, recordTitle, stageTone,
+  type HubspotRow, type MirrorSectionKey, type PillTone,
+} from '../src/hubspot-mirror-ui.ts';
+
+// WHERE THIS MIRROR LIVES. Served at a vendor root the base is '' (fetches are root-relative, as
+// before); served under a path prefix with a <base> tag every read and write resolves inside that
+// prefix instead of escaping it.
+const WIRE_BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
+
+// Map a tone to a STATIC literal class name (a template-literal class is erased by the
+// minifier, so `pill-${tone}` would vanish from the bundle — assert these instead).
+const PILL_CLASS: Record<PillTone, string> = { ok: 'pill pill-ok', warn: 'pill pill-warn', bad: 'pill pill-bad', '': 'pill' };
+
+/** Unwrap HubSpot's collection envelope (`{ results, paging }`) to its results array. */
+async function fetchRows(path: string): Promise<HubspotRow[]> {
+  const res = await fetch(`${WIRE_BASE}${path}`);
+  const body = (await res.json()) as { results?: unknown };
+  return Array.isArray(body.results) ? (body.results as HubspotRow[]) : [];
+}
+
+/** A CRM record list — one `list-row` landmark per record, carrying its HubSpot record id. */
+export function RecordsTable({ section, rows }: { section: MirrorSectionKey; rows: HubspotRow[] }) {
+  if (rows.length === 0) return <div className="empty">No {section} yet.</div>;
+  const columns = SECTION_COLUMNS[section];
+  return (
+    <table className="records-table">
+      <thead>
+        <tr><th>Name</th>{columns.map((c) => <th key={c.prop}>{c.label}</th>)}<th>Record ID</th></tr>
+      </thead>
+      <tbody>
+        {rows.map((r) => (
+          <tr className="list-row" data-record-id={r.id} key={r.id}>
+            <td className="cell-title">{recordTitle(section, r.properties)}</td>
+            {columns.map((c) => (
+              <td className="cell-prop" key={c.prop}>
+                {c.prop === 'amount' ? formatAmount(r.properties?.amount)
+                  : c.prop === 'dealstage'
+                    ? <span className={PILL_CLASS[stageTone(r.properties?.dealstage)]}>{r.properties?.dealstage ?? '—'}</span>
+                    : (r.properties?.[c.prop] ?? '—')}
+              </td>
+            ))}
+            <td className="cell-id">{r.id}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+/** The deal pipeline board — the screen a sales rep actually works in, one column per stage. */
+export function DealBoard({ rows }: { rows: HubspotRow[] }) {
+  const groups = groupByStage(rows);
+  if (groups.length === 0) return <div className="empty">No deals yet.</div>;
+  return (
+    <div className="deal-board">
+      {groups.map((g) => (
+        <section className="board-column" data-stage={g.stage} key={g.stage}>
+          <header className="board-column-head">
+            <span className={PILL_CLASS[stageTone(g.stage)]}>{g.stage}</span>
+            <span className="board-count">{g.rows.length}</span>
+          </header>
+          {g.rows.map((r) => (
+            <article className="deal-card list-row" data-record-id={r.id} key={r.id}>
+              <div className="cell-title">{recordTitle('deals', r.properties)}</div>
+              <div className="deal-amount">{formatAmount(r.properties?.amount)}</div>
+            </article>
+          ))}
+        </section>
+      ))}
+    </div>
+  );
+}
+
+/** Record detail — the property sheet HubSpot shows on the right of a record. */
+export function RecordDetail({ section, rows }: { section: MirrorSectionKey; rows: HubspotRow[] }) {
+  const r = rows[0];
+  if (!r) return <div className="empty">No record.</div>;
+  const entries = Object.entries(r.properties ?? {});
+  return (
+    <section className="record-detail" data-record-id={r.id}>
+      <h2 className="detail-title">{recordTitle(section, r.properties)}</h2>
+      <table className="property-table">
+        <tbody>
+          {entries.map(([k, v]) => (
+            <tr className="list-row" data-prop={k} key={k}>
+              <td className="cell-prop-name">{k}</td>
+              <td className="cell-prop-value">{v ?? '—'}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+}
+
+function App() {
+  const [section, setSection] = useState<MirrorSectionKey>('contacts');
+  const [board, setBoard] = useState(false);
+  const [rows, setRows] = useState<HubspotRow[]>([]);
+  useEffect(() => {
+    const sec = MIRROR_SECTIONS.find((s) => s.key === section)!;
+    fetchRows(sec.path).then(setRows).catch(() => setRows([]));
+  }, [section]);
+  return (
+    <div className="app">
+      <header className="topbar">
+        <span className="brand">HubSpot twin</span>
+        {section === 'deals' ? (
+          <button className="view-toggle" onClick={() => setBoard((b) => !b)}>{board ? 'Table' : 'Board'}</button>
+        ) : null}
+      </header>
+      <nav className="sidebar">
+        {MIRROR_SECTIONS.map((s) => (
+          <button key={s.key} className={`nav-item${s.key === section ? ' active' : ''}`} onClick={() => { setSection(s.key); setBoard(false); }}>{s.label}</button>
+        ))}
+      </nav>
+      <main className="content">
+        {section === 'deals' && board ? <DealBoard rows={rows} /> : <RecordsTable section={section} rows={rows} />}
+      </main>
+    </div>
+  );
+}
+
+const el = typeof document !== 'undefined' ? document.getElementById('root') : null;
+if (el) createRoot(el).render(<App />);

package/dist/src/accounts.d.ts

@@ -0,0 +1,30 @@
+export type Row = Record<string, unknown>;
+export declare const hex: (s: string) => string;
+/** Every live stored subject of a bookkeeping type (these are not scoped to an account: each names its own). */
+export declare function stored(type: string, root?: string): Row[];
+/** Write a bookkeeping subject. */
+export declare function keep(type: string, id: string, fields: Row, root: string | undefined, at: string, actor?: string): Promise<void>;
+export declare const passwordHash: (email: string, password: string) => string;
+export declare function accountOf(hubId: number, root?: string): Row | undefined;
+export declare function personOf(email: string, root?: string): Row | undefined;
+export declare function usersOf(hubId: number, root?: string): Row[];
+/** An account's owners, as GET /crm/v3/owners answers them (the spec's PublicOwner): one per user. */
+export declare function ownersOf(hubId: number, root?: string): Row[];
+/** 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 declare function signUpDoor(email: string, request: Request, root: string | undefined, at: string): Promise<Response>;
+/** 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 declare function subscriptionAt(account: Row, at: string): string;
+export declare const SESSION_COOKIE = "hs_session";
+/** The person the request's session cookie names, or undefined. */
+export declare function signedIn(request: Request, root?: string): Row | undefined;
+export declare function appByClientId(clientId: string, root?: string): Row | undefined;
+export declare function appById(appId: number, root?: string): Row | undefined;
+export declare function appsOf(hubId: number, root?: string): Row[];
+/** The live installs in an account. */
+export declare function installsIn(hubId: number, root?: string): Row[];
+export declare function installOf(appId: number, hubId: number, root?: string): Row | undefined;

package/dist/src/accounts.js

@@ -0,0 +1,122 @@
+// 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 const hex = (s) => 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, root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === type && r.deleted !== true);
+}
+/** Write a bookkeeping subject. */
+export async function keep(type, id, fields, root, at, actor = 'hubspot') {
+    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, password) => hex(`hubspot-password:${email.toLowerCase()}:${password}`);
+export function accountOf(hubId, root) {
+    return stored('_account', root).find((a) => a.hubId === hubId);
+}
+export function personOf(email, root) {
+    return stored('_person', root).find((p) => p.email === email.toLowerCase());
+}
+export function usersOf(hubId, root) {
+    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, root) {
+    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, request, root, at) {
+    let body = {};
+    try {
+        body = JSON.parse(await request.text());
+    }
+    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) => 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;
+    let superAdmin;
+    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, at) {
+    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, root) {
+    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, root) {
+    return stored('_app', root).find((a) => a.client_id === clientId && !a.deleted_at);
+}
+export function appById(appId, root) {
+    return stored('_app', root).find((a) => a.appId === appId && !a.deleted_at);
+}
+export function appsOf(hubId, root) {
+    return stored('_app', root).filter((a) => a.hubId === hubId && !a.deleted_at);
+}
+/** The live installs in an account. */
+export function installsIn(hubId, root) {
+    return stored('_install', root).filter((i) => i.hubId === hubId && !i.uninstalled_at);
+}
+export function installOf(appId, hubId, root) {
+    return installsIn(hubId, root).find((i) => i.appId === appId);
+}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,31 @@
+#!/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.js";
+import { createHubspotMirrorServer } from "./hubspot-mirror-ui.js";
+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.js");
+    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');
+}