@firedrill-tools/hubspot 0.1.1

package/firedrill/tools/hubspot/lib/search.mjs

@@ -0,0 +1,301 @@
+// CRM search semantics: filterGroups (OR of ANDs), free-text query and sorting. Pure functions over record property
+// maps and property definitions. Matching is linear in the property values and every request carries a work budget.
+import { clip, parseMillis } from "./state.mjs";
+import { charge, globMatcher, lowerBound } from "./search-matchers.mjs";
+
+export { MAX_MATCH_WORK, createWorkBudget } from "./search-matchers.mjs";
+
+export const OPERATORS = Object.freeze([
+  "EQ",
+  "NEQ",
+  "LT",
+  "LTE",
+  "GT",
+  "GTE",
+  "BETWEEN",
+  "IN",
+  "NOT_IN",
+  "HAS_PROPERTY",
+  "NOT_HAS_PROPERTY",
+  "CONTAINS_TOKEN",
+  "NOT_CONTAINS_TOKEN",
+]);
+
+export const MAX_FILTER_GROUPS = 5;
+export const MAX_FILTERS_PER_GROUP = 6;
+export const MAX_FILTERS_TOTAL = 18;
+
+/** HubSpot caps a search `query` at 3,000 characters; filter values use the same bound. */
+export const MAX_SEARCH_TEXT = 3000;
+
+const TOKEN_SEPARATOR = /[^\p{L}\p{N}@._+-]+/u;
+
+function isDateType(definition) {
+  return definition.type === "datetime" || definition.type === "date";
+}
+
+/** Comparable form of a raw value (number, epoch ms or lower-cased string); undefined when empty or unparsable. */
+function comparable(definition, value) {
+  if (value === null || value === undefined || value === "") return undefined;
+  if (definition.type === "number") {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+  }
+  if (isDateType(definition)) return parseMillis(String(value));
+  return String(value).toLowerCase();
+}
+
+function hasValue(value) {
+  return value !== null && value !== undefined && value !== "";
+}
+
+function splitTokens(folded) {
+  return folded.split(TOKEN_SEPARATOR).filter((token) => token.length > 0);
+}
+
+/** An own property of a record's property map (never an inherited member such as `constructor`). */
+function own(properties, name) {
+  return Object.hasOwn(properties, name) ? properties[name] : undefined;
+}
+
+/**
+ * The framework decodes query strings and request bodies leniently, so malformed percent-encoding
+ * (`%E0%A4%A`) reaches the Tool as U+FFFD. A search value holding U+FFFD is a mangled request, not
+ * search text: reject it instead of running a corrupted filter that silently matches nothing. A
+ * correctly encoded U+FFFD (`%EF%BF%BD`) is rejected the same way; `%ZZ` stays literal and matches.
+ */
+export function isMangled(value) {
+  return typeof value === "string" && value.includes("\uFFFD");
+}
+
+/**
+ * Validate one filter and return `{ filter }` (normalised, with its comparison values precomputed) or `{ error }`.
+ * `definitions` is a Map of property name → definition for the object type.
+ */
+export function normalizeFilter(filter, definitions) {
+  if (typeof filter !== "object" || filter === null || Array.isArray(filter)) return { error: "Each filter must be an object" };
+  const name = filter.propertyName;
+  if (typeof name !== "string" || name.length === 0) return { error: "propertyName is required on every filter" };
+  const definition = definitions.get(name);
+  if (definition === undefined) return { error: `Property "${clip(name)}" does not exist` };
+  const operator = filter.operator;
+  if (typeof operator !== "string" || !OPERATORS.includes(operator)) {
+    return { error: `Invalid operator ${clip(JSON.stringify(operator ?? null))}; supported operators: ${OPERATORS.join(", ")}` };
+  }
+  const scalar = (value) => (typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? String(value) : undefined);
+  const tooLong = (field) => `Filter ${operator} on "${clip(name)}": ${field} exceeds the maximum length of ${MAX_SEARCH_TEXT} characters`;
+  const mangledValue = (field) => `Filter ${operator} on "${clip(name)}": ${field} contains an invalid character (U+FFFD); check the encoding of the request`;
+  const isDate = isDateType(definition);
+  const invalidDate = (text) => `${clip(JSON.stringify(text))} is not a valid date for "${clip(name)}"; use epoch milliseconds or ISO 8601`;
+  if (operator === "IN" || operator === "NOT_IN") {
+    if (!Array.isArray(filter.values) || filter.values.length === 0) return { error: `Filter ${operator} on "${clip(name)}" requires a non-empty values array` };
+    const values = [];
+    for (const item of filter.values) {
+      const value = scalar(item);
+      if (value === undefined) return { error: `Filter ${operator} on "${clip(name)}" has a non-scalar value` };
+      if (value.length > MAX_SEARCH_TEXT) return { error: tooLong("a value in values") };
+      if (isMangled(value)) return { error: mangledValue("a value in values") };
+      if (isDate && parseMillis(value) === undefined) return { error: invalidDate(value) };
+      values.push(value);
+    }
+    const valueSet = new Set();
+    for (const value of values) {
+      const key = comparable(definition, value);
+      if (key !== undefined) valueSet.add(key);
+    }
+    return { filter: { definition, operator, values, valueSet } };
+  }
+  if (operator === "HAS_PROPERTY" || operator === "NOT_HAS_PROPERTY") return { filter: { definition, operator } };
+  const value = scalar(filter.value);
+  if (value === undefined) return { error: `Filter ${operator} on "${clip(name)}" requires a value` };
+  if (value.length > MAX_SEARCH_TEXT) return { error: tooLong("value") };
+  if (isMangled(value)) return { error: mangledValue("value") };
+  if (isDate && operator !== "CONTAINS_TOKEN" && operator !== "NOT_CONTAINS_TOKEN" && parseMillis(value) === undefined) return { error: invalidDate(value) };
+  if (operator === "BETWEEN") {
+    const highValue = scalar(filter.highValue);
+    if (highValue === undefined) return { error: `Filter BETWEEN on "${clip(name)}" requires a highValue` };
+    if (highValue.length > MAX_SEARCH_TEXT) return { error: tooLong("highValue") };
+    if (isMangled(highValue)) return { error: mangledValue("highValue") };
+    if (isDate && parseMillis(highValue) === undefined) return { error: invalidDate(highValue) };
+    return { filter: { definition, operator, value, highValue, expected: comparable(definition, value), high: comparable(definition, highValue) } };
+  }
+  if (operator === "CONTAINS_TOKEN" || operator === "NOT_CONTAINS_TOKEN") return { filter: { definition, operator, value, match: globMatcher(value) } };
+  return { filter: { definition, operator, value, expected: comparable(definition, value) } };
+}
+
+/** Validate a whole `filterGroups` array → `{ groups }` or `{ error }`. */
+export function normalizeFilterGroups(filterGroups, definitions) {
+  if (filterGroups === undefined) return { groups: [] };
+  if (!Array.isArray(filterGroups)) return { error: "filterGroups must be an array" };
+  if (filterGroups.length > MAX_FILTER_GROUPS) return { error: `At most ${MAX_FILTER_GROUPS} filterGroups are allowed` };
+  const groups = [];
+  let total = 0;
+  for (const group of filterGroups) {
+    const filters = typeof group === "object" && group !== null ? group.filters : undefined;
+    if (!Array.isArray(filters)) return { error: "Each filterGroup must carry a filters array" };
+    if (filters.length > MAX_FILTERS_PER_GROUP) return { error: `At most ${MAX_FILTERS_PER_GROUP} filters are allowed per filterGroup` };
+    total += filters.length;
+    if (total > MAX_FILTERS_TOTAL) return { error: `At most ${MAX_FILTERS_TOTAL} filters are allowed across all filterGroups` };
+    const normalized = [];
+    for (const filter of filters) {
+      const result = normalizeFilter(filter, definitions);
+      if (result.error !== undefined) return { error: result.error };
+      normalized.push(result.filter);
+    }
+    groups.push(normalized);
+  }
+  return { groups };
+}
+
+/**
+ * A per-request record predicate: OR across groups, AND within a group (no groups → every record matches), then
+ * every free-text query token must be a prefix of some token in one of the `searchable` properties. Each record's
+ * property values are folded and tokenised at most once, all work is charged to `budget`, and evaluation stops as
+ * soon as the budget is exhausted (the caller must check `budget.exceeded` and fail the request).
+ */
+export function createRecordMatcher(groups, query, searchable, budget) {
+  const needles = [...new Set(splitTokens(String(query).toLowerCase()))];
+  return (properties) => {
+    const entries = new Map();
+    const entry = (name) => {
+      let found = entries.get(name);
+      if (found === undefined) {
+        found = { raw: own(properties, name), folded: undefined, tokens: undefined };
+        entries.set(name, found);
+      }
+      return found;
+    };
+    const folded = (item) => {
+      if (item.folded === undefined) {
+        const text = String(item.raw);
+        charge(budget, text.length);
+        item.folded = text.toLowerCase();
+      }
+      return item.folded;
+    };
+    const tokensOf = (item) => {
+      if (item.tokens === undefined) {
+        const text = folded(item);
+        charge(budget, text.length);
+        item.tokens = splitTokens(text);
+      }
+      return item.tokens;
+    };
+    const actualOf = (definition, item) => {
+      if (!hasValue(item.raw)) return undefined;
+      if (definition.type === "number" || isDateType(definition)) {
+        charge(budget, String(item.raw).length);
+        return comparable(definition, item.raw);
+      }
+      return folded(item);
+    };
+    const matchesFilter = (filter) => {
+      const { definition, operator } = filter;
+      const item = entry(definition.name);
+      switch (operator) {
+        case "HAS_PROPERTY":
+          return hasValue(item.raw);
+        case "NOT_HAS_PROPERTY":
+          return !hasValue(item.raw);
+        case "IN":
+        case "NOT_IN": {
+          const actual = actualOf(definition, item);
+          const hit = actual !== undefined && filter.valueSet.has(actual);
+          return operator === "IN" ? hit : !hit;
+        }
+        case "CONTAINS_TOKEN":
+        case "NOT_CONTAINS_TOKEN": {
+          let hit = false;
+          if (hasValue(item.raw)) {
+            const tokens = tokensOf(item);
+            if (!charge(budget, item.folded.length + tokens.length)) return false;
+            hit = tokens.some(filter.match);
+          }
+          return operator === "CONTAINS_TOKEN" ? hit : !hit;
+        }
+        default: {
+          const actual = actualOf(definition, item);
+          const expected = filter.expected;
+          if (operator === "NEQ") return actual === undefined || expected === undefined || actual !== expected;
+          if (actual === undefined || expected === undefined) return false;
+          if (operator === "EQ") return actual === expected;
+          if (operator === "LT") return actual < expected;
+          if (operator === "LTE") return actual <= expected;
+          if (operator === "GT") return actual > expected;
+          if (operator === "GTE") return actual >= expected;
+          if (operator === "BETWEEN") return filter.high !== undefined && actual >= expected && actual <= filter.high;
+          return false;
+        }
+      }
+    };
+    if (groups.length > 0 && !groups.some((group) => group.every((filter) => !budget.exceeded && matchesFilter(filter)))) return false;
+    if (budget.exceeded || needles.length === 0) return !budget.exceeded;
+    const unique = new Set();
+    for (const name of searchable) {
+      const item = entry(name);
+      if (hasValue(item.raw)) for (const token of tokensOf(item)) unique.add(token);
+    }
+    const haystack = [...unique].sort();
+    const steps = Math.ceil(Math.log2(haystack.length + 1)) + 1;
+    if (!charge(budget, haystack.length * steps)) return false;
+    for (const needle of needles) {
+      if (!charge(budget, needle.length * steps)) return false;
+      const candidate = haystack[lowerBound(haystack, needle)];
+      if (candidate === undefined || !candidate.startsWith(needle)) return false;
+    }
+    return true;
+  };
+}
+
+/** Validate `sorts` (objects or `"-name"` strings) → `{ sort }` (or `{ sort: undefined }`) or `{ error }`. */
+export function normalizeSorts(sorts, definitions) {
+  if (sorts === undefined) return { sort: undefined };
+  if (!Array.isArray(sorts)) return { error: "sorts must be an array" };
+  if (sorts.length === 0) return { sort: undefined };
+  if (sorts.length > 1) return { error: "Only one sort is supported" };
+  const entry = sorts[0];
+  let name;
+  let direction = "ASCENDING";
+  if (typeof entry === "string") {
+    name = entry.startsWith("-") ? entry.slice(1) : entry;
+    direction = entry.startsWith("-") ? "DESCENDING" : "ASCENDING";
+  } else if (typeof entry === "object" && entry !== null) {
+    name = entry.propertyName;
+    direction = entry.direction ?? "ASCENDING";
+  }
+  if (typeof name !== "string" || name.length === 0) return { error: "sorts[0].propertyName is required" };
+  const definition = definitions.get(name);
+  if (definition === undefined) return { error: `Property "${clip(name)}" does not exist` };
+  if (direction !== "ASCENDING" && direction !== "DESCENDING") return { error: "sorts[0].direction must be ASCENDING or DESCENDING" };
+  return { sort: { definition, direction } };
+}
+
+/**
+ * Sort records in place by `sort` (missing values last in both directions, ties by numeric id). Sort keys are
+ * computed once per record and charged to `budget`, so comparisons never re-fold property values.
+ */
+export function sortRecords(records, sort, budget) {
+  const { definition, direction } = sort;
+  const keyed = records.map((record) => {
+    const raw = own(record.properties, definition.name);
+    if (typeof raw === "string") charge(budget, raw.length);
+    return { record, key: comparable(definition, raw), id: Number(record.id) };
+  });
+  if (budget.exceeded) return records;
+  keyed.sort((left, right) => {
+    const a = left.key;
+    const b = right.key;
+    let order = 0;
+    if (a === undefined && b !== undefined) order = 1;
+    else if (b === undefined && a !== undefined) order = -1;
+    else if (a !== undefined && b !== undefined) {
+      order = a < b ? -1 : a > b ? 1 : 0;
+      if (direction === "DESCENDING") order = -order;
+    }
+    return order || left.id - right.id;
+  });
+  keyed.forEach((entry, index) => {
+    records[index] = entry.record;
+  });
+  return records;
+}

