@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 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[];
};
/**
 * 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;
/**
 * 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_DOCUMENT_OPERATION_BATCH_JSON_SCHEMA, FOLIO_DOCUMENT_OPERATION_JSON_SCHEMA, FOLIO_PRECONDITION_JSON_SCHEMA, FOLIO_TEXT_RANGE_JSON_SCHEMA, FolioJsonSchema, folioDocumentOperationBatchSchema };