@firedrill-tools/unified 0.1.1

package/firedrill/rate-limited.scenario.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "id": "rate-limited",
+  "title": "Every operation answers 429 RATE_LIMITED \"Too many requests to Unified.to\" with Retry-After: 1",
+  "faults": [
+    {
+      "packageId": "unified",
+      "faultId": "rate-limited"
+    }
+  ]
+}

package/firedrill/tools/unified/behavior.mjs

@@ -0,0 +1,69 @@
+// Synthetic Unified.to workspace for Firedrill: connections, unified CRM (contact, company, deal, pipeline) and
+// Messaging (channel, message). Every operation computes from `context.state`; ids come from `meta/counters`,
+// timestamps from virtual time. No Unified.to service and no underlying platform is contacted.
+import { Q, decoder, encoder } from "./lib/wire.mjs";
+import { channels } from "./ops/channels.mjs";
+import { connections } from "./ops/connections.mjs";
+import { companies, contacts } from "./ops/crm.mjs";
+import { deals } from "./ops/deals.mjs";
+import { messages } from "./ops/messages.mjs";
+import { pipelines } from "./ops/pipelines.mjs";
+
+const LIST = { limit: Q.int, offset: Q.int, updated_gte: Q.str, sort: Q.str, order: Q.str, query: Q.str, fields: Q.list };
+const FIELDS = { fields: Q.list };
+const CONNECTION = ["connection_id"];
+const CONNECTION_ID = ["connection_id", "id"];
+
+const listRoute = (extra) => decoder({ path: CONNECTION, query: { ...LIST, ...extra } });
+const getRoute = () => decoder({ path: CONNECTION_ID, query: FIELDS });
+const createRoute = () => decoder({ path: CONNECTION, body: "json", idem: true });
+const updateRoute = () => decoder({ path: CONNECTION_ID, body: "json", idem: true });
+const removeRoute = () => decoder({ path: CONNECTION_ID, idem: true });
+
+/** [operation id, handler, [route id, decoder]...] */
+const TABLE = [
+  ["connections.list", connections.list, ["list-connections", decoder({ query: { limit: Q.int, offset: Q.int, updated_gte: Q.str, sort: Q.str, order: Q.str, env: Q.str, categories: Q.list, external_xref: Q.str } })]],
+  ["connections.get", connections.get, ["get-connection", decoder({ path: ["id"] })]],
+  ["connections.create", connections.create, ["create-connection", decoder({ body: "json", idem: true })]],
+  ["connections.update", connections.update, ["update-connection-put", decoder({ path: ["id"], body: "json", idem: true })], ["update-connection-patch", decoder({ path: ["id"], body: "json", idem: true })]],
+  ["connections.remove", connections.remove, ["remove-connection", decoder({ path: ["id"], idem: true })]],
+
+  ["contacts.list", contacts.list, ["list-crm-contacts", listRoute({ company_id: Q.str, deal_id: Q.str, user_id: Q.str })]],
+  ["contacts.get", contacts.get, ["get-crm-contact", getRoute()]],
+  ["contacts.create", contacts.create, ["create-crm-contact", createRoute()]],
+  ["contacts.update", contacts.update, ["update-crm-contact-put", updateRoute()], ["update-crm-contact-patch", updateRoute()]],
+  ["contacts.remove", contacts.remove, ["remove-crm-contact", removeRoute()]],
+
+  ["companies.list", companies.list, ["list-crm-companies", listRoute({ contact_id: Q.str, deal_id: Q.str, user_id: Q.str })]],
+  ["companies.get", companies.get, ["get-crm-company", getRoute()]],
+  ["companies.create", companies.create, ["create-crm-company", createRoute()]],
+  ["companies.update", companies.update, ["update-crm-company-put", updateRoute()], ["update-crm-company-patch", updateRoute()]],
+  ["companies.remove", companies.remove, ["remove-crm-company", removeRoute()]],
+
+  ["deals.list", deals.list, ["list-crm-deals", listRoute({ company_id: Q.str, contact_id: Q.str, user_id: Q.str, pipeline_id: Q.str })]],
+  ["deals.get", deals.get, ["get-crm-deal", getRoute()]],
+  ["deals.create", deals.create, ["create-crm-deal", createRoute()]],
+  ["deals.update", deals.update, ["update-crm-deal-put", updateRoute()], ["update-crm-deal-patch", updateRoute()]],
+  ["deals.remove", deals.remove, ["remove-crm-deal", removeRoute()]],
+
+  ["pipelines.list", pipelines.list, ["list-crm-pipelines", decoder({ path: CONNECTION, query: { limit: Q.int, offset: Q.int, updated_gte: Q.str, sort: Q.str, order: Q.str, fields: Q.list } })]],
+  ["pipelines.get", pipelines.get, ["get-crm-pipeline", getRoute()]],
+
+  ["channels.list", channels.list, ["list-messaging-channels", listRoute({ parent_id: Q.str, type: Q.str })]],
+  ["channels.get", channels.get, ["get-messaging-channel", getRoute()]],
+
+  ["messages.list", messages.list, ["list-messaging-messages", listRoute({ channel_id: Q.str, parent_id: Q.str, type: Q.str, start_gte: Q.str, end_lt: Q.str, expand: Q.str, user_id: Q.str, user_mentioned_id: Q.str })]],
+  ["messages.get", messages.get, ["get-messaging-message", getRoute()]],
+  ["messages.create", messages.create, ["create-messaging-message", createRoute()]],
+  ["messages.update", messages.update, ["update-messaging-message-put", updateRoute()], ["update-messaging-message-patch", updateRoute()]],
+  ["messages.remove", messages.remove, ["remove-messaging-message", removeRoute()]],
+];
+
+const operations = {};
+const http = {};
+for (const [operationId, handler, ...routes] of TABLE) {
+  operations[operationId] = handler;
+  for (const [routeId, decode] of routes) http[routeId] = { decode, encode: encoder };
+}
+
+export default { operations, http };

