@volter/twin-hubspot 0.1.37 → 1.0.0

package/dist/src/index.d.ts

@@ -1,11 +1,5 @@
-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.js';
-export type { HubspotRequest, HubspotResponse, ObjectType } from './hubspot-twin.js';
-export { createHubspotTwinFetch, createHubspotTwinServer, type HubspotTwinFetchOptions } from './hubspot-server.js';
-export { hubspotRequestForAction, liveHubspotExecute, mapCrmObject, mapOwner, pollTimestamp, pullHubspotAll, pullHubspotObjects, pullHubspotOwners, pushPendingHubspotActions, syncHubspotFromReal, } from './hubspot-connector.js';
-export type { HubspotErrorBody, HubspotExecute, LiveHubspotOptions } from './hubspot-connector.js';
-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.js';
-export type { HubspotBudgetErrorKind, HubspotBudgetOptions, HubspotBudgetReservation, HubspotBudgetSnapshot } from './hubspot-budget.js';
-export { MIRROR_SECTIONS, SECTION_COLUMNS, TITLE_PROPERTY, buildHubspotMirrorClient, createHubspotMirrorServer, formatAmount, groupByStage, hubspotMirrorHtml, recordTitle, stageTone, } from './hubspot-mirror-ui.js';
-export type { HubspotRow, MirrorSectionKey, PillTone } from './hubspot-mirror-ui.js';
-import { type TwinPack } from '@volter/world-core';
-export declare const pack: TwinPack;
+import { manifest } from './manifest.js';
+export { createHubspotFetch } from './fetch.js';
+export { createHubspotTwinServer } from './server.js';
+export { manifest };
+export declare const pack: import("@volter/world-core").PackDescriptor;

package/dist/src/index.js

@@ -1,94 +1,10 @@
-// @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.js";
-export { createHubspotTwinFetch, createHubspotTwinServer } from "./hubspot-server.js";
-export { hubspotRequestForAction, liveHubspotExecute, mapCrmObject, mapOwner, pollTimestamp, pullHubspotAll, pullHubspotObjects, pullHubspotOwners, pushPendingHubspotActions, syncHubspotFromReal, } from "./hubspot-connector.js";
-// 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.js";
-export { MIRROR_SECTIONS, SECTION_COLUMNS, TITLE_PROPERTY, buildHubspotMirrorClient, createHubspotMirrorServer, formatAmount, groupByStage, hubspotMirrorHtml, recordTitle, stageTone, } from "./hubspot-mirror-ui.js";
-// Registry descriptor: the pack self-describes so tooling can discover it.
-import { registerPack } from '@volter/world-core';
-import { performHubspotAction, syncHubspotFromRemote } from "./hubspot-connector.js";
-import { HUBSPOT_RATE_BUDGET as RATE_BUDGET } from "./hubspot-budget.js";
-export const pack = {
-    // 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 } from '@volter/world-core';
+import { manifest } from "./manifest.js";
+import surface from './generated/surface.gen.json' with { type: 'json' };
+export { createHubspotFetch } from "./fetch.js";
+export { createHubspotTwinServer } from "./server.js";
+export { manifest };
+export const pack = registerPack(packOf(manifest, surface));

package/dist/src/manifest.js

@@ -1,68 +1,34 @@
 export const manifest = {
-    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/dist/src/semantics/index.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from '@volter/world-core';
+export declare const hubspotSemantics: Record<string, Handler>;

package/dist/src/semantics/index.js

@@ -0,0 +1 @@
+export const hubspotSemantics = {};

package/dist/src/semantics/states.d.ts

@@ -0,0 +1 @@
+export declare const states: {};

package/dist/src/semantics/states.js

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

package/dist/src/server.d.ts

@@ -0,0 +1,7 @@
+import { type PackFetchOptions } from '@volter/world-core';
+export declare function createHubspotTwinServer(options?: PackFetchOptions & {
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;

package/dist/src/server.js

@@ -0,0 +1,7 @@
+// FETCH-FIRST (runtime contract R12b): a fixed file, the kernel's serve seam around the pack's fetch (./fetch.ts).
+import { serveHttp } from '@volter/world-core';
+import { createHubspotFetch } from "./fetch.js";
+export async function createHubspotTwinServer(options = {}) {
+    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/generated/pack-facts.json

@@ -0,0 +1,42 @@
+{
+  "//": "GENERATED by scripts/pack-facts.ts — current pack descriptors and explicit world-runtime server backings; no prior-artifact entries are retained.",
+  "packs": {
+    "hubspot": {
+      "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"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [],
+      "endpointEnvNone": "The optional integrations address HubSpot hosts; no SDK base-URL environment variable is injected.",
+      "serveExport": "createHubspotTwinServer"
+    }
+  },
+  "undeclared": []
+}

package/journeys/coverage.json

@@ -0,0 +1,60 @@
+{
+  "vendor": "hubspot",
+  "missing": 0,
+  "stale": [],
+  "code": {
+    "lines": 49,
+    "run": 47,
+    "recorded": 2,
+    "missing": 0
+  },
+  "state": {
+    "declared": 0,
+    "reached": 0,
+    "recorded": 0,
+    "missing": [],
+    "undeclared": []
+  },
+  "files": [
+    {
+      "file": "semantics/index.ts",
+      "lines": {
+        "found": 2,
+        "hit": 2
+      },
+      "missing": []
+    },
+    {
+      "file": "manifest.ts",
+      "lines": {
+        "found": 26,
+        "hit": 26
+      },
+      "missing": []
+    },
+    {
+      "file": "index.ts",
+      "lines": {
+        "found": 7,
+        "hit": 7
+      },
+      "missing": []
+    },
+    {
+      "file": "server.ts",
+      "lines": {
+        "found": 4,
+        "hit": 2
+      },
+      "missing": []
+    },
+    {
+      "file": "fetch.ts",
+      "lines": {
+        "found": 10,
+        "hit": 10
+      },
+      "missing": []
+    }
+  ]
+}

package/journeys/customer-life.json

@@ -0,0 +1,7 @@
+{
+  "vendor": "hubspot",
+  "host": "api.hubapi.com",
+  "author": "Codex",
+  "about": "Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in.",
+  "steps": []
+}

package/journeys/customer-life.outline.md

@@ -0,0 +1,6 @@
+# HubSpot customer life
+
+Author: `Codex`.
+
+Cal.com’s shipped CRM app is demand; Dub’s additional integration installation is optional. Pinned evidence for both is in `demand.json`.
+Demanded calls are recorded in demand.json and remain unserved in the retained gap. Scope is unchanged pending a separate implementation; supplying credentials is not opt-in.