@docmana/sdk 0.28.0 → 0.32.0

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.

package/dist/authoring.d.ts

@@ -0,0 +1,317 @@
+import type { HttpClient } from "./http/http-client.js";
+/** Native editor data is lossless: unknown metadata is retained during edits. */
+export type AuthoringData = Record<string, unknown>;
+export interface AuthoringNode extends AuthoringData {
+    id: string;
+    type: string;
+    position: {
+        x: number;
+        y: number;
+    };
+    data: AuthoringData & {
+        label: string;
+        type: string;
+        enabled?: boolean;
+    };
+    parentId?: string;
+}
+export interface AuthoringEdge extends AuthoringData {
+    id: string;
+    source: string;
+    target: string;
+}
+export interface AuthoringRevisions {
+    flow: number;
+    nodes: Record<string, number>;
+    edges: Record<string, number>;
+    rules: Record<string, number>;
+}
+export type AuthoringSource = {
+    kind: "mongo";
+} | {
+    kind: "git";
+    formulaId: string;
+    repository: string;
+    path: string;
+    ref: string;
+};
+export interface AuthoringGitPublication {
+    source: Extract<AuthoringSource, {
+        kind: "git";
+    }>;
+    commitSha: string;
+    publishedVersion: number;
+    mongoRevisions: AuthoringRevisions;
+    contentHash: string;
+    publishedAt: string;
+    artifactHash?: string | null;
+    toolingHash?: string | null;
+}
+export interface AuthoringGitProjection {
+    source: Extract<AuthoringSource, {
+        kind: "git";
+    }>;
+    commitSha: string;
+    artifactHash: string;
+    toolingHash: string;
+    operationId: string;
+    mongoRevisions: AuthoringRevisions;
+    contentHash: string;
+    projectedAt: string;
+}
+export interface AuthoringPublication {
+    operationId: string;
+    expectedRevisions: AuthoringRevisions;
+    gitCommitSha?: string;
+    gitArtifactHash?: string;
+    gitToolingHash?: string;
+}
+export interface AuthoringFlowSummary extends AuthoringData {
+    authoringSource?: AuthoringSource | null;
+    lastGitPublication?: AuthoringGitPublication | null;
+    lastGitProjection?: AuthoringGitProjection | null;
+    createdAt?: string;
+    updatedAt?: string;
+    executionStats?: {
+        totalExecutions: number;
+        totalDocuments: number;
+    };
+    id: string;
+    name: string;
+    type?: "manual" | "assisted";
+    state?: string;
+    isDirty?: boolean;
+}
+export interface AuthoringSnapshot {
+    gitPublicationState?: {
+        status: "not_published" | "unchanged" | "diverged" | "staged";
+        currentContentHash: string;
+    } | null;
+    flow: AuthoringFlowSummary & {
+        configs?: AuthoringData;
+        nodes: AuthoringNode[];
+        edges: AuthoringEdge[];
+    };
+    rules: AuthoringData[];
+    revisions: AuthoringRevisions;
+    historyCounts: {
+        snapshots: number;
+        published: number;
+    };
+}
+export interface AuthoringChanges {
+    create?: AuthoringData[];
+    update?: {
+        id: string;
+        patch: AuthoringData;
+    }[];
+    delete?: string[];
+}
+export interface AuthoringDraft {
+    gitProjection?: {
+        commitSha: string;
+        artifactHash: string;
+        toolingHash: string;
+    };
+    authoringSource?: AuthoringSource;
+    operationId: string;
+    expectedRevisions: AuthoringRevisions;
+    flowPatch?: AuthoringData;
+    nodes?: AuthoringChanges;
+    edges?: AuthoringChanges;
+    prompts?: {
+        create?: AuthoringData[];
+        updateForNode?: string[];
+        delete?: string[];
+        upsertForNode?: {
+            id: string;
+            prompt: AuthoringData;
+        }[];
+    };
+    rules?: AuthoringData[];
+}
+export interface AuthoringCreate {
+    authoringSource?: AuthoringSource;
+    operationId: string;
+    id: string;
+    name: string;
+    type: "manual" | "assisted";
+    configs?: AuthoringData;
+    nodes: AuthoringNode[];
+    edges: AuthoringEdge[];
+}
+export interface AuthoringReceipt {
+    success: boolean;
+    id?: string;
+    version?: number;
+    flowUpdatedAt: string;
+    revisions: AuthoringRevisions;
+    committedRuleIds?: Record<string, string>;
+}
+export interface AuthoringOptions {
+    organization: string;
+    signal?: AbortSignal;
+}
+export interface AuthoringDocumentTrialNode {
+    id: string;
+    name: string;
+    type: "classification" | "extraction" | "metadata-extraction";
+    prompt?: {
+        metadata: AuthoringData;
+        messages: AuthoringData[];
+        schemaDatas: AuthoringData;
+    };
+    /** Native assisted definition; mutually exclusive with a manual prompt. */
+    assisted?: {
+        metadata: AuthoringData;
+        rules: AuthoringData[];
+        configs: AuthoringData;
+    };
+}
+export type AuthoringDocumentTrialSpec = {
+    flowId: string;
+    expectedRevisions: AuthoringRevisions;
+    node?: string;
+    allNodes?: boolean;
+} | {
+    nodes: AuthoringDocumentTrialNode[];
+};
+export interface AuthoringDocumentTrialReport {
+    executor?: "flows" | "docmana-api";
+    mode: "document-trial";
+    execution_scope: "isolated";
+    status: "completed" | "error";
+    rows: {
+        node: string;
+        name: string;
+        type: string;
+        status: "completed" | "error";
+        seconds: number;
+        output?: AuthoringData;
+        error?: string;
+    }[];
+}
+export interface AuthoringEditorCatalog {
+    capabilities?: {
+        canonicalProjection?: number;
+        runtimeEnvironment?: string;
+    };
+    models: {
+        default_model: string;
+        assisted_model?: string;
+        ai_provider: string;
+        models: {
+            model_name: string;
+            reasoning_effort_values?: string[] | null;
+            default_reasoning_effort?: string | null;
+        }[];
+    };
+    tools: (AuthoringData & {
+        tool_id: string;
+        tool_name?: string;
+        type?: string;
+        short_description_fr?: string;
+        short_description_en?: string;
+    })[];
+    systems: {
+        id: string;
+        name: string;
+        expectedFields?: AuthoringData[];
+    }[];
+    defaults: {
+        aggregator: string;
+    };
+    flags: {
+        flags: Record<string, boolean>;
+    };
+}
+export interface AuthoringConversationContext {
+    flow_id: string;
+    scope?: string | null;
+    node_id?: string | null;
+    node_label?: string | null;
+}
+export interface AuthoringConversation {
+    conversation_id: string;
+    expires_at: string;
+    context: AuthoringConversationContext;
+}
+export interface AuthoringConversationInput {
+    flow_id: string;
+    language: "fr" | "en";
+    scope?: string;
+    node_id?: string;
+    messages?: {
+        role: "user" | "assistant";
+        content: string;
+    }[];
+}
+export interface AuthoringConversationTurn {
+    assistant_message: string;
+    options?: unknown[] | null;
+    proposed_rule?: AuthoringData | null;
+    proposed_document_type_rename?: AuthoringData | null;
+    context: AuthoringConversationContext;
+    target_resolved: boolean;
+    expires_at: string;
+}
+export type AuthoringSort = "id" | "newest" | "oldest" | "recentlyModified" | "leastRecentlyModified" | "name";
+export interface AuthoringPageOptions extends AuthoringOptions {
+    sort?: AuthoringSort;
+    offset?: number;
+    limit?: number;
+}
+/** Aggregate authoring only. Caller retains operation IDs when retrying mutations. */
+export declare class FormulaAuthoring {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Read-only, revision-pinned definitions. Assisted execution belongs to the server-side Flows POC. */
+    documentTrialDefinitions(spec: {
+        flowId: string;
+        expectedRevisions: AuthoringRevisions;
+        node?: string;
+        allNodes?: boolean;
+    }, options: AuthoringOptions): Promise<{
+        nodes: AuthoringDocumentTrialNode[];
+    }>;
+    /** Native manual execution through Consumer Edge; assisted trials use definitions plus server-side Flows. */
+    trialDocument(file: Blob, filename: string, spec: AuthoringDocumentTrialSpec, options: AuthoringOptions): Promise<AuthoringDocumentTrialReport>;
+    editorCatalog(options: AuthoringOptions): Promise<AuthoringEditorCatalog>;
+    generateMapping(body: {
+        workflow_fields: AuthoringData[];
+        expected_fields: AuthoringData[];
+        current_mapping: string;
+        user_instructions: string;
+    }, options: AuthoringOptions): Promise<{
+        jsonataExpression: string;
+    }>;
+    openConversation(body: AuthoringConversationInput, options: AuthoringOptions): Promise<AuthoringConversation>;
+    sendConversationMessage(id: string, content: string, options: AuthoringOptions): Promise<AuthoringConversationTurn>;
+    confirmConversation(id: string, body: {
+        rule_id?: string;
+        document_type_rename?: boolean;
+    }, options: AuthoringOptions): Promise<{
+        expires_at: string;
+    }>;
+    private request;
+    list(options: AuthoringPageOptions): Promise<AuthoringFlowSummary[]>;
+    remove(id: string, options: AuthoringOptions): Promise<{
+        success: boolean;
+    }>;
+    exportArchive(id: string, options: AuthoringOptions): Promise<Uint8Array>;
+    importArchive(file: Blob, filename: string, options: AuthoringOptions & {
+        confirmOverwrite?: boolean;
+    }): Promise<{
+        status: "imported" | "confirmation_required";
+        flowName?: string;
+    }>;
+    get(id: string, options: AuthoringOptions): Promise<AuthoringSnapshot>;
+    create(body: AuthoringCreate, options: AuthoringOptions): Promise<AuthoringReceipt>;
+    save(id: string, body: AuthoringDraft, options: AuthoringOptions): Promise<AuthoringReceipt>;
+    validate(id: string, revisions: AuthoringRevisions, options: AuthoringOptions): Promise<AuthoringData>;
+    publish(id: string, body: AuthoringPublication, options: AuthoringOptions): Promise<AuthoringReceipt>;
+    history(id: string, kind: "snapshots" | "published", options: AuthoringPageOptions): Promise<AuthoringData[]>;
+    flags(options: AuthoringOptions): Promise<{
+        flags: Record<string, boolean>;
+    }>;
+}

