@volter/twin-hubspot 0.1.0

package/dist/src/hubspot-server.js

@@ -0,0 +1,116 @@
+// HubSpot twin HTTP server — the pack's wire as the derived dispatch over HubSpot's nine published documents
+// (docs/contributing/architecture.md, "Protocol 3"), so an application calling HubSpot with raw fetch (Dub) or an
+// UNMODIFIED `@hubspot/api-client` (pointed here with its own `basePath` option, or routed by the world injector's
+// api.hubapi.com interception) works against it. Writable by default; pass readOnly to reject writes (R4). The CRM API
+// accepts any bearer: a token the install minted is not required there.
+//
+// FETCH-FIRST (runtime contract R12b): the serve path is the plain fetch below, the server one line of Bun.serve around
+// the same closure. The 204-with-no-body case is the kernel adapter's own null-body rule — `handleHubspotTwinRequest`
+// returns `{ status: 204, body: null, headers }`, served as a genuinely empty response carrying those headers.
+import { createDerivedFetch, createTwinFetchFromHandler, serveHttp, statefulTwinManifest, worldNow } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { hubspotHandlers } from "./semantics/crm.js";
+import { handleHubspotTwinRequest, hubspotUnknownRequest, specObjectPath } from "./hubspot-twin.js";
+import { hubspotOAuth, tokenPortal } from "./hubspot-oauth.js";
+import { signUpDoor } from "./accounts.js";
+import { inPortal } from "./portal.js";
+import { deliveriesDoor } from "./webhooks.js";
+import { accountPages } from "./screens/account.js";
+import { crmPages } from "./screens/crm.js";
+import { developerPages, uploadDoor } from "./screens/developer.js";
+import { FORMS_HOST, formPages, formSubmission } from "./screens/forms.js";
+import { signIn } from "./screens/session.js";
+/**
+ * The pack's wire: the twin's discovery door (`GET /twin`) and HubSpot's OAuth consent (app.hubspot.com's
+ * /oauth/authorize, a hosted flow: hubspot-oauth.tsx) in front, then the derived dispatch over the nine documents'
+ * union. A /crm/v3/objects/ path naming its object type in the spelling the spec's paths do not use (`deals` for the
+ * Deals document's `0-3`, `0-1` for `contacts`) is dispatched as the spelling they use (`specObjectPath`). The
+ * operations the twin serves go to their handlers (semantics/crm.ts); every other one, and a path no document has,
+ * is the gap.
+ */
+export function createHubspotTwinFetch(options) {
+    const answer = createTwinFetchFromHandler(handleHubspotTwinRequest, {
+        ...options,
+        manifest: statefulTwinManifest({
+            vendor: 'hubspot',
+            twinOf: 'the HubSpot CRM v3/v4 API and its OAuth v1 token endpoints',
+            stores: 'CRM records (contacts, companies, deals, tickets), their properties and property groups, pipelines and stages, owners, and associations; OAuth codes and tokens',
+        }),
+    });
+    // a read-only twin installs nothing: its token endpoints answer as the request handler answers any write
+    const oauth = async (request) => (options.readOnly ? undefined : await hubspotOAuth(request, options.root, worldNow)) ?? answer(request);
+    const derived = createDerivedFetch({
+        surface: surface,
+        handlers: hubspotHandlers(answer, oauth),
+        gap: (request) => {
+            const url = new URL(request.url);
+            const refused = hubspotUnknownRequest(request.method, url.pathname);
+            return Response.json(refused.body, { status: refused.status, headers: refused.headers });
+        },
+    });
+    return Object.assign(async function hubspotTwinFetch(request) {
+        try {
+            const url = new URL(request.url);
+            const bare = url.pathname.replace(/\/+$/, '') || '/';
+            if (request.method === 'GET' && bare === '/twin')
+                return await answer(request);
+            const root = options.root;
+            const at = worldNow();
+            // the World's doors, on every host (accounts.ts, screens/developer.tsx, webhooks.ts)
+            if (request.method === 'GET' && bare === '/_twin/deliveries')
+                return deliveriesDoor(request, root);
+            if (!options.readOnly && request.method === 'POST') {
+                const user = /^\/_twin\/users\/([^/]+)\/password$/.exec(bare);
+                if (user)
+                    return await signUpDoor(decodeURIComponent(user[1]).toLowerCase(), request, root, at);
+                const project = /^\/_twin\/accounts\/(\d+)\/projects$/.exec(bare);
+                if (project)
+                    return await uploadDoor(Number(project[1]), request, root, at);
+            }
+            // the vendor host a redirected request names (the injector, a hosted World), else its own
+            const host = (request.headers.get('x-volter-twin-original-host') ?? url.host).split(':')[0].toLowerCase();
+            if (host === FORMS_HOST)
+                return (await formSubmission(request, root, at)) ?? notFoundPage();
+            if (host === 'app.hubspot.com') {
+                if (options.readOnly && request.method !== 'GET')
+                    return notFoundPage();
+                if (bare === '/login')
+                    return await signIn(request, root, at);
+                if (bare === '/oauth/authorize')
+                    return (await hubspotOAuth(request, root, worldNow)) ?? notFoundPage();
+                return (await accountPages(request, root, at)) ?? (await developerPages(request, root, at)) ?? (await crmPages(request, root, at)) ?? (await formPages(request, root, at)) ?? notFoundPage();
+            }
+            // the consent on another hubspot.com host a World routes here (hubspotOAuth answers only on HubSpot's app hosts)
+            if (!options.readOnly && bare === '/oauth/authorize') {
+                const consent = await hubspotOAuth(request, root, worldNow);
+                if (consent)
+                    return consent;
+            }
+            const path = specObjectPath(url.pathname);
+            const routed = path === url.pathname ? request : new Request(Object.assign(url, { pathname: path }), request);
+            // the account the bearer acts in (portal.ts): refused if the twin issued it and it no longer works
+            const scope = tokenPortal(request.headers.get('authorization'), root, at);
+            if (scope instanceof Response)
+                return scope;
+            return scope ? await inPortal(scope, () => derived(routed)) : await derived(routed);
+        }
+        catch (error) {
+            // Never let an exception escape the fetch callback (§8): answer with a vendor-shaped 500
+            // so an in-process fidelity test sees a response, not a hang.
+            return new Response(JSON.stringify({ status: 'error', message: `internal twin error: ${String(error)}`, category: 'INTERNAL_ERROR', correlationId: '00000000-0000-0000-0000-000000000000' }), {
+                status: 500, headers: { 'content-type': 'application/json' },
+            });
+        }
+    }, { owners: () => derived.owners() });
+}
+const notFoundPage = () => new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+export async function createHubspotTwinServer(options) {
+    const server = await serveHttp({
+        hostname: '127.0.0.1',
+        port: options.port ?? 0,
+        idleTimeout: 60,
+        fetch: createHubspotTwinFetch(options),
+    });
+    const port = server.port ?? options.port ?? 0;
+    return { port, url: `http://127.0.0.1:${port}`, stop: () => server.stop(true) };
+}

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