package/firedrill/tools/unified/lib/assoc.mjs

@@ -0,0 +1,61 @@
+// Symmetric CRM associations: a contact's `company_ids` mirrors each company's `contact_ids`, and so on. Only rows
+// whose membership actually changes are rewritten (each rewrite emits object.updated for that row). References are
+// checked with point lookups by id, never by rescanning the namespace.
+import { badRequest } from "./errors.mjs";
+import { emitUpdated } from "./events.mjs";
+import { getRow, putRow } from "./store.mjs";
+import { nowIso } from "./time.mjs";
+import { clip } from "./util.mjs";
+
+/** namespace -> { objectType, links: { field: [target namespace, reverse field] } } */
+export const CRM = {
+  contacts: { objectType: "crm_contact", label: "Contact", links: { company_ids: ["companies", "contact_ids"], deal_ids: ["deals", "contact_ids"] } },
+  companies: { objectType: "crm_company", label: "Company", links: { contact_ids: ["contacts", "company_ids"], deal_ids: ["deals", "company_ids"] } },
+  deals: { objectType: "crm_deal", label: "Deal", links: { contact_ids: ["contacts", "deal_ids"], company_ids: ["companies", "deal_ids"] } },
+};
+
+const LABEL = { contacts: "contact", companies: "company", deals: "deal" };
+
+/** Every referenced id must be a row of the same connection. */
+export function checkReferences(context, connectionId, namespace, fields) {
+  for (const [field, [target]] of Object.entries(CRM[namespace].links)) {
+    const ids = fields[field];
+    if (!Array.isArray(ids)) continue;
+    for (const id of ids) {
+      if (getRow(context, target, connectionId, id) === null) badRequest(context, `Unknown ${LABEL[target]} id in ${field}: ${clip(id, 40)}`);
+    }
+  }
+}
+
+function rewrite(context, connection, target, row, reverseField, ids) {
+  const next = { ...row, [reverseField]: ids, updated_at: nowIso(context) };
+  putRow(context, target, next);
+  emitUpdated(context, connection, CRM[target].objectType, row.id, [reverseField]);
+}
+
+/** Adds `ownId` to the reverse arrays of newly linked rows and removes it from rows no longer linked. */
+export function syncAssociations(context, connection, namespace, row, previous) {
+  for (const [field, [target, reverseField]] of Object.entries(CRM[namespace].links)) {
+    const before = new Set(previous === null ? [] : previous[field] ?? []);
+    const after = new Set(row[field] ?? []);
+    for (const id of after) {
+      if (before.has(id)) continue;
+      const other = getRow(context, target, connection.id, id);
+      if (other === null) continue;
+      const ids = other[reverseField] ?? [];
+      if (!ids.includes(row.id)) rewrite(context, connection, target, other, reverseField, [...ids, row.id]);
+    }
+    for (const id of before) {
+      if (after.has(id)) continue;
+      const other = getRow(context, target, connection.id, id);
+      if (other === null) continue;
+      const ids = other[reverseField] ?? [];
+      if (ids.includes(row.id)) rewrite(context, connection, target, other, reverseField, ids.filter((entry) => entry !== row.id));
+    }
+  }
+}
+
+/** Removes a deleted row's id from every associated row. */
+export function detachAll(context, connection, namespace, row) {
+  syncAssociations(context, connection, namespace, { ...row, contact_ids: [], company_ids: [], deal_ids: [] }, row);
+}

