@volter/twin-hubspot 0.1.37 → 1.0.0

package/src/index.ts

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

package/src/manifest.ts

@@ -1,96 +1,37 @@
-// HubSpot's manifest: the vendor facts its published documents do not carry (docs/contributing/architecture.md,
-// "Protocol 3"). The surface is generated (./generated/surface.gen.json, from ../spec by scripts/derive-pack.ts): the
-// union of nine documents from HubSpot's public spec catalog (the eight CRM documents the pack serves and OAuth v1,
-// ../spec/SOURCE.md), their one OAuth scheme's scope lists made one (../spec/patches.json). The documents name every
-// operation, so an operation's id is HubSpot's own (`post-/crm/v3/properties/{objectType}/batch/create_create`).
-//
-// THE HANDLERS. Every operation the twin serves is a semantics handler (semantics/crm.ts) over the pack's request
-// handler (hubspot-twin.ts), whose store is the vendor's behaviour, or over the OAuth install's token endpoints
-// (hubspot-oauth.tsx). The derived core owns no operation, so no resource is declared here and no state candidate is
-// ruled: the spec's resources (a record, a property, a pipeline and its stages, an owner) are stored by the request
-// handler in its own shape. An operation no handler serves answers the gap (hubspot-server.ts).
-//
-// WHY NO `auth`. HubSpot reads `Authorization: Bearer <access token or static app token>`. A token the twin issued (an
-// install's access token, a static app's token) acts in its account (portal.ts) and is refused once expired, its app
-// uninstalled or its account closed (hubspot-oauth.tsx, tokenPortal); any other bearer acts in the World's own account,
-// as it did before accounts were modelled, and the kernel's `auth` names keys the twin refuses, never the ones it
-// accepts. Where the twin stops: no operation is refused for a scope its token lacks.
-//
-// THE ERROR BODY. `{status: "error", message, correlationId, category}`, HubSpot's documented error envelope
-// (https://developers.hubspot.com/docs/api-reference/error-handling), which the request handler answers with a
-// correlationId derived from the request (so a replay is byte-identical). The template below is the core's, which
-// serves nothing.
-//
-// THE STATE. The request handler's kernel subjects: `crm_object` (a record, keyed `<objectType>_<id>`), `property`,
-// `property_group`, `pipeline` (its stages inside), `owner` (pulled or the seeded portal owner) and `association`;
-// the OAuth install's `oauth_code` and `oauth_token`.
+// Demand is recorded in journeys/demand.json; retained operations still answer the vendor-shaped gap.
 import type { DerivedManifest } from '@volter/world-core';
 
 export const manifest: DerivedManifest = {
-  vendor: 'hubspot',
-  service: 'hubspot',
-  body: {},
-  // the core mints no id (it owns no operation); a record's id is the request handler's
-  ids: { template: '{prefix}_{n}' },
-  time: 'iso',
-  error: { status: 'error', message: '{message}', category: '{code}' },
-  readOnly: { status: 405, message: 'this twin was started read-only; omit readOnly to accept writes', code: 'TWIN_READ_ONLY' },
-  malformedBody: { status: 400, message: 'Invalid input JSON', code: 'VALIDATION_ERROR' },
-  notFound: { status: 404, message: 'resource not found', code: 'OBJECT_NOT_FOUND' },
-  // `{results, paging: {next: {after}}}`, paged by `after` and `limit` (10 by default, 100 at most: the documents'
-  // getPage operations). Required by the type; the core lists nothing.
-  list: { style: 'envelope', envelope: { results: '{data}' }, limit: { param: 'limit', default: 10, max: 100 }, after: 'after' },
-  deleted: {},
-  // HubSpot's pages the life walks (src/screens/, src/hubspot-oauth.tsx), each built from @volter/world-ui's pieces.
-  screens: [
-    {
-      id: 'sign-in', kind: 'flow', host: 'app.hubspot.com', path: '/login',
-      demand: 'every person on a HubSpot page is who signed in there', status: 'done', controls: ['Email address', 'Password', 'Log in'],
-      source: 'https://knowledge.hubspot.com/account-management/log-in-to-hubspot',
-    },
-    {
-      id: 'oauth-consent', kind: 'flow', host: 'app.hubspot.com', path: '/oauth/authorize',
-      demand: "Dub's HubSpot integration sends a workspace owner here to connect a portal (apps/web/lib/integrations/hubspot/oauth.ts, authUrl)",
-      status: 'done', controls: ['Select an account', 'Connect app', 'Cancel', 'Type I accept the risk', 'Connect'],
-      source: 'https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot',
-    },
-    {
-      id: 'app-auth', kind: 'workspace', host: 'app.hubspot.com', path: '/developer-projects/:hubId/project/:name/component/:uid/auth',
-      demand: "an app's client ID and secret are read here", status: 'done',
-      source: 'https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot',
-    },
-    {
-      id: 'app-distribution', kind: 'workspace', host: 'app.hubspot.com', path: '/developer-projects/:hubId/project/:name/component/:uid/distribution',
-      demand: 'an OAuth marketplace app is published (Begin publishing, the AUP) before any install; a static app is installed and its token shown here',
-      status: 'done', controls: ['Begin publishing', 'Sign', 'Install now', 'Show'],
-      source: 'https://developers.hubspot.com/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot',
-    },
-    {
-      id: 'records', kind: 'workspace', host: 'app.hubspot.com', path: '/contacts/:hubId/record/:objectTypeId/:id',
-      demand: "reps create deals on a contact's record and move a deal's stage; account managers add companies", status: 'done',
-      controls: ['Create deal', 'Deal stage', 'Save', 'Create company'], source: 'https://knowledge.hubspot.com/records/create-records-on-the-updated-index-page',
-    },
-    {
-      id: 'pipelines', kind: 'workspace', host: 'app.hubspot.com', path: '/settings/:hubId/objects/deals/pipelines',
-      demand: "a custom pipeline's closed-won stage ID is read here (Dub's guide: \"enter the stage ID corresponding to your custom Closed Won stage\")",
-      status: 'done', source: 'https://knowledge.hubspot.com/object-settings/set-up-and-customize-pipelines',
-    },
-    {
-      id: 'forms', kind: 'workspace', host: 'app.hubspot.com', path: '/forms/:hubId',
-      demand: "Dub's guide: \"In the HubSpot form builder, add a hidden field and map it to the Dub Id contact property\"", status: 'done',
-      controls: ['Create form', 'Add hidden field'], source: 'https://dub.co/docs/integrations/hubspot',
-    },
-    {
-      id: 'connected-apps', kind: 'workspace', host: 'app.hubspot.com', path: '/connected-apps/:hubId/installed',
-      demand: 'a client uninstalls the app it connected', status: 'done', controls: ['Uninstall', 'Type uninstall'],
-      source: 'https://knowledge.hubspot.com/marketplace/install-apps-in-the-hubspot-marketplace',
-    },
-    {
-      id: 'account-and-billing', kind: 'workspace', host: 'app.hubspot.com', path: '/account-and-billing/:hubId/subscriptions',
-      demand: "a company leaving HubSpot cancels its subscription's auto-renewal, then deletes the account once the subscription has ended",
-      status: 'done', controls: ['Cancel auto-renewal', 'Next', 'Delete account', 'Enter your Hub ID to confirm', 'Yes, delete'],
-      source: 'https://knowledge.hubspot.com/account/how-do-i-cancel-my-hubspot-account',
-    },
-  ],
-  resources: {},
+  vendor: 'hubspot', service: 'hubspot', body: { json: 'always', form: { coerce: false } },
+  ids: { template: '{n}' }, time: 'iso',
+  // source: https://developers.hubspot.com/docs/api-reference/error-handling "return a JSON formatted response with details about the error"
+  error: { status: 'error', message: '{message}', correlationId: '{id}' },
+  readOnly: { status: 403, message: 'This World is read-only.' },
+  // source: https://developers.hubspot.com/docs/api-reference/webhooks-webhooks-v3/guide "404 Not Found : requested resource not found"
+  // The documentation gives the not-found class, not words for every unknown path; use that class in its documented JSON envelope.
+  notFound: { status: 404, message: 'requested resource not found' },
+  gap: { status: 404, message: 'requested resource not found' },
+  // source: https://developers.hubspot.com/docs/api-reference/webhooks-webhooks-v3/guide "Authorization : Bearer YOUR_ACCESS_TOKEN"
+  // source: https://developers.hubspot.com/docs/api-reference/error-handling "Returned when the authentication provided is invalid."
+  // Where documentation stops: The 401 rule describes invalid authentication, not missing-key versus unknown-route precedence; the gap stands.
+  auth: { header: 'authorization', scheme: 'Bearer', paths: '^/crm/', gateWhenAbsent: true,
+    missing: { status: 401, message: 'Unauthorized' }, invalid: { status: 401, message: 'Unauthorized' }, invalidKeys: ['invalid'] },
+  deleted: {}, resources: {},
+  unmodeled: ["get-/crm/v3/objects/0-3_getPage", "post-/crm/v3/objects/0-3_create", "get-/crm/v3/objects/0-3/{dealId}_getById", "patch-/crm/v3/objects/0-3/{dealId}_update", "delete-/crm/v3/objects/0-3/{dealId}_archive", "post-/crm/v3/objects/0-3/batch/archive_archive", "post-/crm/v3/objects/0-3/batch/create_create", "post-/crm/v3/objects/0-3/batch/read_read", "post-/crm/v3/objects/0-3/batch/update_update", "post-/crm/v3/objects/0-3/batch/upsert_upsert", "post-/crm/v3/objects/0-3/merge_merge", "post-/crm/v3/objects/0-3/search_doSearch", "get-/crm/v3/objects/companies_getPage", "post-/crm/v3/objects/companies_create", "get-/crm/v3/objects/companies/{companyId}_getById", "patch-/crm/v3/objects/companies/{companyId}_update", "delete-/crm/v3/objects/companies/{companyId}_archive", "post-/crm/v3/objects/companies/batch/archive_archive", "post-/crm/v3/objects/companies/batch/create_create", "post-/crm/v3/objects/companies/batch/read_read", "post-/crm/v3/objects/companies/batch/update_update", "post-/crm/v3/objects/companies/batch/upsert_upsert", "post-/crm/v3/objects/companies/merge_merge", "post-/crm/v3/objects/companies/search_doSearch", "get-/crm/v3/objects/contacts_getPage", "post-/crm/v3/objects/contacts_create", "get-/crm/v3/objects/contacts/{contactId}_getById", "patch-/crm/v3/objects/contacts/{contactId}_update", "delete-/crm/v3/objects/contacts/{contactId}_archive", "post-/crm/v3/objects/contacts/batch/archive_archive", "post-/crm/v3/objects/contacts/batch/create_create", "post-/crm/v3/objects/contacts/batch/read_read", "post-/crm/v3/objects/contacts/batch/update_update", "post-/crm/v3/objects/contacts/batch/upsert_upsert", "post-/crm/v3/objects/contacts/gdpr-delete_purge", "post-/crm/v3/objects/contacts/merge_merge", "post-/crm/v3/objects/contacts/search_doSearch", "get-/crm/v3/objects/meetings_getPage", "post-/crm/v3/objects/meetings_create", "get-/crm/v3/objects/meetings/{meetingId}_getById", "patch-/crm/v3/objects/meetings/{meetingId}_update", "delete-/crm/v3/objects/meetings/{meetingId}_archive", "post-/crm/v3/objects/meetings/batch/archive_archive", "post-/crm/v3/objects/meetings/batch/create_create", "post-/crm/v3/objects/meetings/batch/read_read", "post-/crm/v3/objects/meetings/batch/update_update", "post-/crm/v3/objects/meetings/batch/upsert_upsert", "post-/crm/v3/objects/meetings/search_doSearch", "get-/crm/v3/objects/tickets_getPage", "post-/crm/v3/objects/tickets_create", "get-/crm/v3/objects/tickets/{ticketId}_getById", "patch-/crm/v3/objects/tickets/{ticketId}_update", "delete-/crm/v3/objects/tickets/{ticketId}_archive", "post-/crm/v3/objects/tickets/batch/archive_archive", "post-/crm/v3/objects/tickets/batch/create_create", "post-/crm/v3/objects/tickets/batch/read_read", "post-/crm/v3/objects/tickets/batch/update_update", "post-/crm/v3/objects/tickets/batch/upsert_upsert", "post-/crm/v3/objects/tickets/merge_merge", "post-/crm/v3/objects/tickets/search_doSearch", "get-/crm/v3/owners_/crm/v3/owners", "get-/crm/v3/owners/{ownerId}_getById", "get-/crm/v3/pipelines/{objectType}_getAll", "post-/crm/v3/pipelines/{objectType}_create", "get-/crm/v3/pipelines/{objectType}/{pipelineId}_getById", "put-/crm/v3/pipelines/{objectType}/{pipelineId}_replace", "patch-/crm/v3/pipelines/{objectType}/{pipelineId}_update", "delete-/crm/v3/pipelines/{objectType}/{pipelineId}_archive", "get-/crm/v3/pipelines/{objectType}/{pipelineId}/audit_getAudit", "get-/crm/v3/pipelines/{objectType}/{pipelineId}/stages_getAll", "post-/crm/v3/pipelines/{objectType}/{pipelineId}/stages_create", "get-/crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}_getById", "put-/crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}_replace", "patch-/crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}_update", "delete-/crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}_archive", "get-/crm/v3/pipelines/{objectType}/{pipelineId}/stages/{stageId}/audit_getAudit", "get-/crm/v3/properties/{objectType}_getAll", "post-/crm/v3/properties/{objectType}_create", "get-/crm/v3/properties/{objectType}/{propertyName}_getByName", "patch-/crm/v3/properties/{objectType}/{propertyName}_update", "delete-/crm/v3/properties/{objectType}/{propertyName}_archive", "post-/crm/v3/properties/{objectType}/batch/archive_archive", "post-/crm/v3/properties/{objectType}/batch/create_create", "post-/crm/v3/properties/{objectType}/batch/read_read", "get-/crm/v3/properties/{objectType}/groups_getAll", "post-/crm/v3/properties/{objectType}/groups_create", "get-/crm/v3/properties/{objectType}/groups/{groupName}_getByName", "patch-/crm/v3/properties/{objectType}/groups/{groupName}_update", "delete-/crm/v3/properties/{objectType}/groups/{groupName}_archive", "post-/crm/v4/associations/{fromObjectType}/{toObjectType}/batch/archive_archive", "post-/crm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/default_createDefault", "post-/crm/v4/associations/{fromObjectType}/{toObjectType}/batch/create_create", "post-/crm/v4/associations/{fromObjectType}/{toObjectType}/batch/labels/archive_archiveLabels", "post-/crm/v4/associations/{fromObjectType}/{toObjectType}/batch/read_getPage", "post-/crm/v4/associations/usage/high-usage-report/{userId}_request", "put-/crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}_createDefault", "get-/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}_getPage", "put-/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}_create", "delete-/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}_archive", "get-/oauth/v1/access-tokens/{token}_get", "get-/oauth/v1/refresh-tokens/{token}_get", "delete-/oauth/v1/refresh-tokens/{token}_archive", "post-/oauth/v1/token_create"],
+  vendorBacked: { none: 'No vendor resource or operation is served; every spec operation answers the gap.' },
+  // source: https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines "110 requests every 10 seconds"
+  rateBudget: { windowMs: 60000, ceiling: 660, defaultWeight: 1, maxRetryAfterSeconds: 60, reason: 'Public OAuth allowance of 110 requests per 10 seconds, expressed as 660 per minute.',
+    allowance: { perMinute: 660, source: 'https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines' } },
+  discovery: { twinOf: 'HubSpot CRM, Meetings and OAuth v1 APIs', stores: 'No vendor resources',
+    behavior: 'Every spec operation answers the vendor-shaped gap; Cal.com and Dub require an optional HubSpot app installation.' },
+  descriptor: {
+    protocol: '3', transport: 'rest', archetype: 'crud', bin: 'world-hubspot', resources: [],
+    specSource: 'HubSpot CRM, Meetings and OAuth v1 OpenAPI documents; provenance in spec/SOURCE.md',
+    description: 'HubSpot API twin: every spec operation answers the vendor-shaped gap.',
+    adoption: { sdks: ['@hubspot/api-client'], pypi: ['hubspot-api-client'], envStems: ['HUBSPOT', 'HUBSPOTPRIVATEAPP'] },
+    hosts: [{ host: 'api.hubapi.com' }, { host: 'app.hubspot.com', demandPathPattern: false }, { host: 'api.hsforms.com' }],
+    endpointEnvNone: 'The optional integrations address HubSpot hosts; no SDK base-URL environment variable is injected.',
+    // source: https://raw.githubusercontent.com/dubinc/dub/7e0101363b2ab30afc537c1893f159d1dcba513a/apps/web/lib/integrations/hubspot/oauth.ts "process.env.HUBSPOT_CLIENT_ID"
+    clientCasesNone: 'Optional integration calls remain unserved; no SDK case is claimed for the retained gap.',
+  },
 };

