@docmana/sdk 0.28.1 → 0.36.0-hitl.2

package/dist/reviews.d.ts

@@ -0,0 +1,180 @@
+import type { HttpClient } from "./http/http-client.js";
+import type { ExecutionStatus } from "./models/execution-status.enum.js";
+export interface ReviewCalculation {
+    executionResultId: string;
+    executionStatus: ExecutionStatus;
+    /** Null for legacy/unmarked executions. Never inferred from review status. */
+    calculation: {
+        /** Review owning these coherent outputs; absent during calculation/finalization. */
+        reviewId?: string;
+        mode: "runAhead";
+        status: "calculating" | "completed" | "recalculating" | "finalizing" | "finalized" | "failed";
+        /** Coherent calculation revision; distinct from ReviewTask.version. */
+        revision: number;
+        targetRevision?: number;
+        provisional: boolean;
+        totalReviews?: number;
+        approvedReviews?: number;
+        remainingReviews?: number;
+        /** Node executions, not individual model calls. */
+        computedNodes?: number;
+        reusedNodes?: number;
+    } | null;
+}
+export interface ReviewFlowOutline {
+    flowId: string;
+    name?: string;
+    version: number | null;
+    nodes: Array<{
+        nodeId: string;
+        name?: string | null;
+        label?: string | null;
+        type: string;
+        enabled: boolean;
+        order: number;
+        humanReview?: {
+            enabled: boolean;
+            instructions?: string;
+            skipWhenScoreAtLeast?: number | null;
+        };
+    }>;
+    edges: Array<{
+        source: string;
+        target: string;
+    }>;
+}
+export interface DocumentPreviewManifest {
+    status: "queued" | "processing" | "ready" | "limited" | "failed" | "unavailable";
+    version: string;
+    pageCount: number;
+    renderedPages: number;
+    pages: Array<{
+        number: number;
+        width?: number;
+        height?: number;
+    }>;
+    retryAfterMs: number;
+}
+export interface ReviewItem {
+    itemId: string;
+    kind: "field" | "classification" | "status";
+    nodeId: string | null;
+    nodeName: string;
+    field: string;
+    value: unknown;
+}
+export interface ReviewDocument {
+    docKey: string;
+    name: string | null;
+    pageFrom?: number | null;
+    pageTo?: number | null;
+    pageCount?: number | null;
+    pages?: Array<{
+        number: number;
+        imageUrl: string;
+        thumbnailUrl: string;
+    }>;
+    renderedPages?: number;
+    pagesComplete?: boolean;
+    contentUrl?: string;
+    items?: ReviewItem[];
+    context?: ReviewItem[];
+    /** Read-only evidence from the frozen pause; absent on older backends. */
+    assessments?: ReviewAssessment[];
+}
+export interface ReviewAssessment {
+    nodeId: string | null;
+    nodeName: string;
+    /** Stored node score, 0..100. Not a per-field confidence estimate. */
+    score?: number;
+    scoreDescription?: unknown;
+    feedback?: unknown;
+    explanation?: unknown;
+    reasoning?: unknown;
+}
+export interface ReviewSummary {
+    reviewId: string;
+    executionResultId: string;
+    flowId: string;
+    flowVersion: number | string | null;
+    status: string;
+    version: number;
+    createdAt?: string | null;
+    expiresAt: string | null;
+    node: {
+        nodeId: string;
+        nodeName: string | null;
+        nodeType: string | null;
+        instructions?: string;
+    };
+    documents: ReviewDocument[];
+    level?: "dossier";
+}
+export interface ReviewTask extends ReviewSummary {
+    /** Explicit frozen field signals. Missing/empty keeps legacy UI and global confirmation. */
+    findings?: ReviewFinding[];
+    /** Native lifecycle timestamps, absent on older backends; never inferred from callbacks. */
+    submittedAt?: string | null;
+    resumingAt?: string | null;
+    closedAt?: string | null;
+}
+export interface ReviewFinding {
+    id: string;
+    code: string;
+    /** Producer's concise user-facing explanation, never hidden model reasoning. */
+    message: string;
+    itemIds: string[];
+    source?: "model" | "rule";
+}
+export interface ReviewDecision {
+    decision: "continue" | "exclude" | "rerun" | "reject";
+    reviewer: string;
+    version: number;
+    corrections?: Array<{
+        itemId: string;
+        value: unknown;
+    }>;
+    excludedDocuments?: string[];
+    rerunDocuments?: string[];
+    hint?: string;
+    reason?: string;
+}
+export interface ReviewReadOptions {
+    organization: string;
+    signal?: AbortSignal;
+}
+export interface ReviewDocumentOptions extends ReviewReadOptions {
+    version?: string;
+    size?: "full" | "thumb";
+    range?: string;
+    ifRange?: string;
+    ifNoneMatch?: string;
+    ifModifiedSince?: string;
+}
+/** Human review of a formula execution. Independent of pipelines and final callbacks. */
+export declare class Reviews {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** Repeatable metadata read: never consumes the final execution result. */
+    calculation(executionId: string, options: ReviewReadOptions): Promise<ReviewCalculation>;
+    /** Published formula structure only. Compare its version with the review's flowVersion. */
+    outline(flowId: string, options: ReviewReadOptions): Promise<ReviewFlowOutline>;
+    list(options: ReviewReadOptions & {
+        status?: "pending" | "submitted" | "resuming";
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        reviews: ReviewSummary[];
+        nextCursor: string | null;
+    }>;
+    get(executionId: string, options: ReviewReadOptions): Promise<ReviewTask>;
+    decide(executionId: string, decision: ReviewDecision, options: ReviewReadOptions): Promise<{
+        executionResultId: string;
+        reviewId: string;
+        status: "Queued";
+    }>;
+    /** Streaming Response: callers own consumption/cancellation. Never buffers the PDF. */
+    document(executionId: string, docKey: string, resource: "content" | "locations" | "preview" | {
+        page: number;
+    }, options: ReviewDocumentOptions): Promise<Response>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docmana/sdk",
-  "version": "0.28.1",
+  "version": "0.36.0-hitl.2",
   "description": "Official Docmana SDK — run document-analysis flows with a single call.",
   "license": "MIT",
   "type": "module",