package/firedrill/tools/unified/lib/enums.mjs

@@ -0,0 +1,14 @@
+// Connection enums as published in the provider's OpenAPI document (property_Connection_categories and the crm_/
+// messaging_ values of property_Connection_permissions).
+export const CATEGORIES = [
+  "passthrough", "hris", "ats", "auth", "saml", "crm", "enrich", "martech", "ticketing", "uc", "accounting", "storage", "commerce",
+  "payment", "genai", "messaging", "kms", "task", "scim", "lms", "repo", "metadata", "calendar", "verification", "ads", "analytics",
+  "forms", "shipping", "assessment", "signing", "clubs", "datastore", "cdp", "performance", "social",
+];
+
+export const PERMISSIONS = [
+  "crm_company_read", "crm_company_write", "crm_contact_read", "crm_contact_write", "crm_deal_read", "crm_deal_write",
+  "crm_event_read", "crm_event_write", "crm_lead_read", "crm_lead_write", "crm_pipeline_read", "crm_pipeline_write",
+  "crm_taxonomy_read", "messaging_message_read", "messaging_message_write", "messaging_channel_read", "messaging_channel_write",
+  "messaging_event_read", "messaging_event_write",
+];

package/firedrill/tools/unified/lib/errors.mjs

@@ -0,0 +1,50 @@
+// Declared Tool error codes, their HTTP status on every route and the reason phrases of the wire envelope.
+import { clip } from "./util.mjs";
+
+/** code -> [HTTP status, reason phrase] */
+export const ERRORS = new Map([
+  ["BAD_REQUEST", [400, "Bad Request"]],
+  ["UNAUTHORIZED", [401, "Unauthorized"]],
+  ["FORBIDDEN", [403, "Forbidden"]],
+  ["NOT_FOUND", [404, "Not Found"]],
+  ["PAYLOAD_TOO_LARGE", [413, "Payload Too Large"]],
+  ["RATE_LIMITED", [429, "Too Many Requests"]],
+  ["INTERNAL_ERROR", [500, "Internal Server Error"]],
+  ["FAILED_PRECONDITION", [500, "Internal Server Error"]],
+  ["NOT_IMPLEMENTED", [501, "Not Implemented"]],
+]);
+
+/** Encoded page budget in UTF-8 bytes; the framework refuses route responses above 1 MiB. */
+export const PAGE_BYTE_BUDGET = 900000;
+
+/** Hard ceiling for the per-connection scan bound (`workspaces.limits.max_rows_per_namespace` can only lower it). */
+export const MAX_SCAN_BOUND = 10000;
+
+const DEFAULT_MESSAGE = "Required parameters are missing or in the wrong format";
+
+/** Fails with a declared code; an empty or non-string message falls back to the provider's generic wording. */
+export function fail(context, code, message) {
+  const text = typeof message === "string" ? clip(message, 3000).trim() : "";
+  context.fail({ code, message: text.length > 0 ? text : DEFAULT_MESSAGE });
+}
+
+export const badRequest = (context, message = "Required parameters are missing or in the wrong format") =>
+  fail(context, "BAD_REQUEST", message);
+
+export const unauthorized = (context, message = "Unauthorized") => fail(context, "UNAUTHORIZED", message);
+
+export const forbidden = (context, message = "Forbidden") => fail(context, "FORBIDDEN", message);
+
+export const notFound = (context, message = "Not found") => fail(context, "NOT_FOUND", message);
+
+export const notImplemented = (context) =>
+  fail(context, "NOT_IMPLEMENTED", "The requested functionality is not supported by this integration");
+
+export const tooLarge = (context) =>
+  fail(context, "PAYLOAD_TOO_LARGE", "Response exceeds 1 MB; lower limit or restrict fields");
+
+export const scanBoundExceeded = (context, namespace, bound) =>
+  fail(context, "FAILED_PRECONDITION", `State exceeds the supported bound of ${bound} rows for ${namespace}`);
+
+/** A field whose value is not what the schema allows: names the field and the bound, clipping any caller text. */
+export const invalidField = (context, field, detail) => badRequest(context, `Invalid value for ${clip(field, 80)}: ${detail}`);

