@docmana/sdk 0.28.1 → 0.32.0

package/CHANGELOG.md

@@ -1,217 +1,259 @@
-# Changelog
-
+# Changelog
+
 ## Unreleased
 
+## 0.32.0 - 2026-10-19
+
+- Release the additive `Docmana.authoring` API for scoped formula reads, create/save/validate/publish/history, native archives, sorting, assisted conversations, editor catalog and mapping proposals.
+- Preserve normalized API business error codes and optional POC provenance types. Optional Git/projection write fields are not accepted by DocMana API main; omit them on the ordinary Mongo authoring path.
+- Add revision-pinned `authoring.documentTrialDefinitions` for server-side assisted document trials in DocMana Flows, using existing DocMana API main reads.
+- Document assisted trial execution separately from native manual trials; document-trial reports can identify their executor. No new DocMana API endpoint is required.
+
+### Earlier local POC iteration notes
+
+The earlier 0.29–0.31 authoring iterations are incorporated in 0.32.0. Assisted classification/extraction now uses `documentTrialDefinitions` and the Flows executor; the experimental DocMana API `/extract/test-assisted` route is not required. The multipart `documentTrial` execution route remains manual-only with API main.
+
+### Previously unreleased authoring additions
+
+- Add full compiled prompt upserts, Git projection provenance, the staged state,
+  runtime capabilities and artifact/tooling hashes for traced publication.
+
+- Add organization-scoped document trials through Consumer Edge and native DocMana API, with native revision checks or compiled YAML draft prompts.
+
+- Add typed Git/Mongo authoring sources, Git publication provenance and Mongo divergence state; forward an optional exact Git commit when publishing.
+
+### Editor catalog and conversations
+
+- Add the organization-scoped native editor catalog and JSONata mapping proposal methods.
+
+- Preserve public API business error codes in optional `DocmanaError.apiCode`,
+  without changing existing SDK error categories or retry behavior.
+
+- Add organization-scoped assisted-rule conversations: opening with context and
+  optional transcript, sending messages, and acknowledging approved proposals.
+- Preserve native proposal/context payloads and expired-conversation HTTP 410.
+  Requires Consumer Edge's additive authoring conversation endpoints (DOC-2385).
+
+### Native authoring and archives
+
+- Add `Docmana.authoring` for organization-scoped native formula discovery,
+  creation, draft saving, validation, publication, history and feature flags.
+- Export lossless native authoring types and revision/operation receipt types.
+  Requires Consumer Edge's additive `/v1/authoring` contract (DOC-2385).
 ## 0.28.1 - 2026-10-02
 
 - Add `QUEUED` to the public `ExecutionStatus` type and verify that polling
   continues through `QUEUED` and `INCOMPLETED` before retrieving the completed result.
 
+- Add native archive import/export and formula deletion, with explicit import
+  overwrite confirmation and a 10 MiB archive limit.
+- Add server-side list sorting and formula dates/execution/document totals.
+
 ## 0.28.0 - 2026-09-09
