@volter/twin-hubspot 0.1.0

package/dist/src/hubspot-budget.js

@@ -0,0 +1,176 @@
+// HubSpot's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveHubspotExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger —
+// lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's
+// header for the full rationale AND for the honest list of what the guard does not guarantee (an
+// injected clock or ledger path still defeats it — it guards carelessness, not malice).
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────────────────────
+// A real ~4.5-DAY vendor lockout (Figma, 2026-07-25) happened because raw API calls were made
+// outside the pack's connector — no cache, no batching, no ceiling. Discipline only binds the code
+// that follows it; a BUDGET binds the code that does not.
+//
+// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
+// HubSpot publishes scalar limits, so this models the real thing rather than guessing. From
+// https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines (read
+// 2026-08-31), for a privately distributed app:
+//
+//   • Free / Starter:            100 requests per 10 seconds per app, 250,000 per account per day
+//   • Professional:              190 requests per 10 seconds per app, 625,000 per account per day
+//   • Enterprise:                190 requests per 10 seconds per app, 1,000,000 per day
+//   • With the API Limit Increase add-on: 250 requests per 10 seconds
+//   • Publicly distributed OAuth apps:    110 requests every 10 seconds per installing account
+//                                          (excludes the CRM Search API)
+//
+// and, separately, https://developers.hubspot.com/changelog/crm-search-api-rate-limit-increase
+// (read 2026-08-31): the CRM Search API's burst limit is FIVE REQUESTS PER SECOND.
+//
+// The window is 60 000 ms. HubSpot's own interval is 10 seconds, and matching it exactly would
+// have been tidier — but the kernel's isolation roster refuses any window SHORTER than the
+// fallback's minute (a shorter window at the same ceiling is a silent rate increase), and that
+// gate is not something a pack gets to weaken for cosmetic alignment. So the vendor's figure is
+// converted instead: the TIGHTEST published tier, Free/Starter's 100 requests per 10 seconds for
+// a privately distributed app, is 600 requests a minute.
+//
+// The ceiling is 180 weighted units per minute — 180 ordinary calls a minute, UNDER A THIRD of
+// that 600, because a pack cannot know which subscription the operator's portal is on and must
+// budget for the smallest one. That is more permissive than the kernel's undeclared fallback
+// (30 calls/min) and is therefore licensed ONLY by the documented figure: the hand-written
+// `VENDOR_BURST_ANCHOR` entry for hubspot in `scripts/rate-budget-isolation.test.ts` carries the
+// 600 and its source, and the gate's arithmetic is against that number, not against anything this
+// declaration says about itself.
+//
+// It bounds the average; it does NOT pace (the kernel refuses, it never sleeps — see its header).
+// An intra-second burst can still reach the vendor first; the backstop for that is the cooldown
+// armed from a 429 or an `X-HubSpot-RateLimit-Remaining: 0` / `X-RateLimit-Remaining: 0` signal.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN (documented vs. judged) ─────────────────────────────────────
+// HubSpot counts REQUESTS, so weight 1 is the faithful price and that is what ordinary CRUD gets.
+// Three deliberate exceptions:
+//   • CRM SEARCH costs 3. This one is anchored in a published HubSpot figure, not a judgement:
+//     search has its OWN five-requests-per-second burst limit, roughly a third of the general
+//     allowance, and pricing it at 3 makes the general ceiling bind search at the tighter rate.
+//   • BATCH object calls cost 5. One `POST /crm/v3/objects/{type}/batch/create` mutates up to
+//     100 CRM records — the runaway-loop failure mode here writes real customer data into a real
+//     portal, which is a HUMAN blast radius, not just a throttle. The rule is anchored on the
+//     whole `/batch/` family rather than the write verbs alone, so a 100-record `batch/read` is
+//     priced the same; that is the conservative direction and is deliberate. A judgement call.
+//   • BATCH association writes cost 3, for the same reason at a smaller scale. A judgement call.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'hubspot';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const HUBSPOT_BUDGET_WINDOW_MS = 60_000;
+/**
+ * Weighted units allowed inside one window. 180/60s = 180 ordinary calls a minute — under a THIRD
+ * of HubSpot's tightest published tier converted to a minute (Free/Starter: 100 requests per 10
+ * seconds for a privately distributed app = 600/minute).
+ */
+export const HUBSPOT_BUDGET_CEILING = 180;
+/** Seconds. A `Retry-After` above this means the token is throttled hard — fail loudly, don't sleep. */
+export const HUBSPOT_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for documented vs. judged. */
+export const HUBSPOT_CALL_WEIGHTS = {
+    /** CRM Search — HubSpot's own five-requests-per-second burst limit, ~1/3 the general rate. */
+    search: 3,
+    /** Batch object calls — one WRITE mutates up to 100 real CRM records (a human blast radius),
+     *  and the anchored rule prices the whole `/batch/` family, READS included, deliberately: a
+     *  100-record read is the heaviest single request this API serves and pricing it as a write is
+     *  the conservative direction. Named `batchWrite` for the case that motivated the number. */
+    batchWrite: 5,
+    /** Batch association writes — the same shape at a smaller scale. */
+    batchAssociation: 3,
+    /** Everything else: single-record CRUD, properties, pipelines, owners, association reads. */
+    other: 1,
+};
+/** THE PACK'S DECLARATION — pure data, the only HubSpot-specific thing in the whole budget. */
+export const HUBSPOT_RATE_BUDGET = {
+    windowMs: HUBSPOT_BUDGET_WINDOW_MS,
+    ceiling: HUBSPOT_BUDGET_CEILING,
+    defaultWeight: HUBSPOT_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: HUBSPOT_BUDGET_MAX_RETRY_AFTER_S,
+    rules: [
+        { match: '^POST /crm/v3/objects/[^/]+/search$', weight: HUBSPOT_CALL_WEIGHTS.search },
+        { match: '^POST /crm/v3/objects/[^/]+/batch/', weight: HUBSPOT_CALL_WEIGHTS.batchWrite },
+        { match: '^POST /crm/v4/associations/', weight: HUBSPOT_CALL_WEIGHTS.batchAssociation },
+    ],
+    reason: 'HubSpot documents, for a privately distributed app, 100 requests / 10 seconds on Free and ' +
+        'Starter (250,000 per account per day), 190 / 10 seconds on Professional (625,000/day) and on ' +
+        'Enterprise (1,000,000/day), and 250 / 10 seconds with the API Limit Increase add-on; a ' +
+        'publicly distributed OAuth app gets 110 requests every 10 seconds per installing account ' +
+        '(developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines, read 2026-08-31). ' +
+        'The CRM Search API carries its OWN, tighter burst limit of five requests per second ' +
+        '(developers.hubspot.com/changelog/crm-search-api-rate-limit-increase, read 2026-08-31). ' +
+        'HubSpot\'s own interval is 10 seconds, but the kernel roster refuses a window shorter than ' +
+        'the fallback\'s minute (a shorter window at the same ceiling is a silent rate increase), so ' +
+        'the vendor figure is CONVERTED rather than copied: the tightest published tier, 100 requests ' +
+        'per 10 seconds, is 600 requests a minute. The ceiling of 180 weighted units per 60s is under ' +
+        'a THIRD of that, because a pack cannot know which subscription the operator\'s portal is on ' +
+        'and must budget for the smallest. That IS more permissive than the kernel fallback (30 ' +
+        'calls/min), and is licensed only by the documented 600 — the hand-written VENDOR_BURST_ANCHOR ' +
+        'entry in scripts/rate-budget-isolation.test.ts carries that number and its source. Search costs 3 ' +
+        "(anchored in HubSpot's own 5/second search limit, roughly a third of the general rate); " +
+        'batch object writes cost 5 and batch association writes 3 — judgement calls, not published ' +
+        'costs, because one batch call mutates up to 100 real CRM records. The window bounds the ' +
+        '60-second AVERAGE and does not pace; the 429 / `X-HubSpot-RateLimit-Remaining: 0` cooldown ' +
+        'is the backstop for a sub-second burst.',
+};
+// Declared at module load, so merely importing this module (which `hubspot-connector.ts` does) is
+// enough to arm the real ceiling.
+declareRateBudget(VENDOR, HUBSPOT_RATE_BUDGET);
+/**
+ * Price one call. The key is `"<METHOD> <path>"` (the absolute API path the connector states,
+ * without a host) with the query string split off, so a rule can price by method without the
+ * kernel knowing anything about HubSpot. An unclassified endpoint still costs `defaultWeight` —
+ * nothing is ever free.
+ */
+export function hubspotCallWeight(method, path) {
+    const { bare, query } = splitQuery(path);
+    // UPPER-CASE the method: `fetch` normalizes a known lowercase method before sending, so
+    // `execute('post', …)` really does issue a POST and must be priced as one.
+    return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+/**
+ * `/crm/v3/objects/contacts?limit=1` -> `{ bare: '/crm/v3/objects/contacts', query: { limit: '1' } }`.
+ *
+ * NORMALIZED, because the anchored rules are otherwise trivially evaded: `fetch` upper-cases a
+ * known method before sending, so `execute('post', …)` issues a real WRITE that a `^POST ` rule
+ * would price as a read; and a trailing slash makes a path miss a `$` anchor while HubSpot's own
+ * router treats it as the same endpoint (`/crm/v3/owners` and `/crm/v3/owners/` are both real).
+ * Both are input variations, not attacks, and either one silently voids the "expensive endpoints
+ * are priced up" claim the ceiling rests on.
+ */
+function splitQuery(path) {
+    const at = path.indexOf('?');
+    const query = {};
+    if (at !== -1)
+        for (const [k, v] of new URLSearchParams(path.slice(at + 1)))
+            query[k] = v;
+    const raw = at === -1 ? path : path.slice(0, at);
+    // Collapse a trailing slash, but never turn the root path into the empty string.
+    const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+    return { bare, query };
+}
+/** Where HubSpot's ledger lives. Token-keyed and cwd-independent by default (the limit is per app
+ *  / per private-app token, so a cwd-scoped ledger would hand the same token a fresh allowance in
+ *  every checkout, worktree and CI matrix leg); pass `root` to opt into world-scoped accounting. */
+export function hubspotBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+    // excess-property check only catches object literals) must not redirect this pack's ledger to
+    // another vendor's file.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * HubSpot's budget — the shared kernel guard bound to this vendor's declaration. A real subclass,
+ * not an alias, so `budget instanceof HubspotBudget` in `liveHubspotExecute` means "a budget that
+ * accounts against HUBSPOT's ledger under HUBSPOT's ceiling": another vendor's `RateBudget` (with
+ * its own, possibly larger, ceiling) is NOT assignable there.
+ */
+export class HubspotBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as HubspotBudgetError } from '@volter/world-core';

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

@@ -0,0 +1,3 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const HUBSPOT_CAPABILITIES: CapabilitySpec[];
+export declare function hubspotCapabilities(): Promise<CapabilityReport>;