package/firedrill/tools/unified/lib/events.mjs

@@ -0,0 +1,27 @@
+// Firedrill events mirroring the provider's webhook vocabulary: object.created / object.updated / object.deleted
+// with object types crm_contact, crm_company, crm_deal and messaging_message. A create emits both created and
+// updated (the provider documents that "updated" fires for newly created records too).
+
+function payload(connection, objectType, objectId) {
+  return {
+    workspace_id: connection.workspace_id,
+    connection_id: connection.id,
+    object_type: objectType,
+    object_id: objectId,
+    external_xref: connection.external_xref ?? null,
+  };
+}
+
+export function emitCreated(context, connection, objectType, objectId) {
+  context.events.emit("object.created", payload(connection, objectType, objectId));
+  context.events.emit("object.updated", { ...payload(connection, objectType, objectId), changed_fields: ["*"] });
+}
+
+export function emitUpdated(context, connection, objectType, objectId, changedFields) {
+  if (changedFields.length === 0) return;
+  context.events.emit("object.updated", { ...payload(connection, objectType, objectId), changed_fields: changedFields.slice(0, 64) });
+}
+
+export function emitDeleted(context, connection, objectType, objectId) {
+  context.events.emit("object.deleted", payload(connection, objectType, objectId));
+}

package/firedrill/tools/unified/lib/identity.mjs

@@ -0,0 +1,59 @@
+// Identity and per-connection access rules, applied by every handler in this order:
+// 1 workspace (actor attribute `workspaceId`, falling back to the first seeded workspace), 2 connection resolution
+// (incl. the `connectionIds` scope), 3 connection health, 4 category, 5 permission.
+import { badRequest, forbidden, notFound, notImplemented, unauthorized } from "./errors.mjs";
+import { scanAll } from "./store.mjs";
+import { clip, isHex24 } from "./util.mjs";
+
+/** Resolves the caller's workspace row or fails UNAUTHORIZED; also refuses a codec refusal carried in the input. */
+export function resolveWorkspace(input, context) {
+  if (typeof input.__request_error === "string") badRequest(context, input.__request_error);
+  const claimed = context.actor?.attributes?.workspaceId;
+  if (claimed !== undefined && claimed !== null) {
+    if (typeof claimed !== "string" || claimed.length === 0 || claimed.length > 64) unauthorized(context);
+    const row = context.state.get("workspaces", claimed);
+    if (row === null) unauthorized(context);
+    return row;
+  }
+  const rows = scanAll(context, "workspaces", 100);
+  if (rows.length === 0) unauthorized(context);
+  return rows[0];
+}
+
+/** The connection ids a connection-scoped key may see, or null for a workspace-wide key. */
+export function connectionScope(context) {
+  const scope = context.actor?.attributes?.connectionIds;
+  if (!Array.isArray(scope)) return null;
+  const set = new Set();
+  for (const id of scope.slice(0, 256)) if (typeof id === "string") set.add(id);
+  return set;
+}
+
+export const inScope = (scope, connectionId) => scope === null || scope.has(connectionId);
+
+/** Loads a connection of the workspace within the caller's scope, or fails NOT_FOUND (a scoped key learns nothing). */
+export function loadConnection(context, workspace, connectionId) {
+  if (!isHex24(connectionId)) badRequest(context, `Invalid connection_id: ${clip(connectionId, 60)}`);
+  const connection = context.state.get("connections", connectionId);
+  if (connection === null || connection.workspace_id !== workspace.id || !inScope(connectionScope(context), connectionId)) {
+    notFound(context, "Connection not found");
+  }
+  return connection;
+}
+
+/**
+ * Resolves the connection for a data operation and applies health, category and permission checks.
+ * `category` is "crm" or "messaging"; `permission` is the exact Unified.to permission slug.
+ */
+export function requireConnection(context, workspace, connectionId, category, permission) {
+  const connection = loadConnection(context, workspace, connectionId);
+  if (connection.last_unhealthy_code !== null && connection.last_unhealthy_code !== undefined) {
+    unauthorized(context, "The connection is likely broken and requires recreation");
+  }
+  if (connection.is_paused === true) forbidden(context, "Connection is paused; monthly plan limit exceeded");
+  if (!connection.categories.includes(category)) notImplemented(context);
+  if (!connection.permissions.includes(permission)) {
+    forbidden(context, `The connection lacks the required permissions or scopes: ${permission}`);
+  }
+  return connection;
+}

