ocean-brain 0.13.2 → 0.14.0

package/server/dist/features/note/http/mcp.js

@@ -1,466 +1,18 @@
-import { createNoteFromMarkdown, InvalidNoteAuthoringInputError } from "../../../features/note/services/authoring.js";
-import { deleteNoteById } from "../../../features/note/services/cleanup.js";
 import {
-  appendNoteMarkdown,
-  patchNoteMarkdown,
-  replaceNoteMarkdown,
-  updateNoteMetadata
-} from "../../../features/note/services/markdown-intent-write.js";
-import models from "../../../models.js";
-import { createAppError } from "../../../modules/error-handler.js";
-import { emitServerEvent } from "../../../modules/server-events.js";
-const NOTE_LAYOUTS = /* @__PURE__ */ new Set(["narrow", "wide", "full"]);
-const POSITION_HINTS = /* @__PURE__ */ new Set(["first", "last"]);
-const PRESERVATION_POLICIES = /* @__PURE__ */ new Set([true, false, "warn"]);
-const isRecord = (value) => {
-  return typeof value === "object" && value !== null;
-};
-const resolveNoteLayout = (value) => {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (typeof value === "string" && NOTE_LAYOUTS.has(value)) {
-    return value;
-  }
-  return null;
-};
-const resolveOptionalString = (value, code, message) => {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (typeof value === "string") {
-    return value;
-  }
-  throw createAppError(400, code, message);
-};
-const resolveMetadataPropertyPatch = (value) => {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (!isRecord(value)) {
-    throw createAppError(400, "INVALID_NOTE_PROPERTIES", "Properties patch must be an object.");
-  }
-  const set = value.set === void 0 ? void 0 : Array.isArray(value.set) ? value.set.map((item) => {
-    if (!isRecord(item) || typeof item.key !== "string" || typeof item.value !== "string") {
-      throw createAppError(
-        400,
-        "INVALID_NOTE_PROPERTIES",
-        "Property set items must include string key and value fields."
-      );
-    }
-    return {
-      key: item.key,
-      value: item.value
-    };
-  }) : null;
-  if (set === null) {
-    throw createAppError(400, "INVALID_NOTE_PROPERTIES", "Property set must be an array.");
-  }
-  const deleteKeys = value.deleteKeys === void 0 ? void 0 : Array.isArray(value.deleteKeys) ? value.deleteKeys.map((key) => {
-    if (typeof key !== "string") {
-      throw createAppError(400, "INVALID_NOTE_PROPERTIES", "Property deleteKeys must be strings.");
-    }
-    return key;
-  }) : null;
-  if (deleteKeys === null) {
-    throw createAppError(400, "INVALID_NOTE_PROPERTIES", "Property deleteKeys must be an array.");
-  }
-  return {
-    ...set !== void 0 ? { set } : {},
-    ...deleteKeys !== void 0 ? { deleteKeys } : {}
-  };
-};
-const resolvePositiveNoteId = (value) => {
-  const noteId = Number(value);
-  if (!Number.isInteger(noteId) || noteId <= 0) {
-    throw createAppError(400, "INVALID_NOTE_ID", "A valid note id is required.");
-  }
-  return noteId;
-};
-const serializeNoteWriteBaseline = (note) => {
-  return {
-    id: String(note.id),
-    updatedAt: note.updatedAt instanceof Date ? note.updatedAt.toISOString() : note.updatedAt
-  };
-};
-const isNonNegativeInteger = (value) => {
-  return typeof value === "number" && Number.isInteger(value) && value >= 0;
-};
-const isPositiveInteger = (value) => {
-  return typeof value === "number" && Number.isInteger(value) && value > 0;
-};
-const resolveMarkdownWritePolicy = (value) => {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (!isRecord(value)) {
-    throw createAppError(400, "INVALID_MARKDOWN_POLICY", "Markdown write policy must be an object.");
-  }
-  const policy = {};
-  if (value.allowNoop !== void 0) {
-    if (typeof value.allowNoop !== "boolean") {
-      throw createAppError(400, "INVALID_MARKDOWN_POLICY", "allowNoop must be a boolean.");
-    }
-    policy.allowNoop = value.allowNoop;
-  }
-  if (value.preserveTags !== void 0) {
-    if (!PRESERVATION_POLICIES.has(value.preserveTags)) {
-      throw createAppError(400, "INVALID_MARKDOWN_POLICY", "preserveTags must be boolean or warn.");
-    }
-    policy.preserveTags = value.preserveTags;
-  }
-  if (value.preserveReferences !== void 0) {
-    if (!PRESERVATION_POLICIES.has(value.preserveReferences)) {
-      throw createAppError(400, "INVALID_MARKDOWN_POLICY", "preserveReferences must be boolean or warn.");
-    }
-    policy.preserveReferences = value.preserveReferences;
-  }
-  return policy;
-};
-const resolvePatchSelector = (value) => {
-  if (!isRecord(value)) {
-    throw createAppError(400, "INVALID_PATCH_SELECTOR", "Patch selector must be an object.");
-  }
-  if (value.type === "exact_text") {
-    if (typeof value.text !== "string") {
-      throw createAppError(400, "INVALID_PATCH_SELECTOR", "Exact text selector requires text.");
-    }
-    return {
-      type: "exact_text",
-      text: value.text,
-      ...value.before !== void 0 ? {
-        before: resolveOptionalString(
-          value.before,
-          "INVALID_PATCH_SELECTOR",
-          "Selector before must be a string."
-        )
-      } : {},
-      ...value.after !== void 0 ? {
-        after: resolveOptionalString(
-          value.after,
-          "INVALID_PATCH_SELECTOR",
-          "Selector after must be a string."
-        )
-      } : {}
-    };
-  }
-  if (value.type === "match_candidate") {
-    const { text, matchIndex, lineStart, matchSha256, surroundingHash, positionHint } = value;
-    if (typeof text !== "string" || !isNonNegativeInteger(matchIndex) || !isPositiveInteger(lineStart) || typeof matchSha256 !== "string" || typeof surroundingHash !== "string") {
-      throw createAppError(400, "INVALID_PATCH_SELECTOR", "Match candidate selector has invalid fields.");
-    }
-    if (positionHint !== void 0 && !POSITION_HINTS.has(String(positionHint))) {
-      throw createAppError(400, "INVALID_PATCH_SELECTOR", "positionHint must be first or last.");
-    }
-    return {
-      type: "match_candidate",
-      text,
-      matchIndex,
-      lineStart,
-      matchSha256,
-      surroundingHash,
-      ...positionHint ? { positionHint } : {}
-    };
-  }
-  throw createAppError(400, "INVALID_PATCH_SELECTOR", "Unsupported patch selector type.");
-};
-const resolvePatchOperation = (value) => {
-  if (!isRecord(value)) {
-    throw createAppError(400, "INVALID_PATCH_OPERATION", "Patch operation must be an object.");
-  }
-  if (value.type === "replace") {
-    if (typeof value.replacement !== "string") {
-      throw createAppError(400, "INVALID_PATCH_OPERATION", "Replace operation requires replacement.");
-    }
-    return {
-      type: "replace",
-      replacement: value.replacement
-    };
-  }
-  if (value.type === "insert_before" || value.type === "insert_after") {
-    if (typeof value.insertion !== "string") {
-      throw createAppError(400, "INVALID_PATCH_OPERATION", "Insert operation requires insertion.");
-    }
-    return {
-      type: value.type,
-      insertion: value.insertion
-    };
-  }
-  throw createAppError(400, "INVALID_PATCH_OPERATION", "Unsupported patch operation type.");
-};
-const resolveAppendPlacement = (value) => {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (!isRecord(value)) {
-    throw createAppError(400, "INVALID_APPEND_PLACEMENT", "Append placement must be an object.");
-  }
-  if (value.type === "end") {
-    return { type: "end" };
-  }
-  if (value.type === "after_heading") {
-    if (typeof value.heading !== "string") {
-      throw createAppError(400, "INVALID_APPEND_PLACEMENT", "after_heading placement requires heading.");
-    }
-    const { heading, level } = value;
-    if (typeof heading !== "string") {
-      throw createAppError(400, "INVALID_APPEND_PLACEMENT", "after_heading placement requires heading.");
-    }
-    if (level !== void 0 && (typeof level !== "number" || !Number.isInteger(level) || level < 1 || level > 6)) {
-      throw createAppError(400, "INVALID_APPEND_PLACEMENT", "Heading level must be an integer from 1 to 6.");
-    }
-    return {
-      type: "after_heading",
-      heading,
-      ...level !== void 0 ? { level } : {}
-    };
-  }
-  throw createAppError(400, "INVALID_APPEND_PLACEMENT", "Unsupported append placement type.");
-};
-const resolveSeparator = (value) => {
-  if (value === void 0) {
-    return void 0;
-  }
-  if (value === "\n" || value === "\n\n") {
-    return value;
-  }
-  throw createAppError(400, "INVALID_SEPARATOR", 'Separator must be "\\n" or "\\n\\n".');
-};
-const createMcpCreateNoteHandler = (createNote = createNoteFromMarkdown, emitEvent = emitServerEvent) => {
-  return async (req, reply) => {
-    const { title, markdown, layout } = req.body ?? {};
-    const resolvedLayout = resolveNoteLayout(layout);
-    if (typeof title !== "string") {
-      throw createAppError(400, "INVALID_NOTE_TITLE", "A note title is required.");
-    }
-    if (markdown !== void 0 && typeof markdown !== "string") {
-      throw createAppError(400, "INVALID_NOTE_MARKDOWN", "Note markdown must be a string.");
-    }
-    if (layout !== void 0 && resolvedLayout === null) {
-      throw createAppError(400, "INVALID_NOTE_LAYOUT", "Note layout must be one of narrow, wide, or full.");
-    }
-    try {
-      const note = await createNote({
-        title,
-        ...markdown !== void 0 ? { markdown } : {},
-        ...resolvedLayout ? { layout: resolvedLayout } : {}
-      });
-      emitEvent({
-        type: "mcp.note.created",
-        source: "mcp",
-        noteId: note.id,
-        updatedAt: note.updatedAt
-      });
-      return reply.status(200).send({
-        created: true,
-        note
-      });
-    } catch (error) {
-      if (error instanceof InvalidNoteAuthoringInputError) {
-        throw createAppError(400, "INVALID_NOTE_INPUT", error.message);
-      }
-      throw error;
-    }
-  };
-};
-const createMcpNoteWriteBaselineHandler = (findNoteBaseline = async (id) => models.note.findUnique({
-  where: { id },
-  select: {
-    id: true,
-    updatedAt: true
-  }
-})) => {
-  return async (req, reply) => {
-    const noteId = resolvePositiveNoteId(req.body?.id);
-    const note = await findNoteBaseline(noteId);
-    if (!note) {
-      throw createAppError(404, "NOTE_NOT_FOUND", "The requested note was not found.");
-    }
-    return reply.status(200).send({
-      note: serializeNoteWriteBaseline(note)
-    });
-  };
-};
-const createMcpPatchNoteMarkdownHandler = (patchMarkdown = patchNoteMarkdown, emitEvent = emitServerEvent) => {
-  return async (req, reply) => {
-    const { id, expectedUpdatedAt, baseMarkdownSha256, intent, selector, operation, policy } = req.body ?? {};
-    const noteId = resolvePositiveNoteId(id);
-    const resolvedExpectedUpdatedAt = resolveOptionalString(
-      expectedUpdatedAt,
-      "INVALID_NOTE_VERSION",
-      "expectedUpdatedAt must be a string."
-    );
-    const resolvedBaseMarkdownSha256 = resolveOptionalString(
-      baseMarkdownSha256,
-      "INVALID_MARKDOWN_HASH",
-      "baseMarkdownSha256 must be a string."
-    );
-    if (typeof intent !== "string") {
-      throw createAppError(400, "INVALID_PATCH_INTENT", "Patch intent must be a string.");
-    }
-    const result = await patchMarkdown({
-      id: noteId,
-      expectedUpdatedAt: resolvedExpectedUpdatedAt,
-      baseMarkdownSha256: resolvedBaseMarkdownSha256,
-      intent,
-      selector: resolvePatchSelector(selector),
-      operation: resolvePatchOperation(operation),
-      policy: resolveMarkdownWritePolicy(policy)
-    });
-    if (result.status === "applied") {
-      emitEvent({
-        type: "mcp.note.updated",
-        source: "mcp",
-        noteId: result.note.id,
-        updatedAt: result.note.updatedAt
-      });
-    }
-    return reply.status(200).send(result);
-  };
-};
-const createMcpAppendNoteMarkdownHandler = (appendMarkdown = appendNoteMarkdown, emitEvent = emitServerEvent) => {
-  return async (req, reply) => {
-    const { id, expectedUpdatedAt, baseMarkdownSha256, intent, insertion, placement, separator, policy } = req.body ?? {};
-    const noteId = resolvePositiveNoteId(id);
-    const resolvedExpectedUpdatedAt = resolveOptionalString(
-      expectedUpdatedAt,
-      "INVALID_NOTE_VERSION",
-      "expectedUpdatedAt must be a string."
-    );
-    const resolvedBaseMarkdownSha256 = resolveOptionalString(
-      baseMarkdownSha256,
-      "INVALID_MARKDOWN_HASH",
-      "baseMarkdownSha256 must be a string."
-    );
-    if (typeof intent !== "string") {
-      throw createAppError(400, "INVALID_APPEND_INTENT", "Append intent must be a string.");
-    }
-    if (typeof insertion !== "string") {
-      throw createAppError(400, "INVALID_APPEND_INSERTION", "Append insertion must be a string.");
-    }
-    const result = await appendMarkdown({
-      id: noteId,
-      expectedUpdatedAt: resolvedExpectedUpdatedAt,
-      baseMarkdownSha256: resolvedBaseMarkdownSha256,
-      intent,
-      insertion,
-      placement: resolveAppendPlacement(placement),
-      separator: resolveSeparator(separator),
-      policy: resolveMarkdownWritePolicy(policy)
-    });
-    if (result.status === "applied") {
-      emitEvent({
-        type: "mcp.note.updated",
-        source: "mcp",
-        noteId: result.note.id,
-        updatedAt: result.note.updatedAt
-      });
-    }
-    return reply.status(200).send(result);
-  };
-};
-const createMcpReplaceNoteMarkdownHandler = (replaceMarkdown = replaceNoteMarkdown, emitEvent = emitServerEvent) => {
-  return async (req, reply) => {
-    const { id, expectedUpdatedAt, baseMarkdownSha256, intent, replacement, policy } = req.body ?? {};
-    const noteId = resolvePositiveNoteId(id);
-    const resolvedExpectedUpdatedAt = resolveOptionalString(
-      expectedUpdatedAt,
-      "INVALID_NOTE_VERSION",
-      "expectedUpdatedAt must be a string."
-    );
-    const resolvedBaseMarkdownSha256 = resolveOptionalString(
-      baseMarkdownSha256,
-      "INVALID_MARKDOWN_HASH",
-      "baseMarkdownSha256 must be a string."
-    );
-    if (typeof intent !== "string") {
-      throw createAppError(400, "INVALID_REPLACE_INTENT", "Replace intent must be a string.");
-    }
-    if (typeof replacement !== "string") {
-      throw createAppError(400, "INVALID_REPLACE_MARKDOWN", "Replacement markdown must be a string.");
-    }
-    const result = await replaceMarkdown({
-      id: noteId,
-      expectedUpdatedAt: resolvedExpectedUpdatedAt,
-      baseMarkdownSha256: resolvedBaseMarkdownSha256,
-      intent,
-      replacement,
-      policy: resolveMarkdownWritePolicy(policy)
-    });
-    if (result.status === "applied") {
-      emitEvent({
-        type: "mcp.note.updated",
-        source: "mcp",
-        noteId: result.note.id,
-        updatedAt: result.note.updatedAt
-      });
-    }
-    return reply.status(200).send(result);
-  };
-};
-const createMcpUpdateNoteMetadataHandler = (updateMetadata = updateNoteMetadata, emitEvent = emitServerEvent) => {
-  return async (req, reply) => {
-    const { id, expectedUpdatedAt, title, layout, properties } = req.body ?? {};
-    const noteId = resolvePositiveNoteId(id);
-    const resolvedLayout = resolveNoteLayout(layout);
-    const resolvedProperties = resolveMetadataPropertyPatch(properties);
-    if (typeof expectedUpdatedAt !== "string") {
-      throw createAppError(400, "INVALID_NOTE_VERSION", "expectedUpdatedAt must be a string.");
-    }
-    if (title !== void 0 && typeof title !== "string") {
-      throw createAppError(400, "INVALID_NOTE_TITLE", "Note title must be a string.");
-    }
-    if (layout !== void 0 && resolvedLayout === null) {
-      throw createAppError(400, "INVALID_NOTE_LAYOUT", "Note layout must be one of narrow, wide, or full.");
-    }
-    if (title === void 0 && layout === void 0 && resolvedProperties === void 0) {
-      throw createAppError(400, "INVALID_NOTE_INPUT", "At least one metadata field must be provided.");
-    }
-    const result = await updateMetadata({
-      id: noteId,
-      expectedUpdatedAt,
-      ...title !== void 0 ? { title } : {},
-      ...resolvedLayout ? { layout: resolvedLayout } : {},
-      ...resolvedProperties !== void 0 ? { properties: resolvedProperties } : {}
-    });
-    if (result.status === "applied") {
-      emitEvent({
-        type: "mcp.note.updated",
-        source: "mcp",
-        noteId: result.note.id,
-        updatedAt: result.note.updatedAt
-      });
-    }
-    return reply.status(200).send(result);
-  };
-};
-const createMcpDeleteNoteHandler = (deleteNote = deleteNoteById, emitEvent = emitServerEvent) => {
-  return async (req, reply) => {
-    const id = Number(req.body?.id);
-    if (!Number.isInteger(id) || id <= 0) {
-      throw createAppError(400, "INVALID_NOTE_ID", "A valid note id is required.");
-    }
-    const deletedNote = await deleteNote(id);
-    if (!deletedNote) {
-      throw createAppError(404, "NOTE_NOT_FOUND", "The requested note was not found.");
-    }
-    emitEvent({
-      type: "mcp.note.deleted",
-      source: "mcp",
-      noteId: deletedNote.id
-    });
-    return reply.status(200).send({
-      deleted: true,
-      note: deletedNote
-    });
-  };
-};
+  createAppendNoteMarkdownHandler,
+  createCreateNoteHandler,
+  createDeleteNoteHandler,
+  createNoteWriteBaselineHandler,
+  createPatchNoteMarkdownHandler,
+  createReplaceNoteMarkdownHandler,
+  createUpdateNoteMetadataHandler
+} from "./authoring.js";
 export {
-  createMcpAppendNoteMarkdownHandler,
-  createMcpCreateNoteHandler,
-  createMcpDeleteNoteHandler,
-  createMcpNoteWriteBaselineHandler,
-  createMcpPatchNoteMarkdownHandler,
-  createMcpReplaceNoteMarkdownHandler,
-  createMcpUpdateNoteMetadataHandler
+  createAppendNoteMarkdownHandler as createMcpAppendNoteMarkdownHandler,
+  createCreateNoteHandler as createMcpCreateNoteHandler,
+  createDeleteNoteHandler as createMcpDeleteNoteHandler,
+  createNoteWriteBaselineHandler as createMcpNoteWriteBaselineHandler,
+  createPatchNoteMarkdownHandler as createMcpPatchNoteMarkdownHandler,
+  createReplaceNoteMarkdownHandler as createMcpReplaceNoteMarkdownHandler,
+  createUpdateNoteMetadataHandler as createMcpUpdateNoteMetadataHandler
 };