-
-- Expose optional Fraud Detection API build identity on results through
-  `processor.apiVersion`, `processor.gitCommit`, and `processor.buildTime`.
-
-## 0.27.0 - 2026-09-08
-
-- Expose optional physical-document provenance, logical-document identifiers,
-  and page ranges on execution document mappings.
-- Preserve legacy execution mappings unchanged when source provenance is absent.
-
-## 0.26.0 - 2026-09-07
-
-- Expose the exact numeric version that a new flow execution would use through
-  `getFlowMetadata`.
-
-## 0.25.0 - 2026-08-24
-
-- Stream file-path inputs from disk instead of loading them completely into memory.
-- Expose typed `413` and `503` upload errors, preserve `Retry-After`, and retry one
-  multipart admission `503` carrying that header with a fresh request body.
-
-## 0.24.0 - 2026-08-20
-
-- Preserve the exact numeric flow version when mapping raw execution results.
-- Expose each processing step's LLM model and immutable prompt identifier without
-  reintroducing token or cost telemetry.
-- Update vulnerable HTTP and build-tool transitive dependencies to patched versions.
-
-## 0.23.0 - 2026-08-07
-
-- Align the Fraud result with Consumer Edge's functional public contract.
-- Keep verdict, confidence, reasoning, summary, findings, document id, and duration.
-- Remove internal preprocessing, layer telemetry, model usage, token counts, costs,
-  and persistence diagnostics; finding categories remain available through `finding.layer`.
-
-## 0.22.0 - 2026-08-06
-
-- Expose the complete Consumer Edge fraud-analysis telemetry: global totals,
-  preprocessing, verdict, and per-layer duration, token usage, LLM calls, model
-  usage, cost, and errors.
-- Keep model usage Mongo-safe as `modelUsage[]` and continue excluding the
-  sensitive Fraud `document` payload.
-
-## 0.21.0 - 2026-08-05
-
-- Relay the native Fraud job identifier through Consumer Edge while preserving
-  the existing high-level polling workflow.
-- Add local file, named byte, and readable stream inputs to `detectFraud` and
-  `detectFraudAsync` through the existing `FileInput` contract.
-- Stop sending organization correlation on Fraud requests. The deprecated
-  organization arguments remain accepted and ignored for source compatibility.
-- Expose Consumer Edge's BI-friendly Fraud result contract: aggregate `summary`,
-  referenced `findings`, and detection `layers` keyed by their unique names.
-
-## 0.20.0 - 2026-08-04
-
-- Add `detectFraud` to start a Consumer Edge fraud-detection job, poll its
-  status, and return the normalized verdict and findings.
-- Add `detectFraudAsync`, `getFraudDetectionStatus`, and
-  `getFraudDetectionResult` for callers that manage polling themselves.
-- Respect `X-Poll-After` and `Retry-After`, retry transient status failures,
-  and expose typed failure, timeout, and cancellation errors.
-
-## 0.19.0 - 2026-08-04
-
-- Add synchronous and asynchronous V2 partial flow execution through Consumer Edge.
-- Use `executionScope`, `flowVersion`, and `classificationNodeNames` in the
-  multipart body, leaving only `organization` in the query string.
-- Return the standard `DocmanaExecutionResult` shape with optional
-  `partialExecution` metadata.
-
-## 0.18.0
-- Expose the optional aggregate `verdict` on `DocmanaExecutionResult`, preserving
-  the `VALID`, `PARTIAL`, `WARNING`, `FAILED`, or `UNKNOWN` value computed by
-  Docmana API and returned by consumer-edge.
-
-## 0.17.0
-- Expose the optional `flowVersion` on `DocmanaExecutionResult`, preserving the
-  exact Docmana flow version used by an execution in polling and callback results.
-
-consu## 0.16.0
-- Scope organization document access to a specific organization: `listOrganizationDocuments`
-  now accepts an `organization` option and `downloadOrganizationDocument(s)` an optional
-  `organization` argument, both forwarded as the `?organization=` query param (relayed to
-  docmana-api as `X-Selected-Organization`). Without it, consumer-edge reads the caller's
-  default organization depot, which leaks another org's documents to callers scoping by site.
-
-## 0.15.0
-- Expose `rejectionCode`, `rejectionMessage`, `documentTypeProximity`, and
-  `documentContentNature` as optional system fields on node results instead of
-  including them in user-defined `data`.
-
-## 0.14.0
-- Add the optional human-readable `label` to every mapped node result while
-  preserving the stable node name as the record key.
-- Preserve the `REJECTED` status returned by classification nodes and expose it
-  in the public `ExecutionStatus` contract.
-- Add document-level `preprocessing` results, including generated steps such as
-  `Document Extraction`, correlated to their document by `doc_key`.
-
-## 0.13.0
-- Add normalized execution metrics to `DocmanaExecutionResult`:
-  `flowId`, `totalDocuments`, `totalPages`, `totalTokens`, `totalMana`, and
-  `totalRunningTime`.
-- Add node-level execution metrics to mapped node results: `runningTime` and
-  `mana`.
-
-## 0.12.0
-- Add `--context <json>` to `docmana flow run`, parsed as a JSON object and
-  passed through to `runFlow` as `RunFlowParams.context`.
-- Return CLI usage errors when `--context` is invalid JSON or is not a JSON
-  object.
-
-## 0.11.0
-- Normalize execution statuses to uppercase SDK values:
-  `PENDING`, `RUNNING`, `INCOMPLETED`, `COMPLETED`, and `FAILED`.
-- Normalize raw API and polling statuses before checking terminal or failed
-  states, so legacy mixed-case values still map consistently.
-- Rename flow metadata `contextSchema` to `jsonContextSchema` in the public
-  `FlowMetadata` shape and README examples.
-
-## 0.10.0
-- Add an optional `organization` to flow selection, emitted as a
-  `?organization=<org>` query param on the request to
-  `docmana-consumer-edge-api`. Purely additive — existing calls are unchanged.
-  - `listFlows({ organization })`, `getFlowMetadata(flowId, { organization })`,
-    and `getFlowDefinition(flowId, { organization })` accept the option.
-  - `RunFlowParams` (and therefore `runFlow` / `runFlowAsync`) gains
-    `organization`, threaded onto the `execute-async` request URL.
-- Expose `organization` on `FlowListItem`: when the consumer-edge tags a flow
-  with its organization, `listFlows()` now carries it through on each item.
-
-## 0.8.1
-- Rename the multipart wire fields sent to `docmana-consumer-edge-api` from
-  `json_context` / `callback_url` to `jsonContext` / `callbackUrl`, matching the
-  edge-api DTOs that dropped their snake_case `@Expose` mappings. Public inputs
-  (`context`, `callbackUrl`) are unchanged.
-
-## 0.8.0
-- Add organization document depot methods and CLI commands:
-  `listOrganizationDocuments()`, `downloadOrganizationDocument()`, and
-  `downloadOrganizationDocuments()`.
-- Add `docmana organization document list/download`.
-- Make `docmana organization document download --output` optional; default output
-  is `./{path}`.
-
-## 0.7.0
-- Add `getFlowMetadata()` / `docmana flow metadata` for projected flow runtime
-  metadata from `docmana-consumer-edge-api`.
-- Add `getFlowDefinition()` / `docmana flow definition` for normalized flow
-  graph definitions without exposing the Docmana ZIP export.
-
-## 0.6.0
-- Add `listOrganizations()` and `docmana organization list` to list organizations
-  available through `docmana-consumer-edge-api`.
-
-## 0.5.0
-- Add `listFlows()` to list flows available through `docmana-consumer-edge-api`,
-  returning `{ id, name, state }[]` with `state: "unknown"` when Docmana omits it.
-- Add `docmana flow list` CLI command, with the same API URL and Bearer token resolution as `docmana flow run`.
-- Rename `RunFlowInput` to `RunFlowParams` and move polling controls to
-  `RunFlowOptions`.
-- Remove the single-file `file` shortcut from flow params; callers now pass
-  `files`.
-- Remove `fileName` from flow params; byte and stream inputs now use
-  `{ data, filename, contentType? }`.
-- Replace `runFlowWithCallback` with `runFlowAsync(..., { callbackUrl })`.
-
-## 0.3.5
-- Add callback execution support: starts a flow and returns `{ executionResultId, fileIds }` **without polling**, registering a `callback_url` so docmana-api POSTs a completion notification when the run finishes. Call `getResult(executionResultId)` on receipt to fetch the mapped result.
-
-## 0.3.3
-- Add `RunFlowParams.context` (business `json_context`): when provided, `runFlow`/`runFlowAsync` include `json_context` in the request body for both `run_flow` and `run_once_flow`. The context is passed through as-is — filtering against the flow's *Start* node properties is performed server-side by docmana-api.
-
-## 0.3.2
-- Add `scoreDescription` to score-node results (Validation, Classification, CrossValidation, Conclusion).
-- Fix: when a target `language` is requested, the **textual** score-node fields `feedback` and `scoreDescription` are now returned from `translations[language]` (falling back to the default values when the translation omits them). The numeric `score` is language-independent and is always taken from the default node. Previously only the dynamic `data` fields were translated while the textual fields stayed in the flow's default language.
-
-## 0.3.1
-- Fix: upload all files in a single `/upload` call (one folder UUID) instead of one call per file. Sending each file separately made Docmana treat them as distinct documents, which breaks multi-document flows ("Node already present" when the same flow node is built per document).
-
-## 0.3.0
-- Relocated mapper logic and tests to `src/mappers/`.
-- Renamed SDK models to `DocmanaX` and API models to `DocmanaApiX` to distinguish raw backend types from clean public SDK types.
-- Pluralized `classification` results into a `classifications` key-value record on document results.
-- Nested dynamic extraction fields inside a dedicated `data` record on node results to prevent property name collisions.
-- Restructured node result interfaces to remove `score` and `feedback` from `DocmanaExtractionResult` and `DocmanaMetadataExtractionResult` (via new `DocmanaScoreNodeResult` interface).
-- Excluded internal fields `result` and `documentType` from mapped SDK results.
-
-## 0.2.2
-- Fix `package-lock.json`.
-
-## 0.2.1
-- 400 responses now throw `DocmanaRequestError` (was `DocmanaAuthError`); add `Incompleted` to `ExecutionStatus`.
-
-## 0.2.0
-- `RunFlowParams.once` selects the ad-hoc `run_once_flow` endpoint (current/draft flow) instead of the published `run_flow`.
-- `DocmanaConfig.headers` are sent on every API request (e.g. `X-Selected-Organization`), without overriding the bearer token or per-request headers.
-- `FileInput` now accepts a plain `Uint8Array` (e.g. pdf-lib output) in addition to path, `Buffer`, and `Stream`.
-- Uploads send a `Content-Type` inferred from the filename extension instead of always `application/octet-stream`.
-
-## 0.1.0
-- Single-call `runFlow` orchestration: upload → run → poll → result.
-- OAuth2 client-credentials auth with in-memory token cache and automatic refresh.
-- Typed error hierarchy (`DocmanaError`, `DocmanaExecutionError`, …).
-- Flexible file inputs: path, `Buffer`, `Stream`, and multi-file uploads.
-- Dual ESM + CJS distribution with bundled type definitions.
+
+- Expose optional Fraud Detection API build identity on results through
+  `processor.apiVersion`, `processor.gitCommit`, and `processor.buildTime`.
+
+## 0.27.0 - 2026-09-08
+
+- Expose optional physical-document provenance, logical-document identifiers,
+  and page ranges on execution document mappings.
+- Preserve legacy execution mappings unchanged when source provenance is absent.
+
+## 0.26.0 - 2026-09-07
+
+- Expose the exact numeric version that a new flow execution would use through
+  `getFlowMetadata`.
+
+## 0.25.0 - 2026-08-24
+
+- Stream file-path inputs from disk instead of loading them completely into memory.
+- Expose typed `413` and `503` upload errors, preserve `Retry-After`, and retry one
+  multipart admission `503` carrying that header with a fresh request body.
+
+## 0.24.0 - 2026-08-20
+
+- Preserve the exact numeric flow version when mapping raw execution results.
+- Expose each processing step's LLM model and immutable prompt identifier without
+  reintroducing token or cost telemetry.
+- Update vulnerable HTTP and build-tool transitive dependencies to patched versions.
+
+## 0.23.0 - 2026-08-07
+
+- Align the Fraud result with Consumer Edge's functional public contract.
+- Keep verdict, confidence, reasoning, summary, findings, document id, and duration.
+- Remove internal preprocessing, layer telemetry, model usage, token counts, costs,
+  and persistence diagnostics; finding categories remain available through `finding.layer`.
+
+## 0.22.0 - 2026-08-06
+
+- Expose the complete Consumer Edge fraud-analysis telemetry: global totals,
+  preprocessing, verdict, and per-layer duration, token usage, LLM calls, model
+  usage, cost, and errors.
+- Keep model usage Mongo-safe as `modelUsage[]` and continue excluding the
+  sensitive Fraud `document` payload.
+
+## 0.21.0 - 2026-08-05
+
+- Relay the native Fraud job identifier through Consumer Edge while preserving
+  the existing high-level polling workflow.
+- Add local file, named byte, and readable stream inputs to `detectFraud` and
+  `detectFraudAsync` through the existing `FileInput` contract.
+- Stop sending organization correlation on Fraud requests. The deprecated
+  organization arguments remain accepted and ignored for source compatibility.
+- Expose Consumer Edge's BI-friendly Fraud result contract: aggregate `summary`,
+  referenced `findings`, and detection `layers` keyed by their unique names.
+
+## 0.20.0 - 2026-08-04
+
+- Add `detectFraud` to start a Consumer Edge fraud-detection job, poll its
+  status, and return the normalized verdict and findings.
+- Add `detectFraudAsync`, `getFraudDetectionStatus`, and
+  `getFraudDetectionResult` for callers that manage polling themselves.
+- Respect `X-Poll-After` and `Retry-After`, retry transient status failures,
+  and expose typed failure, timeout, and cancellation errors.
+
+## 0.19.0 - 2026-08-04
+
+- Add synchronous and asynchronous V2 partial flow execution through Consumer Edge.
+- Use `executionScope`, `flowVersion`, and `classificationNodeNames` in the
+  multipart body, leaving only `organization` in the query string.
+- Return the standard `DocmanaExecutionResult` shape with optional
+  `partialExecution` metadata.
+
+## 0.18.0
+- Expose the optional aggregate `verdict` on `DocmanaExecutionResult`, preserving
+  the `VALID`, `PARTIAL`, `WARNING`, `FAILED`, or `UNKNOWN` value computed by
+  Docmana API and returned by consumer-edge.
+
+## 0.17.0
+- Expose the optional `flowVersion` on `DocmanaExecutionResult`, preserving the
+  exact Docmana flow version used by an execution in polling and callback results.
+
+consu## 0.16.0
+- Scope organization document access to a specific organization: `listOrganizationDocuments`
+  now accepts an `organization` option and `downloadOrganizationDocument(s)` an optional
+  `organization` argument, both forwarded as the `?organization=` query param (relayed to
+  docmana-api as `X-Selected-Organization`). Without it, consumer-edge reads the caller's
+  default organization depot, which leaks another org's documents to callers scoping by site.
+
+## 0.15.0
+- Expose `rejectionCode`, `rejectionMessage`, `documentTypeProximity`, and
+  `documentContentNature` as optional system fields on node results instead of
+  including them in user-defined `data`.
+
+## 0.14.0
+- Add the optional human-readable `label` to every mapped node result while
+  preserving the stable node name as the record key.
+- Preserve the `REJECTED` status returned by classification nodes and expose it
+  in the public `ExecutionStatus` contract.
+- Add document-level `preprocessing` results, including generated steps such as
+  `Document Extraction`, correlated to their document by `doc_key`.
+
+## 0.13.0
+- Add normalized execution metrics to `DocmanaExecutionResult`:
+  `flowId`, `totalDocuments`, `totalPages`, `totalTokens`, `totalMana`, and
+  `totalRunningTime`.
+- Add node-level execution metrics to mapped node results: `runningTime` and
+  `mana`.
+
+## 0.12.0
+- Add `--context <json>` to `docmana flow run`, parsed as a JSON object and
+  passed through to `runFlow` as `RunFlowParams.context`.
+- Return CLI usage errors when `--context` is invalid JSON or is not a JSON
+  object.
+
+## 0.11.0
+- Normalize execution statuses to uppercase SDK values:
+  `PENDING`, `RUNNING`, `INCOMPLETED`, `COMPLETED`, and `FAILED`.
+- Normalize raw API and polling statuses before checking terminal or failed
+  states, so legacy mixed-case values still map consistently.
+- Rename flow metadata `contextSchema` to `jsonContextSchema` in the public
+  `FlowMetadata` shape and README examples.
+
+## 0.10.0
+- Add an optional `organization` to flow selection, emitted as a
+  `?organization=<org>` query param on the request to
+  `docmana-consumer-edge-api`. Purely additive — existing calls are unchanged.
+  - `listFlows({ organization })`, `getFlowMetadata(flowId, { organization })`,
+    and `getFlowDefinition(flowId, { organization })` accept the option.
+  - `RunFlowParams` (and therefore `runFlow` / `runFlowAsync`) gains
+    `organization`, threaded onto the `execute-async` request URL.
+- Expose `organization` on `FlowListItem`: when the consumer-edge tags a flow
+  with its organization, `listFlows()` now carries it through on each item.
+
+## 0.8.1
+- Rename the multipart wire fields sent to `docmana-consumer-edge-api` from
+  `json_context` / `callback_url` to `jsonContext` / `callbackUrl`, matching the
+  edge-api DTOs that dropped their snake_case `@Expose` mappings. Public inputs
+  (`context`, `callbackUrl`) are unchanged.
+
+## 0.8.0
+- Add organization document depot methods and CLI commands:
+  `listOrganizationDocuments()`, `downloadOrganizationDocument()`, and
+  `downloadOrganizationDocuments()`.
+- Add `docmana organization document list/download`.
+- Make `docmana organization document download --output` optional; default output
+  is `./{path}`.
+
+## 0.7.0
+- Add `getFlowMetadata()` / `docmana flow metadata` for projected flow runtime
+  metadata from `docmana-consumer-edge-api`.
+- Add `getFlowDefinition()` / `docmana flow definition` for normalized flow
+  graph definitions without exposing the Docmana ZIP export.
+
+## 0.6.0
+- Add `listOrganizations()` and `docmana organization list` to list organizations
+  available through `docmana-consumer-edge-api`.
+
+## 0.5.0
+- Add `listFlows()` to list flows available through `docmana-consumer-edge-api`,
+  returning `{ id, name, state }[]` with `state: "unknown"` when Docmana omits it.
+- Add `docmana flow list` CLI command, with the same API URL and Bearer token resolution as `docmana flow run`.
+- Rename `RunFlowInput` to `RunFlowParams` and move polling controls to
+  `RunFlowOptions`.
+- Remove the single-file `file` shortcut from flow params; callers now pass
+  `files`.
+- Remove `fileName` from flow params; byte and stream inputs now use
+  `{ data, filename, contentType? }`.
+- Replace `runFlowWithCallback` with `runFlowAsync(..., { callbackUrl })`.
+
+## 0.3.5
+- Add callback execution support: starts a flow and returns `{ executionResultId, fileIds }` **without polling**, registering a `callback_url` so docmana-api POSTs a completion notification when the run finishes. Call `getResult(executionResultId)` on receipt to fetch the mapped result.
+
+## 0.3.3
+- Add `RunFlowParams.context` (business `json_context`): when provided, `runFlow`/`runFlowAsync` include `json_context` in the request body for both `run_flow` and `run_once_flow`. The context is passed through as-is — filtering against the flow's *Start* node properties is performed server-side by docmana-api.
+
+## 0.3.2
+- Add `scoreDescription` to score-node results (Validation, Classification, CrossValidation, Conclusion).
+- Fix: when a target `language` is requested, the **textual** score-node fields `feedback` and `scoreDescription` are now returned from `translations[language]` (falling back to the default values when the translation omits them). The numeric `score` is language-independent and is always taken from the default node. Previously only the dynamic `data` fields were translated while the textual fields stayed in the flow's default language.
+
+## 0.3.1
+- Fix: upload all files in a single `/upload` call (one folder UUID) instead of one call per file. Sending each file separately made Docmana treat them as distinct documents, which breaks multi-document flows ("Node already present" when the same flow node is built per document).
+
+## 0.3.0
+- Relocated mapper logic and tests to `src/mappers/`.
+- Renamed SDK models to `DocmanaX` and API models to `DocmanaApiX` to distinguish raw backend types from clean public SDK types.
+- Pluralized `classification` results into a `classifications` key-value record on document results.
+- Nested dynamic extraction fields inside a dedicated `data` record on node results to prevent property name collisions.
+- Restructured node result interfaces to remove `score` and `feedback` from `DocmanaExtractionResult` and `DocmanaMetadataExtractionResult` (via new `DocmanaScoreNodeResult` interface).
+- Excluded internal fields `result` and `documentType` from mapped SDK results.
+
+## 0.2.2
+- Fix `package-lock.json`.
+
+## 0.2.1
+- 400 responses now throw `DocmanaRequestError` (was `DocmanaAuthError`); add `Incompleted` to `ExecutionStatus`.
+
+## 0.2.0
+- `RunFlowParams.once` selects the ad-hoc `run_once_flow` endpoint (current/draft flow) instead of the published `run_flow`.
+- `DocmanaConfig.headers` are sent on every API request (e.g. `X-Selected-Organization`), without overriding the bearer token or per-request headers.
+- `FileInput` now accepts a plain `Uint8Array` (e.g. pdf-lib output) in addition to path, `Buffer`, and `Stream`.
+- Uploads send a `Content-Type` inferred from the filename extension instead of always `application/octet-stream`.
+
+## 0.1.0
+- Single-call `runFlow` orchestration: upload → run → poll → result.
+- OAuth2 client-credentials auth with in-memory token cache and automatic refresh.
+- Typed error hierarchy (`DocmanaError`, `DocmanaExecutionError`, …).
+- Flexible file inputs: path, `Buffer`, `Stream`, and multi-file uploads.
+- Dual ESM + CJS distribution with bundled type definitions.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Docmana
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Docmana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,6 +2,13 @@
 
 Official Docmana SDK for calling `docmana-consumer-edge-api`.
 