@@ -0,0 +1,65 @@
+export type HubspotRequest = {
+    method: string;
+    path: string;
+    body?: string;
+    occurredAt?: string;
+    root?: string;
+    readOnly?: boolean;
+};
+export type HubspotResponse = {
+    status: number;
+    body: unknown;
+    headers?: Record<string, string>;
+};
+export declare const HUBSPOT_RATE_LIMIT_HEADERS: Readonly<Record<string, string>>;
+export declare const OBJECT_TYPES: readonly ["contacts", "companies", "deals", "tickets"];
+export type ObjectType = (typeof OBJECT_TYPES)[number];
+/** Resolve a {objectType} path segment to a modeled object type, or null. */
+export declare function resolveObjectType(raw: string): ObjectType | null;
+/**
+ * The floor this twin mints record ids from — NAMESPACED out of HubSpot's own range.
+ *
+ * HubSpot record ids are opaque numeric strings; the largest this repo has observed in the wild
+ * are ~2.7e10 (`26879063901`-shaped), and contact ids in particular are routinely in the low
+ * thousands. 9e11 is more than an order of magnitude above the largest of those and far below
+ * `Number.MAX_SAFE_INTEGER`, so a locally minted id and a real portal id cannot meet — in EITHER
+ * direction. See header note 3.
+ */
+export declare const HUBSPOT_LOCAL_ID_BASE = 900000000000;
+export declare const SEARCH_FILTER_OPERATORS: readonly ["EQ", "NEQ", "LT", "LTE", "GT", "GTE", "BETWEEN", "IN", "NOT_IN", "HAS_PROPERTY", "NOT_HAS_PROPERTY", "CONTAINS_TOKEN", "NOT_CONTAINS_TOKEN"];
+/** Documented caps. List: 100/page. Search: 200/page, 10 000 total results, 5 filterGroups of
+ *  6 filters (18 filters overall). All from HubSpot's own reference pages, read 2026-08-31. */
+export declare const LIST_LIMIT_MAX = 100;
+export declare const SEARCH_LIMIT_MAX = 200;
+export declare const SEARCH_RESULT_CAP = 10000;
+export declare const SEARCH_MAX_FILTER_GROUPS = 5;
+export declare const SEARCH_MAX_FILTERS_PER_GROUP = 6;
+export declare const SEARCH_MAX_FILTERS_TOTAL = 18;
+/** A DETERMINISTIC correlation id (see note 2 in the header). Shaped like the UUID real
+ *  HubSpot returns, derived from the request + outcome so a replay is byte-identical. */
+export declare function correlationIdFor(seed: string): string;
+export type ErrorContext = {
+    method: string;
+    pathname: string;
+};
+export declare function handleHubspotTwinRequest(req: HubspotRequest): Promise<HubspotResponse>;
+/** What the twin answers a request for no operation it serves (the derived dispatch's gap, hubspot-server.ts): an
+ *  object type HubSpot cannot resolve under /crm/v3/objects/ is refused as the vendor refuses it, a type it has and
+ *  the twin does not model says so (`refuseObjectType`), and anything else is the twin's 404 in HubSpot's error body.
+ *  Where the documentation stops: no page prints HubSpot's answer to an unknown path; the 404 is the twin's. */
+export declare function hubspotUnknownRequest(method: string, pathname: string): HubspotResponse;
+/** A /crm/v3/objects/ path with its object type spelled as the spec's paths spell it; any other path unchanged. */
+export declare function specObjectPath(pathname: string): string;
+export declare const RESOURCE_TYPES: readonly ["crm_object", "property", "property_group", "pipeline", "association", "owner"];
+/**
+ * THE ENDPOINT CENSUS — what this twin CLAIMS to serve, in canonical `{placeholder}` form.
+ *
+ * Hand-authored from the dispatch above, and held to a two-way bijection with
+ * `hubspot-conformance.ts`'s probe table (every claim needs a live probe; every probe needs a
+ * claim), while that file's independent ROUTER_SURFACE closes the third direction — surface the
+ * router SERVES that this list does not name. It exists here, next to the router, so a branch
+ * added without a claim is visible in the same diff.
+ */
+export declare function hubspotTwinSnapshot(): {
+    implementedEndpoints: string[];
+};