superdoc 2.2.1 → 2.3.0

package/dist/document-api/src/fields/fields.types.d.ts

@@ -0,0 +1,90 @@
+import { TextTarget } from '../types/address.js';
+import { AdapterMutationFailure } from '../types/adapter-result.js';
+import { DiscoveryOutput } from '../types/discovery.js';
+export interface FieldAddress {
+    kind: 'field';
+    blockId: string;
+    occurrenceIndex: number;
+    nestingDepth: number;
+    /**
+     * Optional session-stable story id for v2 callers. When present together
+     * with `fieldId`, the v2 runtime resolves the field by its stable identity
+     * first and only falls back to the legacy `blockId + occurrenceIndex +
+     * nestingDepth` lookup when no stable handle is bound.
+     *
+     * Stability is session-scoped: the handle survives common structural edits
+     * that insert, rebuild, or remove other fields in the same story. True
+     * removal of the addressed field still invalidates the handle. The field
+     * is not part of the persisted OOXML id model.
+     */
+    storyId?: string;
+    /**
+     * Optional session-stable field id for v2 callers. See `storyId` for the
+     * stability contract. The legacy fields remain required so v1 callers and
+     * the shared schema keep their existing shape.
+     */
+    fieldId?: string;
+}
+export interface FieldListInput {
+    type?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface FieldGetInput {
+    target: FieldAddress;
+}
+/**
+ * Controls how an inserted field's display result is produced.
+ *
+ * - `rebuild` (default): existing behavior. The field is inserted with an empty
+ *   cached result and is expected to be recomputed via `fields.rebuild`.
+ * - `preserveCached`: the field is inserted with its visible/cached result frozen
+ *   to the supplied `cachedResultText`. No rebuild is performed or implied. This
+ *   is intended for exact reproduction of imported documents where the original
+ *   Word-cached result must survive round-trips.
+ */
+export type FieldUpdatePolicy = 'rebuild' | 'preserveCached';
+export interface FieldInsertInput {
+    at: TextTarget;
+    instruction: string;
+    mode: 'raw';
+    /**
+     * Optional. When `updatePolicy` is `'preserveCached'`, this exact string is
+     * written as the field's cached/visible result. Required (must be a string)
+     * for `preserveCached`; ignored otherwise.
+     */
+    cachedResultText?: string;
+    /**
+     * Optional. Defaults to current `'rebuild'` behavior. Set to `'preserveCached'`
+     * to freeze the imported cached result text instead of recomputing it.
+     */
+    updatePolicy?: FieldUpdatePolicy;
+}
+export interface FieldRebuildInput {
+    target: FieldAddress;
+}
+export interface FieldRemoveInput {
+    target: FieldAddress;
+    mode: 'raw';
+}
+export interface FieldInfo {
+    address: FieldAddress;
+    instruction: string;
+    fieldType: string;
+    resolvedText: string;
+    nested: boolean;
+    parentAddress?: FieldAddress;
+}
+export interface FieldDomain {
+    address: FieldAddress;
+    instruction: string;
+    fieldType: string;
+    resolvedText: string;
+    nested: boolean;
+}
+export interface FieldMutationSuccess {
+    success: true;
+    field: FieldAddress;
+}
+export type FieldMutationResult = FieldMutationSuccess | AdapterMutationFailure;
+export type FieldsListResult = DiscoveryOutput<FieldDomain>;

package/dist/document-api/src/find/find.d.ts

@@ -0,0 +1,52 @@
+import { BlockNodeAddress, Query, Selector } from '../types/index.js';
+import { SDFindInput, SDFindResult } from '../types/sd-envelope.js';
+import { StoryLocator } from '../types/story.types.js';
+/**
+ * Options for the `find` method when using a selector shorthand.
+ */
+export interface FindOptions {
+    /** Maximum number of results to return. */
+    limit?: number;
+    /** Number of results to skip before returning matches. */
+    offset?: number;
+    /** Constrain the search to descendants of the specified block node. */
+    within?: BlockNodeAddress;
+    /** Cardinality requirement for the result set. */
+    require?: Query['require'];
+    /** Whether to hydrate `result.nodes` for matched addresses. */
+    includeNodes?: Query['includeNodes'];
+    /** Whether to include unknown/unsupported nodes in diagnostics. */
+    includeUnknown?: Query['includeUnknown'];
+    /** Target a specific document story (body, header, footer, footnote, endnote). */
+    in?: StoryLocator;
+}
+/**
+ * Engine-specific adapter that the find API delegates to.
+ *
+ * Adapters return a standardized `SDFindResult` envelope.
+ */
+export interface FindAdapter {
+    /**
+     * Execute a find operation against the document.
+     *
+     * @param input - The SDFindInput to execute.
+     * @returns The find result as an SDFindResult envelope.
+     */
+    find(input: SDFindInput): SDFindResult;
+}
+/**
+ * Normalizes a selector-or-query argument into a canonical {@link Query} object.
+ *
+ * @param selectorOrQuery - A selector shorthand or a full query object.
+ * @param options - Options applied when `selectorOrQuery` is a selector.
+ * @returns A normalized query.
+ */
+export declare function normalizeFindQuery(selectorOrQuery: Selector | Query, options?: FindOptions): Query;
+/**
+ * Executes an SDM/1 find operation via the adapter.
+ *
+ * @param adapter - The engine-specific find adapter.
+ * @param input - The SDFindInput to execute.
+ * @returns An SDFindResult envelope.
+ */
+export declare function executeFind(adapter: FindAdapter, input: SDFindInput): SDFindResult;

package/dist/document-api/src/footnotes/footnotes.d.ts

@@ -0,0 +1,17 @@
+import { MutationOptions } from '../write/write.js';
+import { FootnoteGetInput, FootnoteInfo, FootnoteInsertInput, FootnoteUpdateInput, FootnoteRemoveInput, FootnoteConfigureInput, FootnoteMutationResult, FootnoteConfigResult, FootnoteListInput, FootnotesListResult } from './footnotes.types.js';
+export interface FootnotesApi {
+    list(query?: FootnoteListInput): FootnotesListResult;
+    get(input: FootnoteGetInput): FootnoteInfo;
+    insert(input: FootnoteInsertInput, options?: MutationOptions): FootnoteMutationResult;
+    update(input: FootnoteUpdateInput, options?: MutationOptions): FootnoteMutationResult;
+    remove(input: FootnoteRemoveInput, options?: MutationOptions): FootnoteMutationResult;
+    configure(input: FootnoteConfigureInput, options?: MutationOptions): FootnoteConfigResult;
+}
+export type FootnotesAdapter = FootnotesApi;
+export declare function executeFootnotesList(adapter: FootnotesAdapter, query?: FootnoteListInput): FootnotesListResult;
+export declare function executeFootnotesGet(adapter: FootnotesAdapter, input: FootnoteGetInput): FootnoteInfo;
+export declare function executeFootnotesInsert(adapter: FootnotesAdapter, input: FootnoteInsertInput, options?: MutationOptions): FootnoteMutationResult;
+export declare function executeFootnotesUpdate(adapter: FootnotesAdapter, input: FootnoteUpdateInput, options?: MutationOptions): FootnoteMutationResult;
+export declare function executeFootnotesRemove(adapter: FootnotesAdapter, input: FootnoteRemoveInput, options?: MutationOptions): FootnoteMutationResult;
+export declare function executeFootnotesConfigure(adapter: FootnotesAdapter, input: FootnoteConfigureInput, options?: MutationOptions): FootnoteConfigResult;

package/dist/document-api/src/footnotes/footnotes.types.d.ts

@@ -0,0 +1,104 @@
+import { AdapterMutationFailure } from '../types/adapter-result.js';
+import { DiscoveryOutput } from '../types/discovery.js';
+import { TextTarget } from '../types/address.js';
+import { SDFragment } from '../types/fragment.js';
+export interface FootnoteAddress {
+    kind: 'entity';
+    entityType: 'footnote';
+    noteId: string;
+}
+export interface FootnoteNumberingConfig {
+    format?: 'decimal' | 'lowerRoman' | 'upperRoman' | 'lowerLetter' | 'upperLetter' | 'symbol';
+    start?: number;
+    restartPolicy?: 'continuous' | 'eachSection' | 'eachPage';
+    /** Footnote position. Maps to w:pos in w:footnotePr. */
+    position?: 'pageBottom' | 'beneathText';
+}
+export interface EndnoteNumberingConfig {
+    format?: 'decimal' | 'lowerRoman' | 'upperRoman' | 'lowerLetter' | 'upperLetter' | 'symbol';
+    start?: number;
+    restartPolicy?: 'continuous' | 'eachSection';
+    /** Endnote position. Maps to w:pos in w:endnotePr. */
+    position?: 'sectionEnd' | 'documentEnd';
+}
+export type FootnoteConfigScope = {
+    kind: 'document';
+} | {
+    kind: 'section';
+    sectionId: string;
+};
+export interface FootnoteListInput {
+    type?: 'footnote' | 'endnote';
+    limit?: number;
+    offset?: number;
+}
+export interface FootnoteGetInput {
+    target: FootnoteAddress;
+}
+/**
+ * Insert a footnote/endnote.
+ *
+ * Two mutually exclusive content forms:
+ * - legacy `content: string` for plain-text note content
+ * - structured `body: SDFragment` for SDM/1 content
+ *
+ * `at` is optional: when omitted, host runtimes insert at the current
+ * selection/caret position (the toolbar/default editor path).
+ */
+export type FootnoteInsertInput = {
+    at?: TextTarget;
+    type: 'footnote' | 'endnote';
+    content: string;
+    body?: never;
+} | {
+    at?: TextTarget;
+    type: 'footnote' | 'endnote';
+    body: SDFragment;
+    content?: never;
+};
+export type FootnoteUpdatePatch = {
+    content: string;
+    body?: never;
+} | {
+    body: SDFragment;
+    content?: never;
+} | {
+    content?: undefined;
+    body?: undefined;
+};
+export interface FootnoteUpdateInput {
+    target: FootnoteAddress;
+    patch: FootnoteUpdatePatch;
+}
+export interface FootnoteRemoveInput {
+    target: FootnoteAddress;
+}
+export interface FootnoteConfigureInput {
+    type: 'footnote' | 'endnote';
+    scope: FootnoteConfigScope;
+    numbering?: FootnoteNumberingConfig | EndnoteNumberingConfig;
+}
+export interface FootnoteInfo {
+    address: FootnoteAddress;
+    type: 'footnote' | 'endnote';
+    noteId: string;
+    displayNumber: string;
+    content: string;
+}
+export interface FootnoteDomain {
+    address: FootnoteAddress;
+    type: 'footnote' | 'endnote';
+    noteId: string;
+    displayNumber: string;
+    content: string;
+}
+export interface FootnoteMutationSuccess {
+    success: true;
+    footnote: FootnoteAddress;
+}
+export type FootnoteMutationResult = FootnoteMutationSuccess | AdapterMutationFailure;
+export interface FootnoteConfigSuccess {
+    success: true;
+}
+export type FootnoteConfigResult = FootnoteConfigSuccess | AdapterMutationFailure;
+export type FootnotesListResult = DiscoveryOutput<FootnoteDomain>;

package/dist/document-api/src/format/format.d.ts

@@ -0,0 +1,92 @@
+import { MutationOptions } from '../types/mutation-plan.types.js';
+import { SelectionTarget, TargetLocator } from '../types/address.js';
+import { TextMutationReceipt } from '../types/receipt.js';
+import { StoryLocator } from '../types/story.types.js';
+import { SelectionMutationAdapter } from '../selection-mutation.js';
+import { InlineRunPatch, InlineRunPatchKey } from './inline-run-patch.js';
+/** Input payload for `format.bold`. */
+export type FormatBoldInput = FormatInlineAliasInput<'bold'>;
+/** Input payload for `format.italic`. */
+export type FormatItalicInput = FormatInlineAliasInput<'italic'>;
+/** Input payload for `format.underline`. */
+export type FormatUnderlineInput = FormatInlineAliasInput<'underline'>;
+/** Input payload for `format.strikethrough`. */
+export type FormatStrikethroughInput = FormatInlineAliasInput<'strike'>;
+/**
+ * Keys where `value` may be omitted: booleans (defaults to `true`) and
+ * `underline` (defaults to `true` for simple on/off).
+ */
+type ImplicitTrueKey = {
+    [K in InlineRunPatchKey]: InlineRunPatch[K] extends boolean | null | undefined ? K : never;
+}[InlineRunPatchKey] | 'underline';
+/**
+ * Input payload for direct per-property aliases (`format.<inlineKey>`).
+ *
+ * `value` is optional only for boolean-like keys (including `underline`), where
+ * omission defaults to `true` for ergonomic "turn on" calls.
+ */
+export type FormatInlineAliasInput<K extends InlineRunPatchKey> = K extends ImplicitTrueKey ? TargetLocator & {
+    target?: SelectionTarget;
+    ref?: string;
+    in?: StoryLocator;
+    value?: InlineRunPatch[K];
+} : TargetLocator & {
+    target?: SelectionTarget;
+    ref?: string;
+    in?: StoryLocator;
+    value: InlineRunPatch[K];
+};
+/**
+ * Input payload for `format.apply`.
+ *
+ * Accepts either `target` (SelectionTarget) or `ref` (string): exactly one required.
+ */
+export type StyleApplyInput = TargetLocator & {
+    target?: SelectionTarget;
+    ref?: string;
+    inline: InlineRunPatch;
+    /** Target a specific document story (body, header, footer, footnote, endnote). */
+    in?: StoryLocator;
+};
+/**
+ * Legacy root-level alias input for `doc.formatRange(...)`.
+ *
+ * Kept for SDK compatibility while routing through the canonical
+ * `format.apply` implementation.
+ */
+export type FormatRangeInput = TargetLocator & {
+    target?: SelectionTarget;
+    ref?: string;
+    properties: InlineRunPatch;
+    /** Target a specific document story (body, header, footer, footnote, endnote). */
+    in?: StoryLocator;
+    changeMode?: MutationOptions['changeMode'];
+    dryRun?: boolean;
+    expectedRevision?: string;
+};
+/**
+ * Named alias for MutationOptions on format.apply.
+ *
+ * Exists as a distinct type so the styles system can add style-specific
+ * options (e.g. scope, priority) without changing the public API shape.
+ */
+export type StyleApplyOptions = MutationOptions;
+/** Direct alias methods (`format.<inlineKey>`) that route to `format.apply`. */
+export type FormatInlineAliasApi = {
+    [K in InlineRunPatchKey]: (input: FormatInlineAliasInput<K>, options?: MutationOptions) => TextMutationReceipt;
+};
+/** Public helper surface exposed on `DocumentApi.format`. */
+export interface FormatApi extends FormatInlineAliasApi {
+    strikethrough(input: FormatStrikethroughInput, options?: MutationOptions): TextMutationReceipt;
+    apply(input: StyleApplyInput, options?: MutationOptions): TextMutationReceipt;
+}
+/**
+ * Executes `format.apply` via the selection mutation adapter (plan engine).
+ */
+export declare function executeStyleApply(adapter: SelectionMutationAdapter, input: StyleApplyInput, options?: MutationOptions): TextMutationReceipt;
+/**
+ * Executes a direct alias operation (`format.<inlineKey>`) by translating it
+ * into a single-key `format.apply` payload.
+ */
+export declare function executeInlineAlias<K extends InlineRunPatchKey>(adapter: SelectionMutationAdapter, key: K, input: FormatInlineAliasInput<K>, options?: MutationOptions): TextMutationReceipt;
+export {};

package/dist/document-api/src/format/inline-run-patch.d.ts

@@ -0,0 +1,138 @@
+export type InlinePropertyStorage = 'mark' | 'runAttribute';
+export type InlinePropertyType = 'boolean' | 'string' | 'number' | 'object' | 'array';
+export interface UnderlinePatch {
+    style?: string | null;
+    color?: string | null;
+    themeColor?: string | null;
+}
+export interface ShadingPatch {
+    fill?: string | null;
+    color?: string | null;
+    val?: string | null;
+}
+export interface BorderPatch {
+    val?: string | null;
+    sz?: number | null;
+    color?: string | null;
+    space?: number | null;
+}
+export interface FitTextPatch {
+    val?: number | null;
+    id?: string | null;
+}
+export interface LangPatch {
+    val?: string | null;
+    eastAsia?: string | null;
+    bidi?: string | null;
+}
+export interface RFontsPatch {
+    ascii?: string | null;
+    hAnsi?: string | null;
+    eastAsia?: string | null;
+    cs?: string | null;
+    asciiTheme?: string | null;
+    hAnsiTheme?: string | null;
+    eastAsiaTheme?: string | null;
+    csTheme?: string | null;
+    hint?: string | null;
+}
+export interface EastAsianLayoutPatch {
+    id?: string | null;
+    combine?: boolean | null;
+    combineBrackets?: string | null;
+    vert?: boolean | null;
+    vertCompress?: boolean | null;
+}
+export interface StylisticSetPatch {
+    id: number;
+    val?: boolean;
+}
+export interface InlineRunPatch {
+    bold?: boolean | null;
+    italic?: boolean | null;
+    strike?: boolean | null;
+    dstrike?: boolean | null;
+    smallCaps?: boolean | null;
+    caps?: boolean | null;
+    underline?: true | false | UnderlinePatch | null;
+    highlight?: string | null;
+    shading?: ShadingPatch | null;
+    color?: string | null;
+    border?: BorderPatch | null;
+    outline?: boolean | null;
+    shadow?: boolean | null;
+    emboss?: boolean | null;
+    imprint?: boolean | null;
+    vertAlign?: 'superscript' | 'subscript' | 'baseline' | null;
+    position?: number | null;
+    rtl?: boolean | null;
+    cs?: boolean | null;
+    bCs?: boolean | null;
+    iCs?: boolean | null;
+    vanish?: boolean | null;
+    webHidden?: boolean | null;
+    specVanish?: boolean | null;
+    snapToGrid?: boolean | null;
+    oMath?: boolean | null;
+    fontSize?: number | null;
+    fontFamily?: string | null;
+    fontSizeCs?: number | null;
+    letterSpacing?: number | null;
+    charScale?: number | null;
+    kerning?: number | null;
+    fitText?: FitTextPatch | null;
+    lang?: LangPatch | null;
+    rStyle?: string | null;
+    rFonts?: RFontsPatch | null;
+    eastAsianLayout?: EastAsianLayoutPatch | null;
+    em?: string | null;
+    ligatures?: string | null;
+    numForm?: string | null;
+    numSpacing?: string | null;
+    stylisticSets?: StylisticSetPatch[] | null;
+    contextualAlternates?: boolean | null;
+}
+export type InlineRunPatchKey = keyof InlineRunPatch;
+interface InlinePropertyCarrierMark {
+    storage: 'mark';
+    markName: 'bold' | 'italic' | 'underline' | 'strike' | 'highlight' | 'textStyle';
+    textStyleAttr?: string;
+}
+interface InlinePropertyCarrierRunAttribute {
+    storage: 'runAttribute';
+    nodeName: 'run';
+    runPropertyKey: string;
+}
+export type InlinePropertyCarrier = InlinePropertyCarrierMark | InlinePropertyCarrierRunAttribute;
+export interface InlinePropertyRegistryEntry {
+    key: InlineRunPatchKey;
+    type: InlinePropertyType;
+    ooxmlElement: string;
+    storage: InlinePropertyStorage;
+    tracked: boolean;
+    carrier: InlinePropertyCarrier;
+    schema: Record<string, unknown>;
+}
+export declare const INLINE_PROPERTY_REGISTRY: readonly [InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, {
+    readonly key: "underline";
+    readonly type: "object";
+    readonly ooxmlElement: "w:u";
+    readonly storage: "mark";
+    readonly tracked: true;
+    readonly carrier: InlinePropertyCarrierMark;
+    readonly schema: Record<string, unknown>;
+}, {
+    readonly key: "highlight";
+    readonly type: "string";
+    readonly ooxmlElement: "w:highlight";
+    readonly storage: "mark";
+    readonly tracked: true;
+    readonly carrier: InlinePropertyCarrierMark;
+    readonly schema: Record<string, unknown>;
+}, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry, InlinePropertyRegistryEntry];
+export declare const INLINE_PROPERTY_KEY_SET: ReadonlySet<string>;
+export declare const INLINE_PROPERTY_BY_KEY: Readonly<Record<InlineRunPatchKey, InlinePropertyRegistryEntry>>;
+export declare const INLINE_PROPERTY_KEYS_BY_STORAGE: Readonly<Record<InlinePropertyStorage, readonly InlineRunPatchKey[]>>;
+export declare function validateInlineRunPatch(patch: unknown): asserts patch is InlineRunPatch;
+export declare function buildInlineRunPatchSchema(): Record<string, unknown>;
+export {};

package/dist/document-api/src/get/get.d.ts

@@ -0,0 +1,19 @@
+import { SDGetInput } from '../types/sd-envelope.js';
+import { SDDocument } from '../types/fragment.js';
+/**
+ * Engine-specific adapter that the get API delegates to.
+ */
+export interface GetAdapter {
+    /**
+     * Read the full document as an SDDocument structure.
+     */
+    get(input: SDGetInput): SDDocument;
+}
+/**
+ * Execute a get operation via the provided adapter.
+ *
+ * @param adapter - Engine-specific get adapter.
+ * @param input - Canonical get input object.
+ * @returns An SDDocument with body content projected into SDM/1 canonical shapes.
+ */
+export declare function executeGet(adapter: GetAdapter, input: SDGetInput): SDDocument;

package/dist/document-api/src/get-html/get-html.d.ts

@@ -0,0 +1,27 @@
+import { StoryLocator } from '../types/story.types.js';
+export interface GetHtmlInput {
+    /** Restrict the read to a specific story. Omit for body (backward compatible). */
+    in?: StoryLocator;
+    /**
+     * Convert SuperDoc's internal flat-list representation to proper nested
+     * `<ol>`/`<ul>` HTML. Defaults to `true`.
+     */
+    unflattenLists?: boolean;
+}
+/**
+ * Engine-specific adapter that the getHtml API delegates to.
+ */
+export interface GetHtmlAdapter {
+    /**
+     * Return the full document content as an HTML string.
+     */
+    getHtml(input: GetHtmlInput): string;
+}
+/**
+ * Execute a getHtml operation via the provided adapter.
+ *
+ * @param adapter - Engine-specific getHtml adapter.
+ * @param input - Canonical getHtml input object.
+ * @returns The full document content as an HTML string.
+ */
+export declare function executeGetHtml(adapter: GetHtmlAdapter, input: GetHtmlInput): string;

package/dist/document-api/src/get-markdown/get-markdown.d.ts

@@ -0,0 +1,22 @@
+import { StoryLocator } from '../types/story.types.js';
+export interface GetMarkdownInput {
+    /** Restrict the read to a specific story. Omit for body (backward compatible). */
+    in?: StoryLocator;
+}
+/**
+ * Engine-specific adapter that the getMarkdown API delegates to.
+ */
+export interface GetMarkdownAdapter {
+    /**
+     * Return the full document content as a Markdown string.
+     */
+    getMarkdown(input: GetMarkdownInput): string;
+}
+/**
+ * Execute a getMarkdown operation via the provided adapter.
+ *
+ * @param adapter - Engine-specific getMarkdown adapter.
+ * @param input - Canonical getMarkdown input object.
+ * @returns The full document content as a Markdown-formatted string.
+ */
+export declare function executeGetMarkdown(adapter: GetMarkdownAdapter, input: GetMarkdownInput): string;

package/dist/document-api/src/get-node/get-node.d.ts

@@ -0,0 +1,46 @@
+import { BlockNodeType, NodeAddress } from '../types/index.js';
+import { SDNodeResult } from '../types/sd-envelope.js';
+/**
+ * Input for resolving a block node by its unique ID.
+ */
+export interface GetNodeByIdInput {
+    nodeId: string;
+    nodeType?: BlockNodeType;
+}
+/**
+ * Engine-specific adapter that the getNode API delegates to.
+ */
+export interface GetNodeAdapter {
+    /**
+     * Resolve a node address to an SDNodeResult.
+     *
+     * @param address - The node address to resolve.
+     * @returns SDNodeResult with the projected node and its address.
+     * @throws When the address cannot be resolved.
+     */
+    getNode(address: NodeAddress): SDNodeResult;
+    /**
+     * Resolve a block node by its ID.
+     *
+     * @param input - The node-id input payload.
+     * @returns SDNodeResult with the projected node and its address.
+     * @throws When the node ID cannot be found.
+     */
+    getNodeById(input: GetNodeByIdInput): SDNodeResult;
+}
+/**
+ * Execute a getNode operation via the provided adapter.
+ *
+ * @param adapter - Engine-specific getNode adapter.
+ * @param address - The node address to resolve.
+ * @returns SDNodeResult with the projected node and its address.
+ */
+export declare function executeGetNode(adapter: GetNodeAdapter, address: NodeAddress): SDNodeResult;
+/**
+ * Execute a getNodeById operation via the provided adapter.
+ *
+ * @param adapter - Engine-specific getNode adapter.
+ * @param input - The node-id input payload.
+ * @returns SDNodeResult with the projected node and its address.
+ */
+export declare function executeGetNodeById(adapter: GetNodeAdapter, input: GetNodeByIdInput): SDNodeResult;

package/dist/document-api/src/get-text/get-text.d.ts

@@ -0,0 +1,22 @@
+import { StoryLocator } from '../types/story.types.js';
+export interface GetTextInput {
+    /** Restrict the read to a specific story. Omit for body (backward compatible). */
+    in?: StoryLocator;
+}
+/**
+ * Engine-specific adapter that the getText API delegates to.
+ */
+export interface GetTextAdapter {
+    /**
+     * Return the full document text content.
+     */
+    getText(input: GetTextInput): string;
+}
+/**
+ * Execute a getText operation via the provided adapter.
+ *
+ * @param adapter - Engine-specific getText adapter.
+ * @param input - Canonical getText input object.
+ * @returns The full document text content.
+ */
+export declare function executeGetText(adapter: GetTextAdapter, input: GetTextInput): string;