+SDK 0.32.0 adds native formula authoring, assisted conversations and revision-pinned
+document-trial preparation. Deploy Consumer authoring support before publishing
+and adopting this version. DocMana API main supports the ordinary Mongo path;
+assisted document trials run in DocMana Flows. A local development tarball is not
+an npm release. Optional Git/projection types remain POC contracts, not proof of
+support by API main.
+
 The SDK sends documents to Consumer, starts an async flow, polls Consumer for
 status, and returns the mapped Consumer execution DTO.
 
@@ -345,6 +352,9 @@ from the Bearer token.
 Every SDK error extends `DocmanaError`, which carries `.status`, `.code`, and an
 optional `.requestId` when available.
 
+The optional `.apiCode` preserves the public API business code (for example,
+`RULE_INTEGRITY_VIOLATION`). `.code` keeps its existing SDK error category.
+
 | Error                            | Thrown when                                                                                     |
 | -------------------------------- | ----------------------------------------------------------------------------------------------- |
 | `DocmanaRequestError`            | `400` bad request.                                                                              |
@@ -379,6 +389,90 @@ For a one-shot publish to the local yalc store:
 npm run yalc:publish
 ```
 
+## Native formula authoring
+
+SDK 0.30.0 adds the existing DocMana stateful assistant through
+`authoring.openConversation({ flow_id, language, scope?, node_id?, messages? }, options)`,
+`sendConversationMessage(conversationId, content, options)` and
+`confirmConversation(conversationId, { rule_id?, document_type_rename? }, options)`.
+All three require organization scope and accept an abort signal. Opening does
+not call the LLM. Replies contain native context, suggestions and proposals;
+the client must explicitly apply and save approved rules. Confirmation only
+acknowledges acceptance; it does not save or publish. HTTP 410 means the session
+expired: reopen with the prior transcript and resolved context, then send the
+new message. Do not replay an uncertain network failure automatically.
+
+`docmana.authoring` manages native formulas through Consumer Edge's
+`/v1/authoring` endpoints. It requires the DOC-2385 Consumer deployment and the
+DocMana API authoring endpoints. These methods do not manage Git or YAML.
+
+```ts
+const options = { organization: "my-organization" };
+const formulas = await docmana.authoring.list({ ...options, limit: 50, offset: 0 });
+const snapshot = await docmana.authoring.get(formulas[0].id, options);
+const command = {
+  operationId: crypto.randomUUID(),
+  expectedRevisions: snapshot.revisions,
+  flowPatch: { name: "Updated formula" },
+};
+const receipt = await docmana.authoring.save(snapshot.flow.id, command, options);
+await docmana.authoring.validate(snapshot.flow.id, receipt.revisions, options);
+// Publication is an explicit separate operation.
+await docmana.authoring.publish(
+  snapshot.flow.id,
+  {
+    operationId: crypto.randomUUID(),
+    expectedRevisions: receipt.revisions,
+  },
+  options,
+);
+```
+
+Also available: `create`, `history(id, "snapshots" | "published", options)` and
+`flags(options)`. Every call requires an organization and accepts an AbortSignal.
+Lists return arrays; list limits are 1–200 and history limits are 1–100. List sorting is applied before pagination using `sort`: `id` (default), `name`, `newest`, `oldest`, `recentlyModified`, or `leastRecentlyModified`. Summaries include creation/modification dates and execution/document totals when available.
+`get` returns the editable graph, assisted rules, revisions and history counts.
+Create/save/publish return a receipt, not a reloaded graph. Reload with `get`
+after a successful mutation when server-generated prompt/rule identities matter.
+
+Retain the same operation ID **and identical body** when retrying an uncertain
+mutation outcome. A 409 has `error.status === 409`: keep the user's draft and
+resolve the conflict explicitly. The SDK never silently rebases or retries a
+conflict. Native metadata remains opaque and must be preserved by editors;
+server-owned identities, history and revisions are not patchable. Assisted
+editing requires the organization's `assisted-flows` flag and backend roles.
+
+Archive transfers use the existing DocMana `.docmana`/ZIP format, including
+assisted rules. `exportArchive(id, options)` returns `Uint8Array` bytes.
+`importArchive(blob, filename, options)` accepts one archive up to 10 MiB and
+returns `imported` or `confirmation_required`. On a duplicate, obtain explicit
+user confirmation before submitting the same file with `confirmOverwrite: true`.
+`remove(id, options)` permanently deletes the formula and its authoring data;
+confirm that action with the user. Import and deletion do not use operation IDs.
+
 ## License
 
 MIT
+
+`authoring.editorCatalog(options)` retrieves organization-scoped models, tools, external-system field definitions, default prompts and feature flags for native node editors. External-system credentials are excluded. `authoring.generateMapping({ workflow_fields, expected_fields, current_mapping, user_instructions }, options)` returns `{ jsonataExpression }` from the native mapper; it does not save or publish the proposal.
+
+### Git publication provenance (local authoring POC)
+
+The types preserve optional `authoringSource`, Git commit/artifact hashes and
+projection fields for the POC contract. DocMana API main rejects these fields on
+native create/save/publish, including an explicit `{kind: "mongo"}` discriminator;
+omit them for ordinary Mongo authoring. The current Git POC uses the explicitly
+local Mongo release adapter in DocMana Flows instead.
+
+Optional response provenance remains lossless when a compatible backend provides
+it. Consumer and the SDK do not synchronize repositories, verify a checkout,
+compute a publication baseline or automatically publish newer commits. The
+presence of a TypeScript field does not enable an unsupported backend capability.
+
+### Document trials
+
+Use `authoring.trialDocument(fileBlob, filename, spec, { organization, signal })` for manual document-node trials. `spec` selects a saved native `flowId`, `expectedRevisions`, and either `node` or `allNodes`; alternatively it contains compiled YAML `nodes` with native prompts. Consumer calls the existing DocMana API test-fields/test-metadata endpoints. Temporary YAML prompts are removed in finally; abrupt process failure can leave one for administrator cleanup.
+
+For assisted Mongo nodes, call `authoring.documentTrialDefinitions({ flowId, expectedRevisions, node | allNodes }, { organization, signal })`. This read-only preparation pins active node-owned rules and settings to the coherent native snapshot, checking revisions again after resolution. Pass the returned definition and uploaded file to the server-side `runAssistedDocumentTrial` library in `@docmana/docmana-flows`. Git callers use Flows' `prepareDocumentTrial` directly. Neither path requires `/extract/test-assisted` or a modified DocMana API. Calling the old native trial method with assisted nodes now fails before upload with HTTP 422.
+
+Flows owns assisted IDP/model calls and requires its server-side provider configuration. It analyzes the file once and tries up to 100 compatible classification/extraction nodes independently, retaining evidence envelopes. Files are nonempty PDF/images up to 20 MiB. Definitions and uploads use disposable local storage, cleaned after completion; no formula, rule, reference expectation or publication is saved. These trials do not execute production routing, translate results, compare expectations or produce release approval evidence. Missing upstream context is rejected. Native API accounting and PromptShield are not implied by the Flows executor. No new CLI command is introduced.