@stll/folio-agents/dist/operation-schema.d.ts

Framework-neutral LLM tool layer over folio's ai-edits engine: function-calling tools so an agent can read and mutate .docx documents through @stll/folio-core.

import { FolioDocumentOperationBatch } from "@stll/folio-core/server";
//#region src/operation-schema.d.ts
/** Compact public shape for the runtime JSON Schema projections. */
type FolioJsonSchema = {
  readonly type?: string;
  readonly description?: string;
  readonly enum?: readonly unknown[];
  readonly minimum?: number;
  readonly maximum?: number;
  readonly minLength?: number;
  readonly minProperties?: number;
  readonly pattern?: string;
  readonly properties?: Readonly<Record<string, FolioJsonSchema>>;
  readonly required?: readonly string[];
  readonly additionalProperties?: boolean;
  readonly items?: FolioJsonSchema;
  readonly oneOf?: readonly FolioJsonSchema[];
  readonly not?: FolioJsonSchema;
};
/**
 * JSON Schema for the contract's `textRange` handle (a serializable range
 * over the visible text of one main-story block, as returned by `find_text`
 * style tools). Shared between {@link FOLIO_DOCUMENT_OPERATION_JSON_SCHEMA}
 * and the `suggest_changes` tool schema in `tools.ts` so the two cannot
 * drift. `endOffset` must be greater than `startOffset`; JSON Schema cannot
 * express that relation, the parser enforces it.
 */
declare const FOLIO_TEXT_RANGE_JSON_SCHEMA: FolioJsonSchema;
/**
 * JSON Schema for the contract's optional `precondition` guard: `{
 * blockTextHash }`, echoed from a `blockTextHash` returned by a document
 * read (`read_document`, `read_section`, `find_text`). Exported so
 * `tools.ts` can attach the same shape to `suggest_changes` and
 * `add_comment` without redeclaring it.
 */