package/firedrill/tools/unified/lib/query.mjs

@@ -0,0 +1,154 @@
+// List parameters shared by every list operation: limit/offset paging, updated_gte, sort/order, query search,
+// reference filters, `fields` projection and the encoded-page byte budget.
+import { PAGE_BYTE_BUDGET, badRequest, tooLarge } from "./errors.mjs";
+import { parseIsoUs } from "./time.mjs";
+import { clip, compareText, containsFolded, fold, isHex24, jsonBytes } from "./util.mjs";
+
+export const MAX_LIMIT = 100;
+const SORTS = new Set(["name", "updated_at", "created_at"]);
+const ORDERS = new Set(["asc", "desc"]);
+const MAX_QUERY_LENGTH = 2000;
+const MAX_FIELDS = 64;
+
+const isInt = (value) => typeof value === "number" && Number.isInteger(value);
+
+/** Parses the shared list parameters; every problem is BAD_REQUEST with the provider's wording. */
+export function parseListParams(input, context) {
+  let limit = MAX_LIMIT;
+  if (input.limit !== undefined && input.limit !== null) {
+    if (!isInt(input.limit) || input.limit < 1) badRequest(context, "limit must be a positive integer");
+    limit = Math.min(input.limit, MAX_LIMIT);
+  }
+  let offset = 0;
+  if (input.offset !== undefined && input.offset !== null) {
+    if (!isInt(input.offset) || input.offset < 0 || input.offset > Number.MAX_SAFE_INTEGER) badRequest(context, "offset must be a non-negative integer");
+    offset = input.offset;
+  }
+  let updatedGteUs = null;
+  if (input.updated_gte !== undefined && input.updated_gte !== null) {
+    updatedGteUs = parseIsoUs(input.updated_gte);
+    if (updatedGteUs === null) badRequest(context, "updated_gte must be an ISO-8601 date or date-time");
+  }
+  let sort = null;
+  if (input.sort !== undefined && input.sort !== null) {
+    if (typeof input.sort !== "string" || !SORTS.has(input.sort)) badRequest(context, "sort must be one of name, updated_at, created_at");
+    sort = input.sort;
+  }
+  let order = "asc";
+  if (input.order !== undefined && input.order !== null) {
+    if (typeof input.order !== "string" || !ORDERS.has(input.order)) badRequest(context, "order must be asc or desc");
+    order = input.order;
+  }
+  let query = null;
+  if (input.query !== undefined && input.query !== null) {
+    if (typeof input.query !== "string" || input.query.length > MAX_QUERY_LENGTH) badRequest(context, `query must be a string of at most ${MAX_QUERY_LENGTH} characters`);
+    if (input.query.includes("�")) badRequest(context, "query contains malformed percent-encoding");
+    query = fold(input.query);
+  }
+  return { limit, offset, updatedGteUs, sort, order, query };
+}
+
+/** A reference filter (`company_id`, `channel_id`, ...) must be a well-formed id; an unknown id matches nothing. */
+export function idFilter(input, context, name, extra = null) {
+  const value = input[name];
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string" || (!isHex24(value) && !(extra !== null && extra.has(value)))) {
+    badRequest(context, `${name} must be a valid id`);
+  }
+  return value;
+}
+
+/** A plain string filter (`user_id`, `external_xref`). */
+export function textFilter(input, context, name, max = 256) {
+  const value = input[name];
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string" || value.length === 0 || value.length > max) badRequest(context, `${name} must be a string of at most ${max} characters`);
+  return value;
+}
+
+export function enumFilter(input, context, name, allowed) {
+  const value = input[name];
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string" || !allowed.includes(value)) badRequest(context, `${name} must be one of ${allowed.join(", ")}`);
+  return value;
+}
+
+/** True when any of the row's searchable strings contains the folded query. */
+export function matchesQuery(row, query, fields) {
+  if (query === null) return true;
+  for (const field of fields) {
+    const value = row[field];
+    if (typeof value === "string") {
+      if (containsFolded(value, query)) return true;
+    } else if (Array.isArray(value)) {
+      for (const entry of value) {
+        const text = typeof entry === "string" ? entry : entry?.email;
+        if (typeof text === "string" && containsFolded(text, query)) return true;
+      }
+    } else if (value !== null && typeof value === "object") {
+      for (const inner of Object.values(value)) if (containsFolded(inner, query)) return true;
+    }
+  }
+  return false;
+}
+
+export const updatedSince = (row, updatedGteUs) => updatedGteUs === null || (parseIsoUs(row.updated_at) ?? 0) >= updatedGteUs;
+
+/** Sorts in place by the requested field (ties by id); no sort keeps creation (row-id) order. */
+export function sortRows(rows, sort, order, nameField = "name") {
+  if (sort === null) {
+    if (order === "desc") rows.reverse();
+    return rows;
+  }
+  const field = sort === "name" ? nameField : sort;
+  const sign = order === "desc" ? -1 : 1;
+  rows.sort((a, b) => {
+    const left = a[field] ?? "";
+    const right = b[field] ?? "";
+    const cmp = compareText(String(left), String(right));
+    return cmp !== 0 ? sign * cmp : compareText(a.id, b.id);
+  });
+  return rows;
+}
+
+/** Parses `fields` (comma-separated or an array) into a Set, or null for the default projection. */
+export function parseFields(input, context) {
+  const raw = input.fields;
+  if (raw === undefined || raw === null) return null;
+  const parts = Array.isArray(raw) ? raw : typeof raw === "string" ? raw.split(",") : null;
+  if (parts === null) badRequest(context, "fields must be a comma-separated list of field names");
+  const set = new Set();
+  for (const part of parts) {
+    if (typeof part !== "string") badRequest(context, "fields must be a comma-separated list of field names");
+    for (const name of part.split(",")) {
+      const trimmed = name.trim();
+      if (trimmed.length > 0 && trimmed.length <= 200) set.add(trimmed);
+      if (set.size > MAX_FIELDS) badRequest(context, `fields lists more than ${MAX_FIELDS} names`);
+    }
+  }
+  set.add("id");
+  return set;
+}
+
+/** Applies the projection: default is every field except `raw`; `id` is always present; unknown names are ignored. */
+export function project(row, fields, hidden = []) {
+  const out = {};
+  for (const key of Object.keys(row)) {
+    if (key === "connection_id" || hidden.includes(key)) continue;
+    if (fields === null ? key !== "raw" : fields.has(key)) out[key] = row[key];
+  }
+  return out;
+}
+
+/** Slices the page and refuses one whose encoding would exceed the byte budget (offset paging cannot shorten it). */
+export function finishPage(context, rows, params, fields, hidden = []) {
+  const page = rows.slice(params.offset, params.offset + params.limit).map((row) => project(row, fields, hidden));
+  let bytes = 2;
+  for (const item of page) {
+    bytes += jsonBytes(item) + 1;
+    if (bytes > PAGE_BYTE_BUDGET) tooLarge(context);
+  }
+  return page;
+}
+
+export const describe = (value) => clip(typeof value === "string" ? value : JSON.stringify(value), 80);

