feat(document-api): hyperlinks commands

apps/cli/scripts/export-sdk-contract.ts

@@ -156,6 +156,12 @@ const INTENT_NAMES = {
   'doc.toc.listEntries': 'list_table_of_contents_entries',
   'doc.toc.getEntry': 'get_table_of_contents_entry',
   'doc.toc.editEntry': 'edit_table_of_contents_entry',
+  'doc.hyperlinks.list': 'list_hyperlinks',
+  'doc.hyperlinks.get': 'get_hyperlink',
+  'doc.hyperlinks.wrap': 'wrap_hyperlink',
+  'doc.hyperlinks.insert': 'insert_hyperlink',
+  'doc.hyperlinks.patch': 'patch_hyperlink',
+  'doc.hyperlinks.remove': 'remove_hyperlink',
   'doc.query.match': 'query_match',
   'doc.mutations.preview': 'preview_mutations',
   'doc.mutations.apply': 'apply_mutations',

apps/cli/src/__tests__/conformance/scenarios.ts

@@ -186,6 +186,71 @@ async function prepareSeparatedSecondListTarget(
   return { docPath, target };
 }
 
+function requireHyperlinkAddress(item: Record<string, unknown>, context: string): Record<string, unknown> {
+  const address = item.address;
+  if (!address || typeof address !== 'object') {
+    throw new Error(`Missing hyperlink address for ${context}.`);
+  }
+  return address as Record<string, unknown>;
+}
+
+async function resolveFirstHyperlinkAddress(
+  harness: ConformanceHarness,
+  stateDir: string,
+  docPath: string,
+  context: string,
+): Promise<Record<string, unknown>> {
+  const listed = await harness.runCli([...commandTokens('doc.hyperlinks.list'), docPath, '--limit', '10'], stateDir);
+  if (listed.result.code !== 0 || listed.envelope.ok !== true) {
+    throw new Error(`Failed to list hyperlinks for ${context}.`);
+  }
+
+  const items = extractDiscoveryItems(listed.envelope.data);
+  const first = items[0];
+  if (!first) {
+    throw new Error(`No hyperlinks available for ${context}.`);
+  }
+
+  return requireHyperlinkAddress(first, context);
+}
+
+async function createHyperlinkFixture(
+  harness: ConformanceHarness,
+  stateDir: string,
+  label: string,
+): Promise<{ docPath: string; address: Record<string, unknown> }> {
+  const sourceDoc = await harness.copyFixtureDoc(`${label}-source`);
+  const target = await harness.firstTextRange(sourceDoc, stateDir);
+  const collapsedTarget = {
+    kind: 'text',
+    blockId: target.blockId,
+    range: { start: target.range.start, end: target.range.start },
+  };
+  const outputDoc = harness.createOutputPath(`${label}-with-hyperlink`);
+
+  const inserted = await harness.runCli(
+    [
+      ...commandTokens('doc.hyperlinks.insert'),
+      sourceDoc,
+      '--target-json',
+      JSON.stringify(collapsedTarget),
+      '--text',
+      'Conformance hyperlink',
+      '--link-json',
+      JSON.stringify({ destination: { href: 'https://example.com' } }),
+      '--out',
+      outputDoc,
+    ],
+    stateDir,
+  );
+  if (inserted.result.code !== 0 || inserted.envelope.ok !== true) {
+    throw new Error(`Failed to create hyperlink fixture for ${label}.`);
+  }
+
+  const address = await resolveFirstHyperlinkAddress(harness, stateDir, outputDoc, label);
+  return { docPath: outputDoc, address };
+}
+
 function sectionMutationScenario(
   operationId: CliOperationId,
   label: string,
@@ -799,6 +864,99 @@ export const SUCCESS_SCENARIOS = {
       args: ['comments', 'list', fixture.docPath, '--include-resolved', 'false'],
     };
   },
+  'doc.hyperlinks.list': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-hyperlinks-list-success');
+    const fixture = await createHyperlinkFixture(harness, stateDir, 'doc-hyperlinks-list');
+    return {
+      stateDir,
+      args: [...commandTokens('doc.hyperlinks.list'), fixture.docPath, '--limit', '10'],
+    };
+  },
+  'doc.hyperlinks.get': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-hyperlinks-get-success');
+    const fixture = await createHyperlinkFixture(harness, stateDir, 'doc-hyperlinks-get');
+    return {
+      stateDir,
+      args: [...commandTokens('doc.hyperlinks.get'), fixture.docPath, '--target-json', JSON.stringify(fixture.address)],
+    };
+  },
+  'doc.hyperlinks.wrap': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-hyperlinks-wrap-success');
+    const docPath = await harness.copyFixtureDoc('doc-hyperlinks-wrap');
+    const target = await harness.firstTextRange(docPath, stateDir);
+    return {
+      stateDir,
+      args: [
+        ...commandTokens('doc.hyperlinks.wrap'),
+        docPath,
+        '--target-json',
+        JSON.stringify(target),
+        '--link-json',
+        JSON.stringify({ destination: { href: 'https://example.com/wrap' } }),
+        '--out',
+        harness.createOutputPath('doc-hyperlinks-wrap-output'),
+      ],
+    };
+  },
+  'doc.hyperlinks.insert': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-hyperlinks-insert-success');
+    const docPath = await harness.copyFixtureDoc('doc-hyperlinks-insert');
+    const target = await harness.firstTextRange(docPath, stateDir);
+    const collapsedTarget = {
+      kind: 'text',
+      blockId: target.blockId,
+      range: { start: target.range.start, end: target.range.start },
+    };
+    return {
+      stateDir,
+      args: [
+        ...commandTokens('doc.hyperlinks.insert'),
+        docPath,
+        '--target-json',
+        JSON.stringify(collapsedTarget),
+        '--text',
+        'Conformance hyperlink insert',
+        '--link-json',
+        JSON.stringify({ destination: { href: 'https://example.com/insert' } }),
+        '--out',
+        harness.createOutputPath('doc-hyperlinks-insert-output'),
+      ],
+    };
+  },
+  'doc.hyperlinks.patch': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-hyperlinks-patch-success');
+    const fixture = await createHyperlinkFixture(harness, stateDir, 'doc-hyperlinks-patch');
+    return {
+      stateDir,
+      args: [
+        ...commandTokens('doc.hyperlinks.patch'),
+        fixture.docPath,
+        '--target-json',
+        JSON.stringify(fixture.address),
+        '--patch-json',
+        JSON.stringify({ tooltip: 'Conformance hyperlink patch' }),
+        '--out',
+        harness.createOutputPath('doc-hyperlinks-patch-output'),
+      ],
+    };
+  },
+  'doc.hyperlinks.remove': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
+    const stateDir = await harness.createStateDir('doc-hyperlinks-remove-success');
+    const fixture = await createHyperlinkFixture(harness, stateDir, 'doc-hyperlinks-remove');
+    return {
+      stateDir,
+      args: [
+        ...commandTokens('doc.hyperlinks.remove'),
+        fixture.docPath,
+        '--target-json',
+        JSON.stringify(fixture.address),
+        '--mode',
+        'unwrap',
+        '--out',
+        harness.createOutputPath('doc-hyperlinks-remove-output'),
+      ],
+    };
+  },
   'doc.getText': async (harness: ConformanceHarness): Promise<ScenarioInvocation> => {
     const stateDir = await harness.createStateDir('doc-get-text-success');
     const docPath = await harness.copyFixtureDoc('doc-get-text');

apps/docs/document-api/available-operations.mdx

@@ -21,6 +21,7 @@ Use the tables below to see what operations are available and where each one is
 | Create | 6 | 0 | 6 | [Reference](/document-api/reference/create/index) |
 | Format | 44 | 1 | 45 | [Reference](/document-api/reference/format/index) |
 | History | 3 | 0 | 3 | [Reference](/document-api/reference/history/index) |
+| Hyperlinks | 6 | 0 | 6 | [Reference](/document-api/reference/hyperlinks/index) |
 | Images | 13 | 0 | 13 | [Reference](/document-api/reference/images/index) |
 | Lists | 28 | 1 | 29 | [Reference](/document-api/reference/lists/index) |
 | Mutations | 2 | 0 | 2 | [Reference](/document-api/reference/mutations/index) |
@@ -106,6 +107,12 @@ Use the tables below to see what operations are available and where each one is
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.history.get(...)</code></span> | [`history.get`](/document-api/reference/history/get) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.history.undo(...)</code></span> | [`history.undo`](/document-api/reference/history/undo) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.history.redo(...)</code></span> | [`history.redo`](/document-api/reference/history/redo) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.hyperlinks.list(...)</code></span> | [`hyperlinks.list`](/document-api/reference/hyperlinks/list) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.hyperlinks.get(...)</code></span> | [`hyperlinks.get`](/document-api/reference/hyperlinks/get) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.hyperlinks.wrap(...)</code></span> | [`hyperlinks.wrap`](/document-api/reference/hyperlinks/wrap) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.hyperlinks.insert(...)</code></span> | [`hyperlinks.insert`](/document-api/reference/hyperlinks/insert) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.hyperlinks.patch(...)</code></span> | [`hyperlinks.patch`](/document-api/reference/hyperlinks/patch) |
+| <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.hyperlinks.remove(...)</code></span> | [`hyperlinks.remove`](/document-api/reference/hyperlinks/remove) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.images.list(...)</code></span> | [`images.list`](/document-api/reference/images/list) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.images.get(...)</code></span> | [`images.get`](/document-api/reference/images/get) |
 | <span style={{ whiteSpace: 'nowrap', wordBreak: 'normal', overflowWrap: 'normal' }}><code>editor.doc.images.delete(...)</code></span> | [`images.delete`](/document-api/reference/images/delete) |

apps/docs/document-api/reference/_generated-manifest.json

@@ -93,6 +93,13 @@
     "apps/docs/document-api/reference/history/index.mdx",
     "apps/docs/document-api/reference/history/redo.mdx",
     "apps/docs/document-api/reference/history/undo.mdx",
+    "apps/docs/document-api/reference/hyperlinks/get.mdx",
+    "apps/docs/document-api/reference/hyperlinks/index.mdx",
+    "apps/docs/document-api/reference/hyperlinks/insert.mdx",
+    "apps/docs/document-api/reference/hyperlinks/list.mdx",
+    "apps/docs/document-api/reference/hyperlinks/patch.mdx",
+    "apps/docs/document-api/reference/hyperlinks/remove.mdx",
+    "apps/docs/document-api/reference/hyperlinks/wrap.mdx",
     "apps/docs/document-api/reference/images/convert-to-floating.mdx",
     "apps/docs/document-api/reference/images/convert-to-inline.mdx",
     "apps/docs/document-api/reference/images/delete.mdx",
@@ -552,8 +559,22 @@
       ],
       "pagePath": "apps/docs/document-api/reference/images/index.mdx",
       "title": "Images"
+    },
+    {
+      "aliasMemberPaths": [],
+      "key": "hyperlinks",
+      "operationIds": [
+        "hyperlinks.list",
+        "hyperlinks.get",
+        "hyperlinks.wrap",
+        "hyperlinks.insert",
+        "hyperlinks.patch",
+        "hyperlinks.remove"
+      ],
+      "pagePath": "apps/docs/document-api/reference/hyperlinks/index.mdx",
+      "title": "Hyperlinks"
     }
   ],
   "marker": "{/* GENERATED FILE: DO NOT EDIT. Regenerate via `pnpm run docapi:sync`. */}",
-  "sourceHash": "185b9ab20679d6709e676a2b2b810adebddb201298e6a1682b3af62e600e4eb1"
+  "sourceHash": "61970f6e7637f11451e0f7fb218a66bc84f39b7b512a5002d8996286708c2d31"
 }