declare const FOLIO_PRECONDITION_JSON_SCHEMA: FolioJsonSchema;
declare const FOLIO_CLEARABLE_PARAGRAPH_STYLE_ID_JSON_SCHEMA: {
  readonly oneOf: readonly [{
    readonly type: "string";
  }, {
    readonly type: "null";
  }];
  readonly description: string;
};
/** Direct `w:outlineLvl`, or null to restore style inheritance. */
declare const FOLIO_CLEARABLE_OUTLINE_LEVEL_JSON_SCHEMA: FolioJsonSchema;
/** Complete direct `w:ind` attributes, or null to restore style inheritance. */
declare const FOLIO_CLEARABLE_PARAGRAPH_INDENTATION_JSON_SCHEMA: {
  readonly oneOf: readonly [{
    readonly type: "object";
    readonly properties: {
      readonly indentLeft: {
        readonly type: "integer";
        readonly minimum: number;
        readonly maximum: number;
      };
      readonly indentRight: {
        readonly type: "integer";
        readonly minimum: number;
        readonly maximum: number;
      };
      readonly indentFirstLine: {
        readonly type: "integer";
        readonly minimum: number;
        readonly maximum: number;
      };
      readonly hangingIndent: {
        readonly type: "boolean";
      };
    };
    readonly minProperties: 1;
    readonly additionalProperties: false;
  }, {
    readonly type: "null";
  }];
  readonly description: "Complete direct paragraph indentation (`w:ind`); null removes the direct child and restores style inheritance.";
};
declare const FOLIO_INSERT_FORMATTING_SCOPE_JSON_SCHEMA: {
  readonly type: "string";
  readonly enum: readonly ["firstParagraph", "allParagraphs"];
  readonly description: string;
};
declare const FOLIO_PARAGRAPH_NUMBERING_JSON_SCHEMA: {
  readonly oneOf: readonly [{
    readonly type: "object";
    readonly properties: {
      readonly kind: {
        readonly type: "string";
        readonly enum: readonly ["none"];
      };
    };
    readonly required: readonly ["kind"];
    readonly additionalProperties: false;
  }, {
    readonly type: "object";
    readonly properties: {
      readonly kind: {
        readonly type: "string";
        readonly enum: readonly ["inherit"];
      };
    };
    readonly required: readonly ["kind"];
    readonly additionalProperties: false;
  }, {
    readonly type: "object";
    readonly properties: {
      readonly kind: {
        readonly type: "string";
        readonly enum: readonly ["levelOnly"];
      };
      readonly ilvl: {
        readonly type: "integer";
        readonly minimum: 0;
        readonly maximum: 8;
      };
    };
    readonly required: readonly ["kind", "ilvl"];
    readonly additionalProperties: false;
  }, {
    readonly type: "object";
    readonly properties: {
      readonly kind: {
        readonly type: "string";
        readonly enum: readonly ["reference"];
      };
      readonly numId: {
        readonly type: "integer";
        readonly minimum: 1;
        readonly maximum: number;
      };
      readonly ilvl: {
        readonly type: "integer";
        readonly minimum: 0;
        readonly maximum: 8;
      };
    };
    readonly required: readonly ["kind", "numId"];
    readonly additionalProperties: false;
  }, {
    readonly type: "object";
    readonly properties: {
      readonly kind: {
        readonly type: "string";
        readonly enum: readonly ["newList"];
      };
      readonly format: {
        readonly type: "string";
        readonly enum: readonly ["bullet", "numbered"];
      };
      readonly level: {
        readonly type: "integer";
        readonly minimum: 0;
        readonly maximum: 8;
      };
    };
    readonly required: readonly ["kind", "format"];
    readonly additionalProperties: false;
  }];
  readonly description: string;
};
declare const FOLIO_HARD_PAGE_BREAK_JSON_SCHEMA: {
  readonly type: "object";
  readonly properties: {
    readonly clear: {
      readonly type: "string";
      readonly enum: readonly ["none", "left", "right", "all"];
    };
  };
  readonly additionalProperties: false;
  readonly description: "Insert an empty hard page-break run; it cannot be combined with text, pageBreakBefore, or lineBreakMode.";
};
/** Shared cross-field constraint for insertion and suggest-changes projections. */
declare const FOLIO_HARD_PAGE_BREAK_OPERATION_CONSTRAINT: Pick<FolioJsonSchema, "oneOf">;
/** Complete direct `w:spacing` attributes, or null to restore style inheritance. */
declare const FOLIO_CLEARABLE_PARAGRAPH_SPACING_JSON_SCHEMA: {
  readonly oneOf: readonly [{
    readonly type: "object";
    readonly properties: {
      readonly spaceBefore: {
        readonly type: "integer";
        readonly minimum: 0;
        readonly maximum: number;
        readonly description: "Non-negative space before, in twips.";
      };
      readonly spaceAfter: {
        readonly type: "integer";
        readonly minimum: 0;
        readonly maximum: number;
        readonly description: "Non-negative space after, in twips.";
      };
      readonly lineSpacing: {
        readonly type: "integer";
        readonly minimum: number;
        readonly maximum: number;
        readonly description: "Signed line spacing: 240ths of a line with the auto rule, otherwise twips.";
      };
      readonly lineSpacingRule: {
        readonly type: "string";
        readonly enum: readonly undefined[];
        readonly description: "How `lineSpacing` is interpreted.";
      };
      readonly beforeAutospacing: {
        readonly type: "boolean";
        readonly description: "Whether the application determines spacing before automatically.";
      };
      readonly afterAutospacing: {
        readonly type: "boolean";
        readonly description: "Whether the application determines spacing after automatically.";
      };
    };
    readonly minProperties: 1;
    readonly additionalProperties: false;
  }, {
    readonly type: "null";
  }];
  readonly description: "Complete direct paragraph spacing (`w:spacing`); omitted attributes stay absent, while zero and false remain explicit. Null removes the direct spacing child and restores style inheritance.";
};
declare const FOLIO_BLOCK_PARAGRAPH_PROPERTIES_JSON_SCHEMA: {
  readonly type: "object";
  readonly description: "The paragraph properties to set; at least one.";
  readonly properties: {
    readonly styleId: {
      readonly oneOf: readonly [{
        readonly type: "string";
      }, {
        readonly type: "null";
      }];
      readonly description: string;
    };
    readonly outlineLevel: FolioJsonSchema;
    readonly numbering: {
      readonly oneOf: readonly [{
        readonly type: "object";
        readonly properties: {
          readonly kind: {
            readonly type: "string";
            readonly enum: readonly ["none"];
          };
        };
        readonly required: readonly ["kind"];
        readonly additionalProperties: false;
      }, {
        readonly type: "object";
        readonly properties: {
          readonly kind: {
            readonly type: "string";
            readonly enum: readonly ["inherit"];
          };
        };
        readonly required: readonly ["kind"];
        readonly additionalProperties: false;
      }, {
        readonly type: "object";
        readonly properties: {
          readonly kind: {
            readonly type: "string";
            readonly enum: readonly ["levelOnly"];
          };
          readonly ilvl: {
            readonly type: "integer";
            readonly minimum: 0;
            readonly maximum: 8;
          };
        };
        readonly required: readonly ["kind", "ilvl"];
        readonly additionalProperties: false;
      }, {
        readonly type: "object";
        readonly properties: {
          readonly kind: {
            readonly type: "string";
            readonly enum: readonly ["reference"];
          };
          readonly numId: {
            readonly type: "integer";
            readonly minimum: 1;
            readonly maximum: number;
          };
          readonly ilvl: {
            readonly type: "integer";
            readonly minimum: 0;
            readonly maximum: 8;
          };
        };
        readonly required: readonly ["kind", "numId"];
        readonly additionalProperties: false;
      }, {
        readonly type: "object";
        readonly properties: {
          readonly kind: {
            readonly type: "string";
            readonly enum: readonly ["newList"];
          };
          readonly format: {
            readonly type: "string";
            readonly enum: readonly ["bullet", "numbered"];
          };
          readonly level: {
            readonly type: "integer";
            readonly minimum: 0;
            readonly maximum: 8;
          };
        };
        readonly required: readonly ["kind", "format"];
        readonly additionalProperties: false;
      }];
      readonly description: string;
    };
    readonly indentation: {
      readonly oneOf: readonly [{
        readonly type: "object";
        readonly properties: {
          readonly indentLeft: {
            readonly type: "integer";
            readonly minimum: number;
            readonly maximum: number;
          };
          readonly indentRight: {
            readonly type: "integer";
            readonly minimum: number;
            readonly maximum: number;
          };
          readonly indentFirstLine: {
            readonly type: "integer";
            readonly minimum: number;
            readonly maximum: number;
          };
          readonly hangingIndent: {
            readonly type: "boolean";
          };
        };
        readonly minProperties: 1;
        readonly additionalProperties: false;
      }, {
        readonly type: "null";
      }];
      readonly description: "Complete direct paragraph indentation (`w:ind`); null removes the direct child and restores style inheritance.";
    };
    readonly alignment: {
      readonly oneOf: readonly [{
        readonly type: "string";
        readonly enum: readonly undefined[];
      }, {
        readonly type: "null";
      }];
      readonly description: "Direct paragraph alignment; null restores style inheritance.";
    };
    readonly spacing: {
      readonly oneOf: readonly [{
        readonly type: "object";
        readonly properties: {
          readonly spaceBefore: {
            readonly type: "integer";
            readonly minimum: 0;
            readonly maximum: number;
            readonly description: "Non-negative space before, in twips.";
          };
          readonly spaceAfter: {
            readonly type: "integer";
            readonly minimum: 0;
            readonly maximum: number;
            readonly description: "Non-negative space after, in twips.";
          };
          readonly lineSpacing: {
            readonly type: "integer";
            readonly minimum: number;
            readonly maximum: number;
            readonly description: "Signed line spacing: 240ths of a line with the auto rule, otherwise twips.";
          };
          readonly lineSpacingRule: {
            readonly type: "string";
            readonly enum: readonly undefined[];
            readonly description: "How `lineSpacing` is interpreted.";
          };
          readonly beforeAutospacing: {
            readonly type: "boolean";
            readonly description: "Whether the application determines spacing before automatically.";
          };
          readonly afterAutospacing: {
            readonly type: "boolean";
            readonly description: "Whether the application determines spacing after automatically.";
          };
        };
        readonly minProperties: 1;
        readonly additionalProperties: false;
      }, {
        readonly type: "null";
      }];
      readonly description: "Complete direct paragraph spacing (`w:spacing`); omitted attributes stay absent, while zero and false remain explicit. Null removes the direct spacing child and restores style inheritance.";
    };
  };
  readonly minProperties: 1;
  readonly additionalProperties: false;
};
/**
 * JSON Schema (draft-07 compatible) for ONE document operation: the full
 * union accepted by `parseFolioDocumentOperationBatch` in
 * `@stll/folio-core`, one `oneOf` variant per entry in
 * `FOLIO_DOCUMENT_OPERATION_TYPES`. Intended for LLM tool definitions and
 * other consumers that need the contract's wire shape without re-declaring
 * it; note that the `suggest_changes` tool in `tools.ts` deliberately
 * narrows this union (see the comment there).
 */