package/firedrill/tools/unified/lib/shapes.mjs

@@ -0,0 +1,176 @@
+// Composite value validators (emails, telephones, address, metadata, members, references, `raw`). Each returns the
+// normalised value or fails BAD_REQUEST naming the field; caller keys are copied one by one, never spread.
+import { badRequest, invalidField } from "./errors.mjs";
+import { clip, isHex24, isPlainObject, jsonBytes } from "./util.mjs";
+
+const BANNED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const EMAIL_TYPES = ["WORK", "HOME", "OTHER"];
+const TELEPHONE_TYPES = ["WORK", "HOME", "OTHER", "FAX", "MOBILE"];
+export const METADATA_FORMATS = ["TEXT", "NUMBER", "DATE", "BOOLEAN", "TEXTAREA", "SINGLE_SELECT", "MULTIPLE_SELECT", "URL", "EMAIL", "PHONE", "CURRENCY", "PERCENT", "USER", "OBJECT", "MEASUREMENT"];
+const ADDRESS_FIELDS = ["address1", "address2", "city", "region", "region_code", "postal_code", "country", "country_code"];
+const MEMBER_FIELDS = ["user_id", "email", "name", "image_url"];
+const RAW_MAX_DEPTH = 8;
+const RAW_MAX_KEYS = 64;
+const RAW_MAX_BYTES = 16384;
+
+const nullableString = (context, field, value, max) => {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string" || value.length > max) invalidField(context, field, `must be a string of at most ${max} characters`);
+  return value;
+};
+
+function objectWith(context, field, value, names, max) {
+  if (!isPlainObject(value)) invalidField(context, field, "must be an object");
+  const out = {};
+  for (const key of Object.keys(value)) {
+    if (!names.includes(key)) badRequest(context, `Unknown field "${clip(`${field}.${key}`, 80)}"`);
+  }
+  for (const name of names) out[name] = nullableString(context, `${field}.${name}`, value[name], max);
+  return out;
+}
+
+function arrayOf(context, field, value, maxItems, each) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) invalidField(context, field, "must be an array");
+  if (value.length > maxItems) invalidField(context, field, `must have at most ${maxItems} entries`);
+  return value.map((entry, index) => each(`${field}[${index}]`, entry));
+}
+
+const emails = (context, field, value) =>
+  arrayOf(context, field, value, 32, (where, entry) => {
+    const out = objectWith(context, where, entry, ["email", "type"], 320);
+    if (typeof out.email !== "string" || !out.email.includes("@") || out.email.length < 3) invalidField(context, `${where}.email`, "must be an e-mail address");
+    if (out.type !== null && !EMAIL_TYPES.includes(out.type)) invalidField(context, `${where}.type`, `must be one of ${EMAIL_TYPES.join(", ")}`);
+    return out;
+  });
+
+const telephones = (context, field, value) =>
+  arrayOf(context, field, value, 32, (where, entry) => {
+    const out = objectWith(context, where, entry, ["telephone", "type"], 64);
+    if (typeof out.telephone !== "string" || out.telephone.length === 0) invalidField(context, `${where}.telephone`, "is required");
+    if (out.type !== null && !TELEPHONE_TYPES.includes(out.type)) invalidField(context, `${where}.type`, `must be one of ${TELEPHONE_TYPES.join(", ")}`);
+    return out;
+  });
+
+const address = (context, field, value) => (value === undefined || value === null ? null : objectWith(context, field, value, ADDRESS_FIELDS, 256));
+
+const member = (context, field, value) => {
+  const out = objectWith(context, field, value, MEMBER_FIELDS, 320);
+  if (out.email !== null && !out.email.includes("@")) invalidField(context, `${field}.email`, "must be an e-mail address");
+  return out;
+};
+
+const members = (context, field, value) => arrayOf(context, field, value, 100, (where, entry) => member(context, where, entry));
+
+const metadata = (context, field, value) =>
+  arrayOf(context, field, value, 100, (where, entry) => {
+    if (!isPlainObject(entry)) invalidField(context, where, "must be an object");
+    for (const key of Object.keys(entry)) {
+      if (!["id", "slug", "namespace", "format", "value", "extra_data"].includes(key)) badRequest(context, `Unknown field "${clip(`${where}.${key}`, 80)}"`);
+    }
+    const out = {
+      id: nullableString(context, `${where}.id`, entry.id, 256),
+      slug: nullableString(context, `${where}.slug`, entry.slug, 256),
+      namespace: nullableString(context, `${where}.namespace`, entry.namespace, 256),
+      format: nullableString(context, `${where}.format`, entry.format, 32),
+      value: entry.value === undefined ? null : entry.value,
+      extra_data: entry.extra_data === undefined ? null : entry.extra_data,
+    };
+    if (out.id === null && out.slug === null) invalidField(context, where, "needs an id or a slug");
+    if (out.format !== null && !METADATA_FORMATS.includes(out.format)) invalidField(context, `${where}.format`, `must be one of ${METADATA_FORMATS.join(", ")}`);
+    const kind = typeof out.value;
+    if (out.value !== null && kind !== "string" && kind !== "number" && kind !== "boolean") invalidField(context, `${where}.value`, "must be a string, number, boolean or null");
+    if (kind === "string" && out.value.length > 4000) invalidField(context, `${where}.value`, "must be at most 4000 characters");
+    if (kind === "number" && !Number.isFinite(out.value)) invalidField(context, `${where}.value`, "must be finite");
+    out.extra_data = out.extra_data === null ? null : raw(context, `${where}.extra_data`, out.extra_data);
+    return out;
+  });
+
+/** Copies a caller object key by key into fresh objects, bounding depth, keys per level and encoded size. */
+function raw(context, field, value) {
+  if (value === undefined || value === null) return {};
+  if (!isPlainObject(value)) invalidField(context, field, "must be an object");
+  const root = {};
+  const stack = [[value, root, 1]];
+  while (stack.length > 0) {
+    const [source, target, depth] = stack.pop();
+    if (depth > RAW_MAX_DEPTH) invalidField(context, field, `must not nest deeper than ${RAW_MAX_DEPTH} levels`);
+    const keys = Object.keys(source);
+    if (keys.length > RAW_MAX_KEYS) invalidField(context, field, `must have at most ${RAW_MAX_KEYS} keys per level`);
+    for (const key of keys) {
+      if (BANNED_KEYS.has(key) || key.length > 256) badRequest(context, `Invalid key in ${clip(field, 80)}: "${clip(key, 60)}"`);
+      const child = source[key];
+      if (isPlainObject(child)) {
+        const copy = {};
+        target[key] = copy;
+        stack.push([child, copy, depth + 1]);
+      } else if (Array.isArray(child)) {
+        if (child.length > RAW_MAX_KEYS) invalidField(context, field, `arrays must have at most ${RAW_MAX_KEYS} entries`);
+        const copy = [];
+        target[key] = copy;
+        for (const entry of child) {
+          if (isPlainObject(entry)) {
+            const inner = {};
+            copy.push(inner);
+            stack.push([entry, inner, depth + 1]);
+          } else if (Array.isArray(entry)) invalidField(context, field, "nested arrays are not supported");
+          else copy.push(entry === undefined ? null : entry);
+        }
+      } else if (typeof child === "number" && !Number.isFinite(child)) invalidField(context, field, "numbers must be finite");
+      else target[key] = child === undefined ? null : child;
+    }
+  }
+  if (jsonBytes(root) > RAW_MAX_BYTES) invalidField(context, field, `must encode to at most ${RAW_MAX_BYTES} bytes`);
+  return root;
+}
+
+const reactions = (context, field, value) =>
+  arrayOf(context, field, value, 200, (where, entry) => {
+    if (!isPlainObject(entry)) invalidField(context, where, "must be an object");
+    for (const key of Object.keys(entry)) if (key !== "reaction" && key !== "member") badRequest(context, `Unknown field "${clip(`${where}.${key}`, 80)}"`);
+    const reaction = nullableString(context, `${where}.reaction`, entry.reaction, 64);
+    if (reaction === null) invalidField(context, `${where}.reaction`, "is required");
+    return { reaction, member: member(context, `${where}.member`, entry.member ?? {}) };
+  });
+
+const attachments = (context, field, value) =>
+  arrayOf(context, field, value, 32, (where, entry) => {
+    if (!isPlainObject(entry)) invalidField(context, where, "must be an object");
+    const size = entry.size;
+    const rest = {};
+    for (const key of Object.keys(entry)) if (key !== "size") rest[key] = entry[key];
+    const out = objectWith(context, where, rest, ["filename", "content_type", "download_url", "content_identifier", "message_id"], 2048);
+    if (size !== undefined && size !== null && (typeof size !== "number" || !Number.isFinite(size) || size < 0)) invalidField(context, `${where}.size`, "must be a non-negative number");
+    out.size = size === undefined ? null : size;
+    return out;
+  });
+
+const buttons = (context, field, value) =>
+  arrayOf(context, field, value, 16, (where, entry) => {
+    const out = objectWith(context, where, entry, ["id", "text", "icon"], 256);
+    if (out.id === null) invalidField(context, `${where}.id`, "is required");
+    return out;
+  });
+
+/** `channels`, `pipelines`, `stages`: arrays of `{ id, name?, type? }` references whose ids must be well-formed. */
+const refs = (max, names) => (context, field, value) =>
+  arrayOf(context, field, value, max, (where, entry) => {
+    const out = objectWith(context, where, entry, names, 256);
+    if (!isHex24(out.id)) invalidField(context, `${where}.id`, "must be a valid id");
+    return out;
+  });
+
+export const SHAPES = new Map([
+  ["emails", emails],
+  ["telephones", telephones],
+  ["address", address],
+  ["member", (context, field, value) => (value === undefined || value === null ? null : member(context, field, value))],
+  ["members", members],
+  ["metadata", metadata],
+  ["raw", raw],
+  ["reactions", reactions],
+  ["attachments", attachments],
+  ["buttons", buttons],
+  ["channelRefs", refs(8, ["id", "name"])],
+  ["pipelineRefs", refs(1, ["id", "name", "type"])],
+]);