package/firedrill/tools/hubspot/lib/state.mjs

@@ -0,0 +1,248 @@
+// Row ids, counters, bounded scans and virtual-time formatting. Every function is pure or reads
+// context.state; nothing keeps module-level state.
+
+export const SCAN_STEP = 500;
+export const SCAN_CAP = 10_000;
+const ID_PATTERN = /^[1-9][0-9]{0,9}$/;
+const DEFINED_AT = "2019-08-06T02:41:09.058Z";
+
+/** The framework rejects state row ids longer than 512 characters (a lookup with one throws). */
+export const MAX_ROW_ID = 512;
+
+/** True when `namespacePrefix + value` is a row id the state store accepts (non-empty, no `/`, ≤ 512 chars). */
+export function isRowKey(value, prefix = "") {
+  return typeof value === "string" && value.length > 0 && !value.includes("/") && prefix.length + value.length <= MAX_ROW_ID;
+}
+
+/** The framework caps a Tool error message at 1000 characters (longer messages fail response mapping). */
+export const MAX_MESSAGE = 1_000;
+const CLIP = 100;
+
+/**
+ * A caller value shortened for echoing in an error message (`abc…` beyond 100 code points).
+ * The cut is on code points, never on UTF-16 units, so an astral character (emoji, rare CJK) is
+ * never split into a lone surrogate.
+ */
+export function clip(value, max = CLIP) {
+  const text = typeof value === "string" ? value : String(value);
+  if (text.length <= max) return text;
+  const points = Array.from(text);
+  return points.length > max ? `${points.slice(0, max).join("")}…` : text;
+}
+
+/**
+ * A caller value rendered as JSON for an error message: the value is clipped first and encoded
+ * afterwards, so the quoting of a long string stays balanced (`"abc…"`, never `"abc…`).
+ */
+export function clipJson(value, max = CLIP) {
+  if (typeof value === "string") return JSON.stringify(clip(value, max));
+  if (value === null || typeof value === "number" || typeof value === "boolean") return clip(String(value), max);
+  if (Array.isArray(value)) return `an array of ${value.length} values`;
+  if (typeof value === "object") return "an object";
+  return clip(String(value), max);
+}
+
+/**
+ * A Tool error message bounded to the framework's cap. The framework validates the message with a
+ * UTF-16 length check (`z.string().max(1000)`), so the bound is 1000 UTF-16 units, but the cut falls on
+ * a code point boundary: an astral character that would straddle the cut is dropped whole, never split
+ * into a lone surrogate. The result, ellipsis included, always fits the cap.
+ */
+export function clipMessage(message, max = MAX_MESSAGE) {
+  const text = typeof message === "string" ? message : String(message);
+  if (text.length <= max) return text;
+  let end = 0;
+  for (const point of text) {
+    if (end + point.length > max - 1) break;
+    end += point.length;
+  }
+  return `${text.slice(0, end)}…`;
+}
+
+export function fail(context, code, message, details) {
+  const text = clipMessage(message);
+  return context.fail(details === undefined ? { code, message: text } : { code, message: text, details });
+}
+
+export function notFound(context, message = "resource not found") {
+  return fail(context, "NOT_FOUND", message);
+}
+
+/** HubSpot's validation envelope: one message plus one `errors[]` entry per offending field. */
+export function validationError(context, message, errors) {
+  return fail(context, "VALIDATION_ERROR", message, { errors: errors ?? [{ message }] });
+}
+
+export function tooLarge(context) {
+  return fail(context, "VALIDATION_ERROR", "The result set is too large for this Tool (more than 10000 rows).");
+}
+
+export function isObjectId(value) {
+  return typeof value === "string" && ID_PATTERN.test(value);
+}
+
+export function padId(id) {
+  return String(id).padStart(10, "0");
+}
+
+export function associationRowId(fromTypeId, fromId, toTypeId, toId) {
+  return `${fromTypeId}/${padId(fromId)}/${toTypeId}/${padId(toId)}`;
+}
+
+export function associationPrefix(fromTypeId, fromId, toTypeId) {
+  return `${fromTypeId}/${padId(fromId)}/${toTypeId}/`;
+}
+
+/** Every row whose id starts with `prefix` (in row-id order), through bounded scans. */
+export function prefixRows(context, namespace, prefix) {
+  const rows = [];
+  let after = prefix;
+  for (;;) {
+    const batch = context.state.scan(namespace, { afterRowId: after, limit: SCAN_STEP });
+    if (batch.length === 0) return rows;
+    for (const record of batch) {
+      if (!record.rowId.startsWith(prefix)) return rows;
+      after = record.rowId;
+      rows.push(record.value);
+      if (rows.length >= SCAN_CAP) return tooLarge(context);
+    }
+    if (batch.length < SCAN_STEP) return rows;
+  }
+}
+
+/** Every row of a namespace in row-id order (bounded). */
+export function allRows(context, namespace) {
+  const rows = [];
+  let after;
+  for (;;) {
+    const batch = context.state.scan(namespace, { ...(after === undefined ? {} : { afterRowId: after }), limit: SCAN_STEP });
+    if (batch.length === 0) return rows;
+    for (const record of batch) {
+      after = record.rowId;
+      rows.push(record.value);
+      if (rows.length >= SCAN_CAP) return tooLarge(context);
+    }
+    if (batch.length < SCAN_STEP) return rows;
+  }
+}
+
+/** ISO-8601 with milliseconds, as HubSpot renders timestamps (`2026-09-14T09:00:00.000Z`). */
+export function isoFromUs(us) {
+  return new Date(Math.floor(us / 1_000)).toISOString();
+}
+
+export function isoNow(context) {
+  return isoFromUs(context.clock.nowUs());
+}
+
+export function definedAt() {
+  return DEFINED_AT;
+}
+
+// Strict, host-independent datetime parsing. HubSpot accepts epoch milliseconds or ISO 8601; `Date.parse`
+// is never used because it reads zone-less strings in the host time zone and accepts engine-specific formats.
+const EPOCH_MS = /^[0-9]{1,15}$/;
+const ISO_8601 =
+  /^([0-9]{4})-([0-9]{2})-([0-9]{2})(?:[Tt ]([0-9]{2}):([0-9]{2})(?::([0-9]{2})(?:[.,]([0-9]{1,9}))?)?(Z|z|[+-][0-9]{2}(?::?[0-9]{2})?)?)?$/;
+// HubSpot renders datetimes as four-digit-year ISO strings: accept 0000-01-01T00:00:00.000Z … 9999-12-31T23:59:59.999Z.
+const MIN_EPOCH_MS = -62_167_219_200_000;
+const MAX_EPOCH_MS = 253_402_300_799_999;
+
+function daysInMonth(year, month) {
+  if (month === 2) return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0 ? 29 : 28;
+  return month === 4 || month === 6 || month === 9 || month === 11 ? 30 : 31;
+}
+
+/**
+ * Epoch milliseconds for an epoch-ms digit string or an ISO-8601 date/datetime; undefined otherwise.
+ * A date-only value is midnight UTC and a datetime without a zone designator is read as UTC, so the same
+ * input yields the same instant on every host. Impossible calendar values (month 13, 31 April, 24:00) are rejected.
+ */
+export function parseMillis(value) {
+  if (typeof value !== "string") return undefined;
+  const text = value.trim();
+  if (EPOCH_MS.test(text)) {
+    const epoch = Number(text);
+    return epoch > MAX_EPOCH_MS ? undefined : epoch;
+  }
+  const match = ISO_8601.exec(text);
+  if (match === null) return undefined;
+  const [, y, mo, d, h = "00", mi = "00", s = "00", fraction = "", zone = "Z"] = match;
+  const year = Number(y);
+  const month = Number(mo);
+  const day = Number(d);
+  const hour = Number(h);
+  const minute = Number(mi);
+  const second = Number(s);
+  if (month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month) || hour > 23 || minute > 59 || second > 59) return undefined;
+  let offsetMinutes = 0;
+  if (zone !== "Z" && zone !== "z") {
+    const digits = zone.slice(1).replace(":", "");
+    const offsetHours = Number(digits.slice(0, 2));
+    const offsetMins = digits.length > 2 ? Number(digits.slice(2, 4)) : 0;
+    if (offsetHours > 18 || offsetMins > 59) return undefined;
+    offsetMinutes = (zone[0] === "-" ? -1 : 1) * (offsetHours * 60 + offsetMins);
+  }
+  const millis = Number(fraction.padEnd(3, "0").slice(0, 3));
+  const instant = Date.UTC(2000, 0, 1, 0, 0, 0, 0) + utcDayOffset(year, month, day) * 86_400_000 + ((hour * 60 + minute - offsetMinutes) * 60 + second) * 1_000 + millis;
+  return instant < MIN_EPOCH_MS || instant > MAX_EPOCH_MS ? undefined : instant;
+}
+
+/** Whole days from 2000-01-01 to the given proleptic Gregorian date (pure arithmetic, no Date parsing). */
+function utcDayOffset(year, month, day) {
+  const y = month <= 2 ? year - 1 : year;
+  const era = Math.floor(y / 400);
+  const yoe = y - era * 400;
+  const doy = Math.floor((153 * (month + (month > 2 ? -3 : 9)) + 2) / 5) + day - 1;
+  const doe = yoe * 365 + Math.floor(yoe / 4) - Math.floor(yoe / 100) + doy;
+  return era * 146_097 + doe - 719_468 - 10_957;
+}
+
+/** Epoch-millisecond digit strings and ISO-8601 dates/datetimes → `YYYY-MM-DDTHH:MM:SS.sssZ`; undefined when invalid. */
+export function normalizeDateTime(value) {
+  const ms = parseMillis(value);
+  return ms === undefined ? undefined : new Date(ms).toISOString();
+}
+
+/**
+ * The first row of a namespace (row-id order) matching `predicate`, or null. Pages through the whole
+ * namespace in bounded scans; it never truncates, because it returns a single row rather than a result set.
+ */
+export function findRow(context, namespace, predicate) {
+  let after;
+  for (;;) {
+    const batch = context.state.scan(namespace, { ...(after === undefined ? {} : { afterRowId: after }), limit: SCAN_STEP });
+    for (const record of batch) {
+      if (predicate(record.value)) return record.value;
+      after = record.rowId;
+    }
+    if (batch.length < SCAN_STEP) return null;
+  }
+}
+
+const DEFAULT_COUNTERS = { nextObjectId: 1 };
+
+export function counters(context) {
+  const stored = context.state.get("meta", "counters");
+  return stored === null ? { ...DEFAULT_COUNTERS } : { ...stored };
+}
+
+/**
+ * The next free object id. Starter data normally seeds `meta/counters`; when it is absent the counter
+ * starts at 1 and skips ids that already exist in any object namespace (bounded probe).
+ */
+export function nextObjectId(context, namespaces) {
+  const meta = counters(context);
+  let id = meta.nextObjectId;
+  for (let probe = 0; probe < 1_000; probe += 1) {
+    const taken = namespaces.some((namespace) => context.state.get(namespace, padId(id)) !== null);
+    if (!taken) break;
+    id += 1;
+  }
+  context.state.put("meta", "counters", { ...meta, nextObjectId: id + 1 });
+  return String(id);
+}
+
+export function compareStrings(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

package/firedrill/tools/hubspot/lib/wire.mjs

@@ -0,0 +1,125 @@
+// HubSpot REST wire helpers: query parsing, the error envelope and the rate-limit headers. Pure
+// functions only, so the HTTP codecs can use them without state or a clock.
+
+import { assertJsonDepth } from "./json-depth.mjs";
+
+const OAUTH_DOCS = "https://developers.hubspot.com/docs/methods/auth/oauth-overview";
+
+function last(values) {
+  return values === undefined || values.length === 0 ? undefined : values[values.length - 1];
+}
+
+export function str(query, name) {
+  return last(query[name]);
+}
+
+export function int(query, name) {
+  const value = last(query[name]);
+  if (value === undefined) return undefined;
+  // A malformed value is passed through as its raw string; the handler rejects it with VALIDATION_ERROR.
+  return /^-?[0-9]{1,9}$/.test(value) ? Number(value) : value;
+}
+
+export function bool(query, name) {
+  const value = last(query[name]);
+  if (value === undefined) return undefined;
+  if (value === "true") return true;
+  if (value === "false") return false;
+  return value; // raw string: the handler rejects it with VALIDATION_ERROR
+}
+
+/** Comma-separated (and repeatable) query parameter → string array, or undefined when absent. */
+export function list(query, name) {
+  const values = query[name];
+  if (values === undefined || values.length === 0) return undefined;
+  const items = [];
+  for (const value of values) for (const part of value.split(",")) if (part.trim().length > 0) items.push(part.trim());
+  return items;
+}
+
+export function defined(object) {
+  return Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined));
+}
+
+export function jsonBody(request) {
+  const value = request.body.kind === "json" ? request.body.value : undefined;
+  assertJsonDepth(value);
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+
+export function jsonArrayBody(request) {
+  const value = request.body.kind === "json" ? request.body.value : undefined;
+  assertJsonDepth(value);
+  return Array.isArray(value) ? value : [];
+}
+
+/** Mutations accept an optional X-Firedrill-Idempotency-Key header (HubSpot clients never send one). */
+export function operationInput(request, args) {
+  const key = last(request.headers["x-firedrill-idempotency-key"]);
+  return key === undefined || key.length === 0 ? { arguments: args } : { arguments: args, idempotencyKey: key };
+}
+
+export function isRateLimited(outcome) {
+  return outcome.status === "tool_error" && outcome.error?.code === "tool.RATE_LIMITED";
+}
+
+/** Constant decoration headers; under the rate-limit fault `Remaining` drops to 0 and Retry-After appears. */
+export function responseHeaders(correlationId, limited) {
+  return {
+    "x-hubspot-correlation-id": correlationId,
+    "x-hubspot-ratelimit-secondly": "100",
+    "x-hubspot-ratelimit-secondly-remaining": limited ? "0" : "99",
+    "x-hubspot-ratelimit-daily": "250000",
+    "x-hubspot-ratelimit-daily-remaining": limited ? "249000" : "249999",
+    "x-hubspot-ratelimit-interval-milliseconds": "10000",
+    ...(limited ? { "retry-after": "1" } : {}),
+  };
+}
+
+const CATEGORIES = {
+  UNAUTHORIZED: "INVALID_AUTHENTICATION",
+  MISSING_SCOPES: "MISSING_SCOPES",
+  NOT_FOUND: "OBJECT_NOT_FOUND",
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  CONFLICT: "CONFLICT",
+  RATE_LIMITED: "RATE_LIMITS",
+  SERVICE_UNAVAILABLE: "INTERNAL_ERROR",
+};
+
+/** HubSpot error envelope for a non-ok outcome; status codes are framework-owned (declared per route). */
+export function hubspotError(outcome, correlationId) {
+  const error = outcome.error ?? {};
+  const message = typeof error.message === "string" ? error.message : "";
+  if (outcome.status === "denied") {
+    return {
+      status: "error",
+      message: "This operation is not granted to the calling actor in this Firedrill world.",
+      correlationId,
+      category: "MISSING_SCOPES",
+    };
+  }
+  if (outcome.status === "unsupported") {
+    return { status: "error", message: "resource not found", correlationId, category: "OBJECT_NOT_FOUND" };
+  }
+  if (outcome.status === "invalid") {
+    return {
+      status: "error",
+      message: message.length > 0 ? `Invalid input JSON: ${message}` : "Invalid input JSON",
+      correlationId,
+      category: "VALIDATION_ERROR",
+      context: { firedrill: [String(error.code ?? "invalid")] },
+    };
+  }
+  const code = String(error.code ?? "").replace(/^tool\./, "");
+  const body = {
+    status: "error",
+    message: message.length > 0 ? message : "internal error",
+    correlationId,
+    category: Object.hasOwn(CATEGORIES, code) ? CATEGORIES[code] : "INTERNAL_ERROR",
+  };
+  const details = typeof error.details === "object" && error.details !== null ? error.details : {};
+  if (Array.isArray(details.errors)) body.errors = details.errors;
+  if (typeof details.context === "object" && details.context !== null) body.context = details.context;
+  if (code === "UNAUTHORIZED") body.links = { "oauth-overview": OAUTH_DOCS };
+  return body;
+}