package/src/semantics/index.ts

@@ -0,0 +1,6 @@
+// GENERATED by scripts/create-pack.ts --index: the handler map, by operationId, from the families' files (each
+// handler named as its operation). Do not edit; add a handler to its family's file and generate again.
+import type { Handler } from '@volter/world-core';
+
+export const hubspotSemantics: Record<string, Handler> = {
+};

package/src/semantics/states.ts

@@ -0,0 +1,2 @@
+// No vendor resources are served, so there are no state machines or notState rulings.
+export const states = {};

package/src/server.ts

@@ -0,0 +1,8 @@
+// FETCH-FIRST (runtime contract R12b): a fixed file, the kernel's serve seam around the pack's fetch (./fetch.ts).
+import { serveHttp, type PackFetchOptions } from '@volter/world-core';
+import { createHubspotFetch } from './fetch.ts';
+
+export async function createHubspotTwinServer(options: PackFetchOptions & { port?: number } = {}): Promise<{ port: number; stop: () => void }> {
+  const server = await serveHttp({ port: options.port ?? 0, idleTimeout: 60, fetch: createHubspotFetch(options) });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}

package/client/hubspot-mirror.css

@@ -1,43 +0,0 @@
-: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/client/hubspot-mirror.tsx

@@ -1,132 +0,0 @@
-// 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 />);