@docmana/sdk 0.28.1 → 0.32.0

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);