package/dist/cli.mjs

@@ -36,11 +36,148 @@ function normalizeApiBaseUrl(value) {
   return /\/v\d+$/i.test(trimmed) ? trimmed : `${trimmed}/v1`;
 }
 
+// src/sdk/authoring.ts
+function identity(id) {
+  if (!/^[A-Za-z0-9_-]{1,200}$/.test(id)) throw new Error("Invalid formula identifier");
+  return encodeURIComponent(id);
+}
+var FormulaAuthoring = class {
+  constructor(http) {
+    this.http = http;
+  }
+  http;
+  /** Read-only, revision-pinned definitions. Assisted execution belongs to the server-side Flows POC. */
+  documentTrialDefinitions(spec, options) {
+    identity(spec.flowId);
+    if (Boolean(spec.node) === (spec.allNodes === true))
+      throw new Error("Select one node or all nodes");
+    if (spec.node) identity(spec.node);
+    return this.request("POST", "document-trial/definitions", options, spec);
+  }
+  /** Native manual execution through Consumer Edge; assisted trials use definitions plus server-side Flows. */
+  async trialDocument(file, filename, spec, options) {
+    if (!options.organization.trim()) throw new Error("Organization is required");
+    if (!file.size || file.size > 20 * 1024 * 1024 || !/\.(pdf|jpeg|jpg|png|bmp|tiff|tif|heic)$/i.test(filename))
+      throw new Error("Invalid trial document");
+    if ("flowId" in spec) {
+      identity(spec.flowId);
+      if (Boolean(spec.node) === (spec.allNodes === true))
+        throw new Error("Select one node or all nodes");
+      if (spec.node) identity(spec.node);
+    } else if (!Array.isArray(spec.nodes) || !spec.nodes.length || spec.nodes.length > 100)
+      throw new Error("Invalid trial nodes");
+    const body = new FormData();
+    body.set("file", file, filename);
+    body.set("spec", JSON.stringify(spec));
+    return this.http.requestJson("POST", "/authoring/document-trial", {
+      query: { organization: options.organization },
+      signal: options.signal,
+      body
+    });
+  }
+  editorCatalog(options) {
+    return this.request("GET", "editor-catalog", options);
+  }
+  generateMapping(body, options) {
+    return this.request("POST", "generate-mapping", options, body);
+  }
+  openConversation(body, options) {
+    identity(body.flow_id);
+    if (body.node_id) identity(body.node_id);
+    return this.request("POST", "conversations", options, body);
+  }
+  sendConversationMessage(id, content, options) {
+    return this.request("POST", `conversations/${identity(id)}/messages`, options, { content });
+  }
+  confirmConversation(id, body, options) {
+    return this.request("POST", `conversations/${identity(id)}/confirm`, options, body);
+  }
+  request(method, path, options, body) {
+    if (!options.organization.trim()) throw new Error("Organization is required");
+    return this.http.requestJson(method, `/authoring/${path}`, {
+      query: { organization: options.organization },
+      signal: options.signal,
+      ...body === void 0 ? {} : {
+        body: JSON.stringify(body),
+        headers: { "content-type": "application/json" }
+      }
+    });
+  }
+  list(options) {
+    const offset = options.offset ?? 0, limit = options.limit ?? 50;
+    if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 200)
+      throw new Error("Invalid authoring pagination");
+    return this.request(
+      "GET",
+      `flows?offset=${offset}&limit=${limit}&sort=${encodeURIComponent(options.sort ?? "id")}`,
+      options
+    );
+  }
+  remove(id, options) {
+    return this.request("DELETE", `flows/${identity(id)}`, options);
+  }
+  async exportArchive(id, options) {
+    if (!options.organization.trim()) throw new Error("Organization is required");
+    return (await this.http.requestBytes("GET", `/authoring/flows/${identity(id)}/export`, {
+      query: { organization: options.organization },
+      signal: options.signal
+    })).bytes;
+  }
+  importArchive(file, filename, options) {
+    if (!options.organization.trim()) throw new Error("Organization is required");
+    if (!/\.(zip|docmana)$/i.test(filename) || file.size > 10 * 1024 * 1024)
+      throw new Error("Invalid formula archive");
+    const body = new FormData();
+    body.append("file", file, filename);
+    return this.http.requestJson("POST", "/authoring/flows/import", {
+      query: {
+        organization: options.organization,
+        confirmOverwrite: String(options.confirmOverwrite === true)
+      },
+      body,
+      signal: options.signal
+    });
+  }
+  get(id, options) {
+    return this.request("GET", `flows/${identity(id)}`, options);
+  }
+  create(body, options) {
+    return this.request("POST", "flows", options, body);
+  }
+  save(id, body, options) {
+    return this.request("PATCH", `flows/${identity(id)}/draft`, options, body);
+  }
+  validate(id, revisions, options) {
+    return this.request("POST", `flows/${identity(id)}/validate`, options, {
+      expectedRevisions: revisions
+    });
+  }
+  publish(id, body, options) {
+    return this.request("POST", `flows/${identity(id)}/publish`, options, body);
+  }
+  history(id, kind, options) {
+    if (kind !== "snapshots" && kind !== "published") throw new Error("Invalid history kind");
+    const offset = options.offset ?? 0, limit = options.limit ?? 20;
+    if (!Number.isInteger(offset) || offset < 0 || !Number.isInteger(limit) || limit < 1 || limit > 100)
+      throw new Error("Invalid history pagination");
+    return this.request(
+      "GET",
+      `flows/${identity(id)}/history/${kind}?offset=${offset}&limit=${limit}`,
+      options
+    );
+  }
+  flags(options) {
+    return this.request("GET", "feature-flags", options);
+  }
+};
+
 // src/sdk/errors.ts
 var DocmanaError = class extends Error {
   status;
   requestId;
   code;
+  /** Public API business code; `code` retains the SDK's existing error category. */
+  apiCode;
   constructor(message, opts = {}) {
     super(message);
     this.name = new.target.name;
@@ -169,12 +306,16 @@ var HttpClient = class {
     if (!res.ok) {
       const requestId = res.headers.get("x-request-id") ?? void 0;
       const message = await this.extractMessage(res);
-      throw errorFromResponse(
+      const error = errorFromResponse(
         res.status,
         message,
         requestId,
         parseRetryAfterMs(res.headers.get("retry-after"))
       );
+      const data = await res.clone().json().catch(() => null);
+      if (typeof data?.code === "string" && /^[A-Za-z][A-Za-z0-9_]{0,99}$/.test(data.code))
+        Object.defineProperty(error, "apiCode", { value: data.code, enumerable: true });
+      throw error;
     }
     return res;
   }
@@ -674,6 +815,7 @@ function fullJitterDelay(intervalMs, maxIntervalMs, attempt, random) {
 
 // src/sdk/client.ts
 var Docmana = class {
+  authoring;
   config;
   http;
   constructor(config) {
@@ -685,6 +827,7 @@ var Docmana = class {
       getAccessToken: this.config.getAccessToken,
       headers: this.config.headers
     });
+    this.authoring = new FormulaAuthoring(this.http);
   }
   async runFlowAsync(flowId, params, options = {}) {
     const parts = await resolveInputs(params);