package/server/dist/features/note/services/authoring.js

@@ -1,6 +1,12 @@
 import models from "../../../models.js";
 import { extractTagIdsFromContentJson, markdownToBlocksJson } from "../../../modules/blocknote.js";
 import { replaceNoteReferences } from "./note-reference-index.js";
+import {
+  resolveNotePropertiesPatchValueTypes,
+  serializeNoteProperties,
+  setNotePropertyValues,
+  validateNotePropertiesPatchValues
+} from "./properties.js";
 import { buildNoteSearchProjection } from "./search.js";
 class InvalidNoteAuthoringInputError extends Error {
   constructor(message) {
@@ -11,6 +17,7 @@ class InvalidNoteAuthoringInputError extends Error {
 const PLACEHOLDER_PREFIX = "{%";
 const PLACEHOLDER_SUFFIX = "%}";
 const serializeNote = (note) => ({
+  ...note.properties ? { properties: note.properties } : {},
   id: String(note.id),
   title: note.title,
   layout: note.layout,
@@ -49,6 +56,7 @@ const createNoteAuthoringService = (deps) => {
       if (!title) {
         throw new InvalidNoteAuthoringInputError("A note title is required.");
       }
+      const properties = input.properties ? await deps.validateProperties(input.properties) : void 0;
       const replacedTitle = await replacePlaceholders(title);
       const replacedMarkdown = await replacePlaceholders(input.markdown ?? "");
       const content = await deps.parseMarkdownToContentJson(replacedMarkdown);
@@ -57,6 +65,7 @@ const createNoteAuthoringService = (deps) => {
         title: replacedTitle,
         content,
         tagIds,
+        ...properties ? { properties } : {},
         ...input.layout ? { layout: input.layout } : {}
       });
       return serializeNote(note);
@@ -64,6 +73,7 @@ const createNoteAuthoringService = (deps) => {
   };
 };
 const defaultNoteAuthoringService = createNoteAuthoringService({
+  validateProperties: async (patch) => validateNotePropertiesPatchValues(await resolveNotePropertiesPatchValueTypes(patch)),
   createNote: async (input) => {
     return models.$transaction(async (tx) => {
       const note = await tx.note.create({
@@ -78,8 +88,14 @@ const defaultNoteAuthoringService = createNoteAuthoringService({
           ...input.tagIds ? { tags: { connect: input.tagIds.map((id) => ({ id: Number(id) })) } } : {}
         }
       });
+      if (input.properties) await setNotePropertyValues(tx, note.id, input.properties);
       await replaceNoteReferences(tx, note.id, input.content);
-      return note;
+      const properties = await tx.noteProperty.findMany({
+        where: { noteId: note.id },
+        include: { definition: true, option: true },
+        orderBy: { definition: { key: "asc" } }
+      });
+      return { ...note, properties: serializeNoteProperties(properties) };
     });
   },
   findPlaceholders: async (templates) => {

package/server/dist/features/note/services/markdown-intent-write.js

@@ -167,6 +167,7 @@ const applyMarkdownPlan = async (deps, input) => {
   }
   return {
     status: "applied",
+    warnings: input.plan.warnings,
     note: {
       id: String(updateResult.note.id),
       updatedAt: updateResult.note.updatedAt.toISOString()

package/server/dist/features/note/services/markdown-read.js

@@ -0,0 +1,85 @@
+const boundary = (text, index) => index > 0 && /[\uDC00-\uDFFF]/.test(text[index] ?? "") && /[\uD800-\uDBFF]/.test(text[index - 1]) ? index - 1 : index;
+const headingsIn = (markdown) => {
+  const headings = [];
+  let fence = null;
+  for (const line of markdown.matchAll(/^.*(?:\n|$)/gm)) {
+    if (!line[0]) continue;
+    const fenceMatch = /^ {0,3}(`{3,}|~{3,})/.exec(line[0]);
+    if (fenceMatch) {
+      const marker = fenceMatch[1];
+      if (!fence) fence = { character: marker[0], length: marker.length };
+      else if (marker[0] === fence.character && marker.length >= fence.length && line[0].slice(fenceMatch[0].length).trim() === "")
+        fence = null;
+      continue;
+    }
+    if (fence) continue;
+    const heading = /^ {0,3}(#{1,6})[ \t]+(.+?)[ \t]*(?:\r?\n)?$/.exec(line[0]);
+    if (heading)
+      headings.push({
+        heading: heading[2].replace(/[ \t]+#+[ \t]*$/, "").trim(),
+        level: heading[1].length,
+        start: line.index,
+        end: markdown.length
+      });
+  }
+  return headings.map((heading, index) => ({
+    ...heading,
+    end: headings.slice(index + 1).find((next) => next.level <= heading.level)?.start ?? markdown.length
+  }));
+};
+const readMarkdownRange = (markdown, updatedAt, input) => {
+  const maxLength = input.maxLength ?? 1e3;
+  const offset = input.offset ?? 0;
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(maxLength) || maxLength < 0) {
+    throw new Error("offset and maxLength must be nonnegative integers.");
+  }
+  if (input.heading !== void 0 && input.offset !== void 0)
+    throw new Error("Use either heading or offset, not both.");
+  const empty = { markdown: "", contentRange: null, candidates: [] };
+  if (input.expectedUpdatedAt !== void 0) {
+    const expected = /^\d+$/.test(input.expectedUpdatedAt) ? Number(input.expectedUpdatedAt) : Date.parse(input.expectedUpdatedAt);
+    if (expected !== updatedAt.getTime())
+      return {
+        ...empty,
+        status: "failed",
+        reason: "NOTE_VERSION_CONFLICT",
+        message: "The note changed. Start a new read using its current updatedAt."
+      };
+  }
+  let start = boundary(markdown, Math.min(offset, markdown.length));
+  let sectionEnd = markdown.length;
+  if (input.heading !== void 0) {
+    const candidates = headingsIn(markdown).filter((heading) => heading.heading === input.heading);
+    if (candidates.length !== 1)
+      return {
+        ...empty,
+        status: candidates.length ? "needs_disambiguation" : "failed",
+        reason: candidates.length ? "HEADING_AMBIGUOUS" : "HEADING_NOT_FOUND",
+        message: candidates.length ? "Use a candidate start as offset to select a heading." : "Exact heading text was not found.",
+        candidates
+      };
+    start = candidates[0].start;
+    sectionEnd = candidates[0].end;
+  }
+  let end = maxLength === 0 ? sectionEnd : boundary(markdown, Math.min(start + maxLength, sectionEnd));
+  if (end === start && start < sectionEnd) end = Math.min(start + 2, sectionEnd);
+  const hasMore = end < sectionEnd;
+  return {
+    status: "read",
+    reason: null,
+    message: null,
+    candidates: [],
+    markdown: markdown.slice(start, end),
+    contentRange: {
+      start,
+      end,
+      totalLength: markdown.length,
+      sectionEnd,
+      hasMore,
+      nextOffset: hasMore ? end : null
+    }
+  };
+};
+export {
+  readMarkdownRange
+};