@firedrill-tools/notion 0.1.1

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

@@ -0,0 +1,272 @@
+// Data-source query semantics: Notion's per-type filter conditions, compound filters (two levels, ≤ 100
+// conditions per group), relative date windows from virtual time, and stable sorts.
+import { TEXT_TYPES, findDefinition, propertyValue } from "./properties.mjs";
+import { plainText } from "./rich-text.mjs";
+import { isMangled, mangledError, shown, validationError } from "./state.mjs";
+
+const DAY_MS = 86400000;
+const MAX_GROUP = 100;
+const MAX_DEPTH = 2;
+const TEXT_CONDITIONS = ["equals", "does_not_equal", "contains", "does_not_contain", "starts_with", "ends_with", "is_empty", "is_not_empty"];
+const NUMBER_CONDITIONS = ["equals", "does_not_equal", "greater_than", "less_than", "greater_than_or_equal_to", "less_than_or_equal_to", "is_empty", "is_not_empty"];
+const CHECKBOX_CONDITIONS = ["equals", "does_not_equal"];
+const OPTION_CONDITIONS = ["equals", "does_not_equal", "is_empty", "is_not_empty"];
+const CONTAINS_CONDITIONS = ["contains", "does_not_contain", "is_empty", "is_not_empty"];
+const DATE_CONDITIONS = ["equals", "before", "after", "on_or_before", "on_or_after", "is_empty", "is_not_empty", "this_week", "past_week", "past_month", "past_year", "next_week", "next_month", "next_year"];
+const DATE_TYPES = ["date", "created_time", "last_edited_time"];
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function conditionsFor(type) {
+  if (TEXT_TYPES.includes(type)) return TEXT_CONDITIONS;
+  if (type === "number") return NUMBER_CONDITIONS;
+  if (type === "checkbox") return CHECKBOX_CONDITIONS;
+  if (type === "select" || type === "status") return OPTION_CONDITIONS;
+  if (type === "multi_select" || type === "people" || type === "relation" || type === "created_by" || type === "last_edited_by") return CONTAINS_CONDITIONS;
+  if (DATE_TYPES.includes(type)) return DATE_CONDITIONS;
+  return [];
+}
+
+function textOf(type, value) {
+  if (value === null || value === undefined) return "";
+  return type === "title" || type === "rich_text" ? plainText(value) : String(value);
+}
+
+function dayIndex(ms) {
+  return Math.floor(ms / DAY_MS);
+}
+
+/** Compare a stored date (`{start}` or timestamp) with a filter value; date-only values compare by UTC day. */
+function compareDates(stored, filterValue) {
+  const storedString = isObject(stored) ? stored.start : stored;
+  const storedMs = Date.parse(storedString);
+  const filterMs = Date.parse(filterValue);
+  if (Number.isNaN(storedMs) || Number.isNaN(filterMs)) return undefined;
+  const dayOnly = storedString.length === 10 || filterValue.length === 10;
+  const left = dayOnly ? dayIndex(storedMs) : storedMs;
+  const right = dayOnly ? dayIndex(filterMs) : filterMs;
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function windowFor(condition, nowMs) {
+  const dayStart = dayIndex(nowMs) * DAY_MS;
+  switch (condition) {
+    case "past_week":
+      return [nowMs - 7 * DAY_MS, nowMs];
+    case "past_month":
+      return [nowMs - 30 * DAY_MS, nowMs];
+    case "past_year":
+      return [nowMs - 365 * DAY_MS, nowMs];
+    case "next_week":
+      return [nowMs, nowMs + 7 * DAY_MS];
+    case "next_month":
+      return [nowMs, nowMs + 30 * DAY_MS];
+    case "next_year":
+      return [nowMs, nowMs + 365 * DAY_MS];
+    case "this_week": {
+      const weekday = (new Date(dayStart).getUTCDay() + 6) % 7; // Monday = 0
+      const monday = dayStart - weekday * DAY_MS;
+      return [monday, monday + 7 * DAY_MS - 1];
+    }
+    default:
+      return undefined;
+  }
+}
+
+function evaluate(type, condition, expected, value, nowMs) {
+  if (TEXT_TYPES.includes(type)) {
+    const text = textOf(type, value).toLowerCase();
+    const needle = typeof expected === "string" ? expected.toLowerCase() : "";
+    switch (condition) {
+      case "equals": return text === needle;
+      case "does_not_equal": return text !== needle;
+      case "contains": return text.includes(needle);
+      case "does_not_contain": return !text.includes(needle);
+      case "starts_with": return text.startsWith(needle);
+      case "ends_with": return text.endsWith(needle);
+      case "is_empty": return text.length === 0;
+      case "is_not_empty": return text.length > 0;
+      default: return false;
+    }
+  }
+  if (type === "number") {
+    const empty = value === null || value === undefined;
+    switch (condition) {
+      case "is_empty": return empty;
+      case "is_not_empty": return !empty;
+      case "equals": return !empty && value === expected;
+      case "does_not_equal": return empty || value !== expected;
+      case "greater_than": return !empty && value > expected;
+      case "less_than": return !empty && value < expected;
+      case "greater_than_or_equal_to": return !empty && value >= expected;
+      case "less_than_or_equal_to": return !empty && value <= expected;
+      default: return false;
+    }
+  }
+  if (type === "checkbox") return condition === "equals" ? value === expected : value !== expected;
+  if (type === "select" || type === "status") {
+    const name = value === null ? null : value.name;
+    switch (condition) {
+      case "equals": return name === expected;
+      case "does_not_equal": return name !== expected;
+      case "is_empty": return name === null;
+      case "is_not_empty": return name !== null;
+      default: return false;
+    }
+  }
+  if (type === "multi_select" || type === "people" || type === "relation" || type === "created_by" || type === "last_edited_by") {
+    const items = Array.isArray(value) ? value : value === null || value === undefined ? [] : [value];
+    const keys = items.map((item) => (type === "multi_select" ? item.name : item.id));
+    switch (condition) {
+      case "contains": return keys.includes(expected);
+      case "does_not_contain": return !keys.includes(expected);
+      case "is_empty": return keys.length === 0;
+      case "is_not_empty": return keys.length > 0;
+      default: return false;
+    }
+  }
+  if (DATE_TYPES.includes(type)) {
+    const empty = value === null || value === undefined;
+    if (condition === "is_empty") return empty;
+    if (condition === "is_not_empty") return !empty;
+    if (empty) return false;
+    const window = windowFor(condition, nowMs);
+    if (window !== undefined) {
+      const start = isObject(value) ? value.start : value;
+      const ms = Date.parse(start);
+      if (Number.isNaN(ms)) return false;
+      // Date-only values are compared by UTC calendar day, so "today" falls inside next_week / this_week.
+      if (start.length === 10) return dayIndex(ms) >= dayIndex(window[0]) && dayIndex(ms) <= dayIndex(window[1]);
+      return ms >= window[0] && ms <= window[1];
+    }
+    const order = compareDates(value, expected);
+    if (order === undefined) return false;
+    switch (condition) {
+      case "equals": return order === 0;
+      case "before": return order < 0;
+      case "after": return order > 0;
+      case "on_or_before": return order <= 0;
+      case "on_or_after": return order >= 0;
+      default: return false;
+    }
+  }
+  return false;
+}
+
+function expectedValueValid(type, condition, expected) {
+  if (condition === "is_empty" || condition === "is_not_empty" || windowFor(condition, 0) !== undefined) return isObject(expected) || expected === true;
+  if (TEXT_TYPES.includes(type) || type === "select" || type === "status" || type === "multi_select") return typeof expected === "string";
+  if (type === "number") return typeof expected === "number" && Number.isFinite(expected);
+  if (type === "checkbox") return typeof expected === "boolean";
+  if (DATE_TYPES.includes(type)) return typeof expected === "string" && !Number.isNaN(Date.parse(expected));
+  return typeof expected === "string";
+}
+
+/** Compile a filter object into a predicate over page rows; throws declared VALIDATION_ERRORs. */
+export function compileFilter(context, definitions, filter, path = "filter", depth = 1) {
+  if (!isObject(filter)) return validationError(context, `body failed validation: body.${path} should be an object.`);
+  const compound = filter.and !== undefined ? "and" : filter.or !== undefined ? "or" : undefined;
+  if (compound !== undefined) {
+    if (depth > MAX_DEPTH) return validationError(context, `body failed validation: body.${path}.${compound} nests compound filters deeper than ${MAX_DEPTH} levels.`);
+    const group = filter[compound];
+    if (!Array.isArray(group)) return validationError(context, `body failed validation: body.${path}.${compound} should be an array.`);
+    if (group.length > MAX_GROUP) return validationError(context, `body failed validation: body.${path}.${compound}.length should be ≤ ${MAX_GROUP}, instead was ${group.length}.`);
+    const predicates = group.map((child, index) => compileFilter(context, definitions, child, `${path}.${compound}[${index}]`, depth + 1));
+    return compound === "and" ? (page, nowMs) => predicates.every((predicate) => predicate(page, nowMs)) : (page, nowMs) => predicates.some((predicate) => predicate(page, nowMs));
+  }
+  let type;
+  let read;
+  if (typeof filter.timestamp === "string") {
+    if (filter.timestamp !== "created_time" && filter.timestamp !== "last_edited_time") {
+      return validationError(context, `body failed validation: body.${path}.timestamp should be "created_time" or "last_edited_time", instead was \`${filter.timestamp}\`.`);
+    }
+    type = filter.timestamp;
+    read = (page) => page[type];
+  } else {
+    if (typeof filter.property !== "string") return validationError(context, `body failed validation: body.${path}.property should be a string.`);
+    if (isMangled(filter.property)) return mangledError(context, `body.${path}.property`);
+    const definition = findDefinition(definitions, filter.property);
+    if (definition === undefined) return validationError(context, `Could not find property with name or id: ${filter.property}`);
+    type = definition.type;
+    read = (page) => propertyValue(page, definition);
+  }
+  const filterKey = filter[type] !== undefined ? type : type === "title" && filter.rich_text !== undefined ? "rich_text" : undefined;
+  if (filterKey === undefined || !isObject(filter[filterKey])) {
+    return validationError(context, `body failed validation: body.${path}.${type} should be defined, instead was \`undefined\`.`);
+  }
+  const conditions = Object.keys(filter[filterKey]);
+  if (conditions.length !== 1) return validationError(context, `body failed validation: body.${path}.${filterKey} should contain exactly one condition.`);
+  const condition = conditions[0];
+  const allowed = conditionsFor(type);
+  if (!allowed.includes(condition)) {
+    return validationError(context, `body failed validation: body.${path}.${filterKey}.${condition} is not a supported condition for ${type} properties (supported: ${allowed.join(", ")}).`);
+  }
+  const expected = filter[filterKey][condition];
+  // A filter value carrying U+FFFD is a mangled request, not a literal to match (RECIPE, lenient decoding).
+  if (isMangled(expected)) return mangledError(context, `body.${path}.${filterKey}.${condition}`);
+  if (!expectedValueValid(type, condition, expected)) {
+    return validationError(context, `body failed validation: body.${path}.${filterKey}.${condition} should be a valid ${type} filter value, instead was \`${JSON.stringify(expected)}\`.`);
+  }
+  return (page, nowMs) => evaluate(type, condition, expected, read(page), nowMs);
+}
+
+function sortKey(type, value, definition) {
+  if (value === null || value === undefined) return undefined;
+  if (TEXT_TYPES.includes(type)) {
+    const text = textOf(type, value);
+    return text.length === 0 ? undefined : text.toLowerCase();
+  }
+  if (type === "number") return value;
+  if (type === "checkbox") return value ? 1 : 0;
+  if (type === "select" || type === "status") {
+    const index = definition.config.options.findIndex((option) => option.id === value.id);
+    return index < 0 ? undefined : index;
+  }
+  if (type === "multi_select") return value.length === 0 ? undefined : value[0].name.toLowerCase();
+  if (type === "people" || type === "relation") return value.length === 0 ? undefined : value[0].id;
+  if (type === "created_by" || type === "last_edited_by") return value.id;
+  if (DATE_TYPES.includes(type)) {
+    const ms = Date.parse(isObject(value) ? value.start : value);
+    return Number.isNaN(ms) ? undefined : ms;
+  }
+  return undefined;
+}
+
+/** Compile `sorts` into a comparator; empties sort last, ties keep creation (row-id) order. */
+export function compileSorts(context, definitions, sorts) {
+  if (sorts === undefined) return () => 0;
+  if (!Array.isArray(sorts)) return validationError(context, "body failed validation: body.sorts should be an array.");
+  const keys = sorts.map((sort, index) => {
+    if (!isObject(sort)) return validationError(context, `body failed validation: body.sorts[${index}] should be an object.`);
+    if (sort.direction !== "ascending" && sort.direction !== "descending") {
+      return validationError(context, `body failed validation: body.sorts[${index}].direction should be "ascending" or "descending", instead was \`${shown(sort.direction)}\`.`);
+    }
+    const sign = sort.direction === "ascending" ? 1 : -1;
+    if (typeof sort.timestamp === "string") {
+      if (sort.timestamp !== "created_time" && sort.timestamp !== "last_edited_time") {
+        return validationError(context, `body failed validation: body.sorts[${index}].timestamp should be "created_time" or "last_edited_time".`);
+      }
+      const field = sort.timestamp;
+      return { sign, key: (page) => Date.parse(page[field]) };
+    }
+    if (typeof sort.property !== "string") return validationError(context, `body failed validation: body.sorts[${index}].property should be a string.`);
+    if (isMangled(sort.property)) return mangledError(context, `body.sorts[${index}].property`);
+    const definition = findDefinition(definitions, sort.property);
+    if (definition === undefined) return validationError(context, `Could not find sort property with name or id: ${sort.property}`);
+    return { sign, key: (page) => sortKey(definition.type, propertyValue(page, definition), definition) };
+  });
+  return (left, right) => {
+    for (const { sign, key } of keys) {
+      const a = key(left);
+      const b = key(right);
+      if (a === undefined && b === undefined) continue;
+      if (a === undefined) return 1;
+      if (b === undefined) return -1;
+      if (a < b) return -sign;
+      if (a > b) return sign;
+    }
+    return 0;
+  };
+}

package/firedrill/tools/notion/lib/render.mjs

@@ -0,0 +1,137 @@
+// Notion object rendering (page, database, data source, block, comment, list envelopes). Pure functions
+// over state rows; reads through context only to expand users and child titles.
+import { compactId } from "./ids.mjs";
+import { renderPageProperties, renderSchema, renderUser, userReference } from "./properties.mjs";
+import { plainText } from "./rich-text.mjs";
+import { slug } from "./state.mjs";
+
+export { renderUser };
+
+export function objectUrl(titlePlain, id) {
+  const part = slug(titlePlain);
+  return `https://www.notion.so/${part.length > 0 ? `${part}-` : ""}${compactId(id)}`;
+}
+
+function stamps(row) {
+  return {
+    created_time: row.created_time,
+    last_edited_time: row.last_edited_time,
+    created_by: { object: "user", id: row.created_by.id },
+    last_edited_by: { object: "user", id: row.last_edited_by.id },
+  };
+}
+
+export function renderPage(context, identity, page, filterIds) {
+  return {
+    object: "page",
+    id: page.id,
+    ...stamps(page),
+    cover: page.cover,
+    icon: page.icon,
+    parent: page.parent,
+    archived: page.in_trash,
+    in_trash: page.in_trash,
+    properties: renderPageProperties(context, identity, page, filterIds),
+    url: objectUrl(page.title_plain, page.id),
+    public_url: null,
+  };
+}
+
+export function renderDatabase(context, database) {
+  const sources = database.data_source_ids.map((id) => {
+    const source = context.state.get("data-sources", id);
+    return { id, name: source === null ? "" : source.name };
+  });
+  return {
+    object: "database",
+    id: database.id,
+    ...stamps(database),
+    title: database.title,
+    description: database.description,
+    icon: database.icon,
+    cover: database.cover,
+    parent: database.parent,
+    is_inline: database.is_inline,
+    is_locked: false,
+    archived: database.in_trash,
+    in_trash: database.in_trash,
+    url: objectUrl(database.title_plain, database.id),
+    public_url: null,
+    data_sources: sources,
+  };
+}
+
+export function renderDataSource(context, source) {
+  const database = context.state.get("databases", source.parent.database_id);
+  return {
+    object: "data_source",
+    id: source.id,
+    name: source.name,
+    ...stamps(source),
+    title: source.title,
+    description: source.description,
+    icon: database === null ? null : database.icon,
+    properties: renderSchema(source.properties),
+    parent: source.parent,
+    database_parent: database === null ? { type: "workspace", workspace: true } : database.parent,
+    is_inline: database === null ? false : database.is_inline,
+    archived: source.in_trash,
+    in_trash: source.in_trash,
+    url: objectUrl(plainText(source.title), source.id),
+    public_url: null,
+  };
+}
+
+function blockContent(context, block) {
+  if (block.type === "child_page") {
+    const page = context.state.get("pages", block.id);
+    return { title: page === null ? block.content.title ?? "" : page.title_plain };
+  }
+  if (block.type === "child_database") {
+    const database = context.state.get("databases", block.id);
+    return { title: database === null ? block.content.title ?? "" : database.title_plain };
+  }
+  return block.content;
+}
+
+export function renderBlock(context, block) {
+  return {
+    object: "block",
+    id: block.id,
+    parent: block.parent,
+    ...stamps(block),
+    has_children: block.has_children,
+    archived: block.in_trash,
+    in_trash: block.in_trash,
+    type: block.type,
+    [block.type]: blockContent(context, block),
+  };
+}
+
+export function renderComment(context, identity, comment) {
+  return {
+    object: "comment",
+    id: comment.id,
+    parent: comment.parent,
+    discussion_id: comment.discussion_id,
+    created_time: comment.created_time,
+    last_edited_time: comment.last_edited_time,
+    created_by: userReference(context, identity, comment.created_by.id),
+    rich_text: comment.rich_text,
+    attachments: [],
+    display_name: comment.display_name,
+  };
+}
+
+/** Notion's paginated list envelope (`type` names the element kind; `request_status` on query/search). */
+export function listResponse(type, results, pagination, extra = {}) {
+  return {
+    object: "list",
+    results,
+    next_cursor: pagination.next_cursor,
+    has_more: pagination.has_more,
+    type,
+    [type]: {},
+    ...extra,
+  };
+}

package/firedrill/tools/notion/lib/rich-text.mjs

@@ -0,0 +1,134 @@
+// Notion rich text: validation of request items (`text`, `mention`) and the normalised stored/returned form.
+import { normalizeId } from "./ids.mjs";
+import { jsonBytes, OBJECT_BUDGET_BYTES } from "./size.mjs";
+import { shown, validationError } from "./state.mjs";
+
+export const COLORS = Object.freeze([
+  "default", "gray", "brown", "orange", "yellow", "green", "blue", "purple", "pink", "red",
+  "gray_background", "brown_background", "orange_background", "yellow_background", "green_background",
+  "blue_background", "purple_background", "pink_background", "red_background",
+]);
+const MAX_ITEMS = 100;
+const MAX_CONTENT = 2000;
+const MAX_URL = 2000;
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$/;
+
+export function isDateString(value) {
+  return typeof value === "string" && (DATE_ONLY.test(value) || DATE_TIME.test(value));
+}
+
+export function defaultAnnotations() {
+  return { bold: false, italic: false, strikethrough: false, underline: false, code: false, color: "default" };
+}
+
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function annotations(context, value, path) {
+  const result = defaultAnnotations();
+  if (value === undefined) return result;
+  if (!isObject(value)) return validationError(context, `body failed validation: body.${path}.annotations should be an object.`);
+  for (const key of ["bold", "italic", "strikethrough", "underline", "code"]) {
+    if (value[key] === undefined) continue;
+    if (typeof value[key] !== "boolean") return validationError(context, `body failed validation: body.${path}.annotations.${key} should be a boolean.`);
+    result[key] = value[key];
+  }
+  if (value.color !== undefined) {
+    if (!COLORS.includes(value.color)) return validationError(context, `body failed validation: body.${path}.annotations.color should be a valid color, instead was \`${shown(value.color)}\`.`);
+    result.color = value.color;
+  }
+  return result;
+}
+
+export function textItem(content, options = {}) {
+  const link = options.link ?? null;
+  return {
+    type: "text",
+    text: { content, link },
+    annotations: { ...defaultAnnotations(), ...(options.annotations ?? {}) },
+    plain_text: content,
+    href: link === null ? null : link.url,
+  };
+}
+
+/** Validate and normalise a rich text array from a request body. `path` names the field for messages. */
+export function normalizeRichText(context, value, path) {
+  if (!Array.isArray(value)) return validationError(context, `body failed validation: body.${path} should be an array, instead was \`${JSON.stringify(value)}\`.`);
+  if (value.length > MAX_ITEMS) return validationError(context, `body failed validation: body.${path}.length should be ≤ ${MAX_ITEMS}, instead was ${value.length}.`);
+  const items = [];
+  // Rendered text appears twice per item (text.content and plain_text), so the array is bounded by the encoded bytes
+  // it renders to, measured as items are admitted; one stored block, page or comment always fits one response.
+  let bytes = 0;
+  const admit = (normalized) => {
+    bytes += jsonBytes(normalized) + 1;
+    if (bytes > OBJECT_BUDGET_BYTES) {
+      return validationError(context, `body failed validation: body.${path} would be more than ${OBJECT_BUDGET_BYTES} bytes once rendered (text.content and plain_text both carry the text).`);
+    }
+    items.push(normalized);
+  };
+  for (let index = 0; index < value.length; index += 1) {
+    const item = value[index];
+    const itemPath = `${path}[${index}]`;
+    if (!isObject(item)) return validationError(context, `body failed validation: body.${itemPath} should be an object.`);
+    const type = item.type ?? (item.text !== undefined ? "text" : item.mention !== undefined ? "mention" : undefined);
+    if (type === "text") {
+      if (!isObject(item.text) || typeof item.text.content !== "string") {
+        return validationError(context, `body failed validation: body.${itemPath}.text.content should be a string.`);
+      }
+      if (item.text.content.length > MAX_CONTENT) {
+        return validationError(context, `body failed validation: body.${itemPath}.text.content.length should be ≤ ${MAX_CONTENT}, instead was ${item.text.content.length}.`);
+      }
+      let link = null;
+      if (item.text.link !== undefined && item.text.link !== null) {
+        if (!isObject(item.text.link) || typeof item.text.link.url !== "string" || item.text.link.url.length === 0) {
+          return validationError(context, `body failed validation: body.${itemPath}.text.link.url should be a string.`);
+        }
+        if (item.text.link.url.length > MAX_URL) {
+          return validationError(context, `body failed validation: body.${itemPath}.text.link.url.length should be ≤ ${MAX_URL}, instead was ${item.text.link.url.length}.`);
+        }
+        link = { url: item.text.link.url };
+      }
+      admit(textItem(item.text.content, { link, annotations: annotations(context, item.annotations, itemPath) }));
+      continue;
+    }
+    if (type === "mention") {
+      const mention = item.mention;
+      if (!isObject(mention)) return validationError(context, `body failed validation: body.${itemPath}.mention should be an object.`);
+      const mentionType = mention.type ?? (mention.user !== undefined ? "user" : mention.page !== undefined ? "page" : mention.date !== undefined ? "date" : undefined);
+      const base = { type: "mention", annotations: annotations(context, item.annotations, itemPath), href: null };
+      if (mentionType === "user") {
+        const id = isObject(mention.user) ? normalizeId(mention.user.id) : undefined;
+        const user = id === undefined ? null : context.state.get("users", id);
+        if (user === null) return validationError(context, `body failed validation: body.${itemPath}.mention.user.id should be the id of a user in the workspace.`);
+        admit({ ...base, mention: { type: "user", user: { object: "user", id: user.id } }, plain_text: `@${user.name}` });
+        continue;
+      }
+      if (mentionType === "page") {
+        const id = isObject(mention.page) ? normalizeId(mention.page.id) : undefined;
+        const page = id === undefined ? null : context.state.get("pages", id);
+        if (page === null) return validationError(context, `body failed validation: body.${itemPath}.mention.page.id should be the id of a page in the workspace.`);
+        admit({ ...base, mention: { type: "page", page: { id: page.id } }, plain_text: page.title_plain, href: `https://www.notion.so/${page.id.replaceAll("-", "")}` });
+        continue;
+      }
+      if (mentionType === "date") {
+        const date = mention.date;
+        if (!isObject(date) || !isDateString(date.start) || (date.end !== undefined && date.end !== null && !isDateString(date.end))) {
+          return validationError(context, `body failed validation: body.${itemPath}.mention.date.start should be a valid ISO 8601 date string.`);
+        }
+        const end = date.end ?? null;
+        const timeZone = typeof date.time_zone === "string" ? date.time_zone : null;
+        admit({ ...base, mention: { type: "date", date: { start: date.start, end, time_zone: timeZone } }, plain_text: end === null ? date.start : `${date.start} → ${end}` });
+        continue;
+      }
+      return validationError(context, `body failed validation: body.${itemPath}.mention.type should be "user", "page" or "date", instead was \`${shown(mentionType)}\`.`);
+    }
+    return validationError(context, `body failed validation: body.${itemPath}.type should be "text" or "mention", instead was \`${shown(type)}\`.`);
+  }
+  return items;
+}
+
+export function plainText(items) {
+  return items.map((item) => item.plain_text).join("");
+}

package/firedrill/tools/notion/lib/size.mjs

@@ -0,0 +1,44 @@
+// UTF-8 byte accounting for response budgets. The framework refuses an HTTP response body over 1 MiB, so every
+// rendered object is bounded when it is written and every list page is filled by encoded bytes. No module state.
+
+/** Hard bound on one encoded response body (the framework's cap is 1,048,576 bytes; the rest is headroom). */
+export const MAX_RESPONSE_BYTES = 1_000_000;
+/** Encoded bytes of `results` one list page may fill before it ends early with a real next_cursor. */
+export const PAGE_BUDGET_BYTES = 900_000;
+/** Rendered size a stored page, block, comment, database or data source may reach when it is written. */
+export const OBJECT_BUDGET_BYTES = 800_000;
+/** Rendered size of one data source schema (its property keys are repeated in every page of the data source). */
+export const SCHEMA_BUDGET_BYTES = 150_000;
+/**
+ * Worst-case bytes a data source schema adds to the rendering of each of its pages (every property with an empty
+ * value, created_by / last_edited_by as the widest expanded user). A page is bounded by OBJECT_BUDGET_BYTES when it
+ * is written, including the schema of that moment; a later schema change adds at most this much to it, so
+ * OBJECT_BUDGET_BYTES + SCHEMA_PAGE_BUDGET_BYTES stays under one list item (MAX_RESPONSE_BYTES - 4096).
+ */
+export const SCHEMA_PAGE_BUDGET_BYTES = 150_000;
+/** Block content (rich text, captions, urls) one create or append request may add. */
+export const REQUEST_CONTENT_BYTES = 900_000;
+
+/** UTF-8 length of a string computed from its code points (1, 2, 3 or 4 bytes each). */
+export function utf8Length(text) {
+  let bytes = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    const unit = text.charCodeAt(index);
+    if (unit < 0x80) bytes += 1;
+    else if (unit < 0x800) bytes += 2;
+    else if (unit >= 0xd800 && unit <= 0xdbff && index + 1 < text.length) {
+      const next = text.charCodeAt(index + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        index += 1;
+      } else bytes += 3;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+/** Encoded bytes of a value as it is sent: JSON text (escapes included) measured in UTF-8. */
+export function jsonBytes(value) {
+  const text = JSON.stringify(value);
+  return typeof text === "string" ? utf8Length(text) : 0;
+}