declare const FOLIO_DOCUMENT_OPERATION_JSON_SCHEMA: FolioJsonSchema;
/**
 * JSON Schema (draft-07 compatible) for the versioned batch envelope accepted
 * by `parseFolioDocumentOperationBatch`: `version` (always
 * `FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION`), `operations`, and the
 * optional `mode` / `atomic` / `dryRun` flags — the exact wire shape of
 * `FolioDocumentOperationBatch`. Hand this to an LLM tool definition (or any
 * JSON Schema consumer) instead of re-declaring the contract.
 */
declare const FOLIO_DOCUMENT_OPERATION_BATCH_JSON_SCHEMA: FolioJsonSchema;
/**
 * Minimal structural subset of the Standard Schema V1 interface
 * (https://standardschema.dev). Declared locally instead of depending on
 * `@standard-schema/spec` — the spec is a tiny type-only interface designed
 * to be inlined, and this keeps the package dependency-free. Consumers that
 * accept the spec type (TanStack AI, tRPC, etc.) match it structurally.
 */
type StandardSchemaV1Issue = {
  readonly message: string;
  readonly path?: readonly PropertyKey[] | undefined;
};
type StandardSchemaV1Result<Output> = {
  readonly value: Output;
  readonly issues?: undefined;
} | {
  readonly issues: readonly StandardSchemaV1Issue[];
};
type StandardSchemaV1<Input = unknown, Output = Input> = {
  readonly "~standard": {
    readonly version: 1;
    readonly vendor: string;
    readonly validate: (value: unknown) => StandardSchemaV1Result<Output>;
    readonly types?: {
      readonly input: Input;
      readonly output: Output;
    } | undefined;
  };
};
type FolioDocumentOperationBatchSchema = StandardSchemaV1<unknown, FolioDocumentOperationBatch> & {
  /**
   * The batch envelope's JSON Schema
   * ({@link FOLIO_DOCUMENT_OPERATION_BATCH_JSON_SCHEMA}), attached so tool
   * builders get the runtime validator and the LLM-facing schema from one
   * import.
   */
  readonly jsonSchema: FolioJsonSchema;
};
/**
 * Standard Schema V1 (https://standardschema.dev) validator for a document
 * operation batch, for spec-aware consumers (TanStack AI tool `inputSchema`,
 * tRPC input, etc.). Delegates to `parseFolioDocumentOperationBatch` from
 * `@stll/folio-core`, so the strict parser stays the single source of truth:
 * `validate` never throws, returning `{ value }` with the parser's exact
 * output on success and `{ issues }` (message plus a key path when the parser
 * reported one) on failure. The matching LLM-facing JSON schema is attached
 * as {@link FolioDocumentOperationBatchSchema.jsonSchema}.
 */
