@superdoc/sdk 2.17.1-next.1 → 2.17.1-next.11

package/README.md

@@ -60,6 +60,42 @@ is not supported for Liveblocks or the standalone document host.
 
 See the [Node.js SDK guide](https://docs.superdoc.dev/agents/automation/node-sdk) for a complete workflow.
 
+## Discover footer paragraphs
+
+`blocks.list({ in: story })` lists top-level blocks. To discover paragraphs
+inside footer tables, including tables wrapped in block content controls, use
+the paragraph node selector:
+
+```js
+const story = { kind: 'story', storyType: 'headerFooterPart', refId: footerPart.refId };
+const paragraphs = await document.find({
+  in: story,
+  select: { type: 'node', nodeType: 'paragraph' },
+  limit: 100,
+  offset: 0,
+});
+```
+
+Page with `offset` and `limit` until you have read `total` paragraphs. Each
+item's `address.nodeId` is the supported `blockId` for a text position, and
+`address.story` scopes that position to the footer. Use the returned address;
+do not derive it from OOXML `w14:paraId`. The supplied XML ID may match the API
+ID, but that equality is not a contract, and structural edits can replace a
+paragraph and its ID. Rediscover the paragraph after such edits.
+
+For a token replacement, `query.match` returns the complete mutation target,
+including the story and text offsets:
+
+```js
+const matches = await document.query.match({
+  in: story,
+  select: { type: 'text', pattern: '{{contract_number}}', mode: 'contains' },
+});
+if (matches.total === 1) {
+  await document.replace({ target: matches.items[0].target, text: 'PO-123' });
+}
+```
+
 ## Tracked comparison with exact-file review
 
 The SDK's `diff.capture` and `diff.compare` describe a snapshot comparison. A