declare const folioDocumentOperationBatchSchema: FolioDocumentOperationBatchSchema;
//#endregion
export { FOLIO_BLOCK_PARAGRAPH_PROPERTIES_JSON_SCHEMA, FOLIO_CLEARABLE_OUTLINE_LEVEL_JSON_SCHEMA, FOLIO_CLEARABLE_PARAGRAPH_INDENTATION_JSON_SCHEMA, FOLIO_CLEARABLE_PARAGRAPH_SPACING_JSON_SCHEMA, FOLIO_CLEARABLE_PARAGRAPH_STYLE_ID_JSON_SCHEMA, FOLIO_DOCUMENT_OPERATION_BATCH_JSON_SCHEMA, FOLIO_DOCUMENT_OPERATION_JSON_SCHEMA, FOLIO_HARD_PAGE_BREAK_JSON_SCHEMA, FOLIO_HARD_PAGE_BREAK_OPERATION_CONSTRAINT, FOLIO_INSERT_FORMATTING_SCOPE_JSON_SCHEMA, FOLIO_PARAGRAPH_NUMBERING_JSON_SCHEMA, FOLIO_PRECONDITION_JSON_SCHEMA, FOLIO_TEXT_RANGE_JSON_SCHEMA, FolioJsonSchema, folioDocumentOperationBatchSchema };