@abyss-project/tools 1.0.5 → 1.2.0

package/src/types/interface/models/board-card-comment.dto.ts

@@ -1,15 +1,15 @@
-import { IBoardCard } from './board-card.dto';
-import { IUser } from './user.dto';
-
-export interface IBoardCardComment {
-  id: string;
-  boardCardId: string;
-  content: string;
-  userId: string | null;
-  updatedAt?: Date;
-  createdAt?: Date;
-
-  // Association
-  boardCard?: IBoardCard;
-  user?: IUser | null;
-}
+import { IBoardCard } from './board-card.dto';
+import { IUser } from './user.dto';
+
+export interface IBoardCardComment {
+  id: string;
+  boardCardId: string;
+  content: string;
+  userId: string | null;
+  updatedAt?: Date;
+  createdAt?: Date;
+
+  // Association
+  boardCard?: IBoardCard;
+  user?: IUser | null;
+}

package/src/types/interface/models/board-card-document.dto.ts

@@ -1,22 +1,22 @@
-import { IBoardCard } from './board-card.dto';
-import { IBoard } from './board.dto';
-
-export interface IBoardCardDocument {
-  id: string;
-  boardCardId: string;
-  boardId: string;
-  name: string;
-  externalId: string;
-  publicAccessId: string;
-  thumbnailId: string | null;
-  thumbnailPublicAccessId: string | null;
-  checksum: string;
-  mimeType: string;
-  sizeOctet: number;
-  updatedAt?: Date;
-  createdAt?: Date;
-
-  // Association
-  boardCard: IBoardCard;
-  board: IBoard;
-}
+import { IBoardCard } from './board-card.dto';
+import { IBoard } from './board.dto';
+
+export interface IBoardCardDocument {
+  id: string;
+  boardCardId: string;
+  boardId: string;
+  name: string;
+  externalId: string;
+  publicAccessId: string;
+  thumbnailId: string | null;
+  thumbnailPublicAccessId: string | null;
+  checksum: string;
+  mimeType: string;
+  sizeOctet: number;
+  updatedAt?: Date;
+  createdAt?: Date;
+
+  // Association
+  boardCard: IBoardCard;
+  board: IBoard;
+}

package/src/types/interface/models/board-card-label.dto.ts

@@ -1,14 +1,14 @@
-import { IBoardCard } from './board-card.dto';
-import { IBoardLabel } from './board-label.dto';
-
-export interface IBoardCardLabel {
-  id: string;
-  boardLabelId: string;
-  boardCardId: string;
-  updatedAt?: Date;
-  createdAt?: Date;
-
-  // Association
-  boardLabel?: IBoardLabel;
-  boardCard?: IBoardCard;
-}
+import { IBoardCard } from './board-card.dto';
+import { IBoardLabel } from './board-label.dto';
+
+export interface IBoardCardLabel {
+  id: string;
+  boardLabelId: string;
+  boardCardId: string;
+  updatedAt?: Date;
+  createdAt?: Date;
+
+  // Association
+  boardLabel?: IBoardLabel;
+  boardCard?: IBoardCard;
+}

package/src/types/interface/models/board-card-member.dto.ts

@@ -1,14 +1,14 @@
-import { IBoardCard } from './board-card.dto';
-import { IUser } from './user.dto';
-
-export interface IBoardCardMember {
-  id: string;
-  boardCardId: string;
-  userId: string;
-  updatedAt?: Date;
-  createdAt?: Date;
-
-  // Association
-  boardCard: IBoardCard;
-  user: IUser;
-}
+import { IBoardCard } from './board-card.dto';
+import { IUser } from './user.dto';
+
+export interface IBoardCardMember {
+  id: string;
+  boardCardId: string;
+  userId: string;
+  updatedAt?: Date;
+  createdAt?: Date;
+
+  // Association
+  boardCard: IBoardCard;
+  user: IUser;
+}

package/src/types/interface/models/board-card.dto.ts

@@ -1,37 +1,37 @@
-import { IBoardActivity } from './board-activity.dto';
-import { IBoardCardChecklist } from './board-card-checklist.dto';
-import { IBoardCardComment } from './board-card-comment.dto';
-import { IBoardCardDocument } from './board-card-document.dto';
-import { IBoardCardLabel } from './board-card-label.dto';
-import { IBoardCardMember } from './board-card-member.dto';
-import { IBoardColumn } from './board-column.dto';
-import { IBoard } from './board.dto';
-
-export interface IBoardCard {
-  id: string;
-  slug: string;
-  identifier: number;
-  boardColumnId: string | null;
-  boardId: string;
-  title: string;
-  description: string | null;
-  weight: number | null;
-  position: number;
-  startDate: Date | null;
-  endDate: Date | null;
-  bannerId: string | null;
-  updatedAt?: Date;
-  createdAt?: Date;
-  deletedAt?: Date | null;
-
-  // Association
-  board: IBoard;
-  boardColumn: IBoardColumn;
-  boardActivities: IBoardActivity[];
-  boardCardMembers: IBoardCardMember[];
-  boardCardDocuments: IBoardCardDocument[];
-  boardCardChecklists: IBoardCardChecklist[];
-  boardCardComments?: IBoardCardComment[];
-  boardCardLabels?: IBoardCardLabel[];
-  banner?: IBoardCardDocument | null;
-}
+import { IBoardActivity } from './board-activity.dto';
+import { IBoardCardChecklist } from './board-card-checklist.dto';
+import { IBoardCardComment } from './board-card-comment.dto';
+import { IBoardCardDocument } from './board-card-document.dto';
+import { IBoardCardLabel } from './board-card-label.dto';
+import { IBoardCardMember } from './board-card-member.dto';
+import { IBoardColumn } from './board-column.dto';
+import { IBoard } from './board.dto';
+
+export interface IBoardCard {
+  id: string;
+  slug: string;
+  identifier: number;
+  boardColumnId: string | null;
+  boardId: string;
+  title: string;
+  description: string | null;
+  weight: number | null;
+  position: number;
+  startDate: Date | null;
+  endDate: Date | null;
+  bannerId: string | null;
+  updatedAt?: Date;
+  createdAt?: Date;
+  deletedAt?: Date | null;
+
+  // Association
+  board: IBoard;
+  boardColumn: IBoardColumn;
+  boardActivities: IBoardActivity[];
+  boardCardMembers: IBoardCardMember[];
+  boardCardDocuments: IBoardCardDocument[];
+  boardCardChecklists: IBoardCardChecklist[];
+  boardCardComments?: IBoardCardComment[];
+  boardCardLabels?: IBoardCardLabel[];
+  banner?: IBoardCardDocument | null;
+}

package/src/types/interface/models/board-column.dto.ts

@@ -1,17 +1,17 @@
-import { BoardColumnType } from '../../enum';
-import { IBoardCard } from './board-card.dto';
-import { IBoard } from './board.dto';
-
-export interface IBoardColumn {
-  id: string;
-  title: string;
-  position: number;
-  boardId: string;
-  type: BoardColumnType;
-  updatedAt?: Date;
-  createdAt?: Date;
-
-  // Association
-  board: IBoard;
-  boardCards: IBoardCard[];
-}
+import { BoardColumnType } from '../../enum';
+import { IBoardCard } from './board-card.dto';
+import { IBoard } from './board.dto';
+
+export interface IBoardColumn {
+  id: string;
+  title: string;
+  position: number;
+  boardId: string;
+  type: BoardColumnType;
+  updatedAt?: Date;
+  createdAt?: Date;
+
+  // Association
+  board: IBoard;
+  boardCards: IBoardCard[];
+}

package/src/types/interface/models/board-label.dto.ts

@@ -1,13 +1,13 @@
-import { IBoard } from './board.dto';
-
-export interface IBoardLabel {
-  id: string;
-  name: string;
-  color: string;
-  boardId: string;
-  updatedAt?: Date;
-  createdAt?: Date;
-
-  // Association
-  board: IBoard;
-}
+import { IBoard } from './board.dto';
+
+export interface IBoardLabel {
+  id: string;
+  name: string;
+  color: string;
+  boardId: string;
+  updatedAt?: Date;
+  createdAt?: Date;
+
+  // Association
+  board: IBoard;
+}

package/src/types/interface/models/board.dto.ts

@@ -1,33 +1,33 @@
-import { IBoardActivity } from './board-activity.dto';
-import { IBoardCardDocument } from './board-card-document.dto';
-import { IBoardCard } from './board-card.dto';
-import { IBoardColumn } from './board-column.dto';
-import { IBoardLabel } from './board-label.dto';
-import { IOrganization } from './organization.dto';
-import { IProject } from './project.dto';
-import { IEntityTag } from './tag.dto';
-import { IUser } from './user.dto';
-
-export interface IBoard {
-  id: string;
-  slug: string;
-  title: string;
-  userId: string | null;
-  projectId: string | null;
-  organizationId: string | null;
-  createdByUserId: string | null;
-  archivedAt: Date | null;
-  updatedAt?: Date;
-  createdAt?: Date;
-
-  // Association
-  boardColumns?: IBoardColumn[];
-  boardActivities?: IBoardActivity[];
-  boardCards?: IBoardCard[];
-  user?: IUser | null;
-  project?: IProject | null;
-  organization?: IOrganization | null;
-  boardLabels?: IBoardLabel[];
-  boardCardDocuments?: IBoardCardDocument[];
-  entityTags?: IEntityTag[];
-}
+import { IBoardActivity } from './board-activity.dto';
+import { IBoardCardDocument } from './board-card-document.dto';
+import { IBoardCard } from './board-card.dto';
+import { IBoardColumn } from './board-column.dto';
+import { IBoardLabel } from './board-label.dto';
+import { IOrganization } from './organization.dto';
+import { IProject } from './project.dto';
+import { IEntityTag } from './tag.dto';
+import { IUser } from './user.dto';
+
+export interface IBoard {
+  id: string;
+  slug: string;
+  title: string;
+  userId: string | null;
+  projectId: string | null;
+  organizationId: string | null;
+  createdByUserId: string | null;
+  archivedAt: Date | null;
+  updatedAt?: Date;
+  createdAt?: Date;
+
+  // Association
+  boardColumns?: IBoardColumn[];
+  boardActivities?: IBoardActivity[];
+  boardCards?: IBoardCard[];
+  user?: IUser | null;
+  project?: IProject | null;
+  organization?: IOrganization | null;
+  boardLabels?: IBoardLabel[];
+  boardCardDocuments?: IBoardCardDocument[];
+  entityTags?: IEntityTag[];
+}

package/src/types/interface/models/content-share.dto.ts

@@ -1,16 +1,16 @@
-import { ShareableContentType, SharePermission, ShareTargetType } from '../../enum/content-share.enum';
-
-export interface IContentShare {
-  id: string;
-  contentType: ShareableContentType;
-  contentId: string;
-  organizationId: string | null;
-  targetType: ShareTargetType;
-  targetId: string | null;
-  permission: SharePermission;
-  publicToken: string | null;
-  expiresAt: string | null;
-  createdByUserId: string;
-  createdAt: string;
-  updatedAt: string;
-}
+import { ShareableContentType, SharePermission, ShareTargetType } from '../../enum/content-share.enum';
+
+export interface IContentShare {
+  id: string;
+  contentType: ShareableContentType;
+  contentId: string;
+  organizationId: string | null;
+  targetType: ShareTargetType;
+  targetId: string | null;
+  permission: SharePermission;
+  publicToken: string | null;
+  expiresAt: string | null;
+  createdByUserId: string;
+  createdAt: string;
+  updatedAt: string;
+}

package/src/types/interface/models/draw.dto.ts

@@ -1,30 +1,30 @@
-import { IOrganization } from './organization.dto';
-import { IProject } from './project.dto';
-import { IEntityTag } from './tag.dto';
-import { IUser } from './user.dto';
-
-export interface IDraw {
-  id: string;
-  title: string;
-  content: string;
-  userId: string | null;
-  projectId: string | null;
-  organizationId: string | null;
-  createdByUserId: string | null;
-  fileId: string | null;
-  filePublicAccessId: string | null;
-  thumbnailId: string | null;
-  thumbnailPublicAccessId: string | null;
-  sizeOctet: number;
-  mimeType: string;
-  checksum: string;
-  archivedAt?: Date | null;
-  updatedAt?: Date;
-  createdAt?: Date;
-
-  // Association
-  user?: IUser | null;
-  project?: IProject | null;
-  organization?: IOrganization | null;
-  entityTags?: IEntityTag[];
-}
+import { IOrganization } from './organization.dto';
+import { IProject } from './project.dto';
+import { IEntityTag } from './tag.dto';
+import { IUser } from './user.dto';
+
+export interface IDraw {
+  id: string;
+  title: string;
+  content: string;
+  userId: string | null;
+  projectId: string | null;
+  organizationId: string | null;
+  createdByUserId: string | null;
+  fileId: string | null;
+  filePublicAccessId: string | null;
+  thumbnailId: string | null;
+  thumbnailPublicAccessId: string | null;
+  sizeOctet: number;
+  mimeType: string;
+  checksum: string;
+  archivedAt?: Date | null;
+  updatedAt?: Date;
+  createdAt?: Date;
+
+  // Association
+  user?: IUser | null;
+  project?: IProject | null;
+  organization?: IOrganization | null;
+  entityTags?: IEntityTag[];
+}

package/src/types/interface/models/extraction-fetched-provenance.dto.test.ts

@@ -0,0 +1,193 @@
+// Type-level compile test — no jest runner in this package.
+// Verifies the FETCHED-extraction DTO (the GET extraction response / IExtraction)
+// surfaces the additive V2-P1 provenance + manifest fields type-safely, while
+// staying backward-compatible for old readers of value+confidence.
+// Run: npx tsc --noEmit (from packages/abyss_tools_core).
+
+import { ProviderKind, InterpreterKind, CombineStrategy } from '../../enum';
+import type { IExtraction } from './extraction.dto';
+import type { IFieldValue, IExecutionManifest, IGlobalConfidence } from './extraction-plan.dto';
+import type { IGetExtractionData } from '../api/responses/extraction.response';
+
+// A fully-populated plan-path field value (the IFieldValue superset).
+const fv: IFieldValue = {
+  value: 120,
+  confidence: 0.95,
+  chosen: {
+    provider: ProviderKind.TEXT,
+    interpreter: InterpreterKind.ALGORITHMIC,
+    providerId: 'pdf-auto',
+    interpreterId: 'algo-v1',
+  },
+  sources: [
+    {
+      mode: {
+        provider: ProviderKind.TEXT,
+        interpreter: InterpreterKind.ALGORITHMIC,
+        providerId: 'pdf-auto',
+        interpreterId: 'algo-v1',
+      },
+      value: 120,
+      confidence: 0.95,
+      signals: [],
+    },
+  ],
+  agreement: { agreed: false, distinctValues: 1 },
+  signals: [],
+};
+
+// A field value carrying NON-EMPTY signals — exercises every variant of the
+// ISignal discriminated union so a future drift between the SDK union and the
+// backend `Signal` shape (e.g. re-adding the invented `score` field, or
+// dropping `check`/`passed`/`agreed`/`modes`) fails compilation here.
+const fvWithSignals: IFieldValue = {
+  value: 'FR7630001007941234567890185',
+  confidence: 0.98,
+  chosen: {
+    provider: ProviderKind.TEXT,
+    interpreter: InterpreterKind.ALGORITHMIC,
+    providerId: 'pdf-auto',
+    interpreterId: 'algo-v1',
+  },
+  sources: [
+    {
+      mode: {
+        provider: ProviderKind.TEXT,
+        interpreter: InterpreterKind.ALGORITHMIC,
+        providerId: 'pdf-auto',
+        interpreterId: 'algo-v1',
+      },
+      value: 'FR7630001007941234567890185',
+      confidence: 0.98,
+      signals: [
+        { kind: 'format', check: 'iban_mod97', passed: true, weight: 0.2 },
+        { kind: 'anchor', detail: "matched near 'IBAN' label", weight: 0.1 },
+      ],
+    },
+  ],
+  agreement: { agreed: true, distinctValues: 1 },
+  signals: [
+    { kind: 'format', check: 'iban_mod97', passed: true, weight: 0.2 },
+    { kind: 'coherence', check: 'balance_reconciliation', passed: true, weight: 0.3 },
+    { kind: 'agreement', agreed: true, modes: 2, weight: 0.1 },
+  ],
+};
+void fvWithSignals;
+
+// A CONSUMER narrows the ISignal union by `kind` and reads the discriminant
+// fields that actually exist on the wire — type-safe, no cast.
+for (const sig of fvWithSignals.signals) {
+  if (sig.kind === 'format' || sig.kind === 'coherence') {
+    const _check: string = sig.check;
+    const _passed: boolean = sig.passed;
+    void _check; void _passed;
+  } else if (sig.kind === 'anchor') {
+    const _detail: string = sig.detail;
+    void _detail;
+  } else {
+    const _agreed: boolean = sig.agreed;
+    const _modes: number = sig.modes;
+    void _agreed; void _modes;
+  }
+}
+
+// Mirrors the persisted backend ExecutionManifest shape (resolvedPlan + combine
+// + passes + createdAt) — exactly what GET /extractions/:id surfaces via toJSON().
+const manifest: IExecutionManifest = {
+  resolvedPlan: {
+    stages: [
+      { runParallel: false, passes: [{ providerId: 'pdf-auto', interpreterId: 'algo-v1' }] },
+    ],
+    combine: CombineStrategy.MAX_CONFIDENCE,
+  },
+  combine: CombineStrategy.MAX_CONFIDENCE,
+  passes: [
+    { providerId: 'pdf-auto', providerVersion: '1.0.0', interpreterId: 'algo-v1', interpreterVersion: '1.0.0' },
+  ],
+  createdAt: '2026-06-28T00:00:00.000Z',
+};
+
+// Mirrors the persisted backend GlobalConfidence shape (stats + method +
+// aggregation + perPass + lowestFields).
+const globalConfidence: IGlobalConfidence = {
+  stats: {
+    overall: 0.95,
+    mean: 0.95,
+    highest: 0.95,
+    lowest: 0.95,
+    median: 0.95,
+    belowThreshold: { threshold: 0.7, count: 0 },
+    fieldCount: 1,
+  },
+  method: CombineStrategy.MAX_CONFIDENCE,
+  aggregation: 'weighted-by-field-importance',
+  perPass: [
+    {
+      mode: {
+        provider: ProviderKind.TEXT,
+        interpreter: InterpreterKind.ALGORITHMIC,
+        providerId: 'pdf-auto',
+        interpreterId: 'algo-v1',
+      },
+      confidence: 0.95,
+      fieldsContributed: 1,
+      ocrPageCount: 0,
+    },
+  ],
+  lowestFields: [{ fieldKey: 'totalTtc', confidence: 0.95 }],
+};
+
+// The fetched-extraction model carries provenance fieldsJson + manifest +
+// globalConfidence + usedOcr/ocrPageCount type-safely.
+const fetched: Partial<IExtraction> = {
+  fieldsJson: { totalTtc: fv },
+  executionManifest: manifest,
+  globalConfidence,
+  usedOcr: true,
+  ocrPageCount: 3,
+};
+void fetched;
+
+// A CONSUMER reading the chosen impl id + sources off the fetched field value —
+// no cast needed (this is the whole point of the surfacing fix).
+const totalTtc = (fetched.fieldsJson ?? {}).totalTtc;
+if (totalTtc) {
+  const _chosenId: string = totalTtc.chosen.interpreterId;
+  const _sourceCount: number = totalTtc.sources.length;
+  void _chosenId; void _sourceCount;
+}
+
+// Backward-compat: an old reader that only knows value+confidence still works.
+const _legacyRead: { value: unknown; confidence: number } | undefined =
+  (fetched.fieldsJson ?? {}).totalTtc;
+void _legacyRead;
+
+// The GET extraction response data exposes the same superset under `fields`
+// AND inherits manifest + globalConfidence from IExtraction.
+const getData: Partial<IGetExtractionData> = {
+  fields: { totalTtc: fv },
+  executionManifest: manifest,
+  globalConfidence,
+};
+void getData;
+
+// usedOcr/ocrPageCount remain readable as before.
+const _usedOcr: boolean | undefined = fetched.usedOcr;
+const _ocrPages: number | undefined = fetched.ocrPageCount;
+void _usedOcr; void _ocrPages;
+
+// A CONSUMER reads the manifest + globalConfidence fields that the backend
+// actually persists/surfaces (createdAt — NOT resolvedAt — and the stats block),
+// type-safely off the fetched extraction.
+if (fetched.executionManifest) {
+  const _createdAt: string = fetched.executionManifest.createdAt;
+  const _passCount: number = fetched.executionManifest.passes.length;
+  void _createdAt; void _passCount;
+}
+if (fetched.globalConfidence) {
+  const _overall: number = fetched.globalConfidence.stats.overall;
+  const _agg: 'weighted-by-field-importance' = fetched.globalConfidence.aggregation;
+  void _overall; void _agg;
+}
+
+export {};

package/src/types/interface/models/extraction-plan.dto.test.ts

@@ -0,0 +1,47 @@
+// Type-level compile test — no jest runner in this package.
+// Each block verifies that the SDK types compile correctly.
+// Run: npx tsc --noEmit (from packages/abyss_tools_core).
+
+import { ProviderKind, InterpreterKind, CombineStrategy } from '../../enum';
+import type { IExtractionPlan, IFieldValue, IExtractModesData, IPositionedToken } from './extraction-plan.dto';
+
+// Verify enum string values match the api side.
+const _pk: string = ProviderKind.TEXT; // 'text'
+const _ik: string = InterpreterKind.TEMPLATE; // 'template'
+const _cs: string = CombineStrategy.MAX_CONFIDENCE; // 'maxConfidence'
+void _pk; void _ik; void _cs;
+
+// Verify IFieldValue is a structural superset of {value,confidence}.
+const fv: IFieldValue = {
+  value: 1,
+  confidence: 0.9,
+  chosen: {
+    provider: ProviderKind.TEXT,
+    interpreter: InterpreterKind.ALGORITHMIC,
+    providerId: 'pdf-text',
+    interpreterId: 'algo-v1',
+  },
+  sources: [],
+  signals: [],
+};
+// Must be assignable to the legacy shape without cast.
+const _legacy: { value: unknown; confidence: number } = fv;
+void _legacy;
+
+// Verify IExtractModesData typing compiles.
+const _modes: IExtractModesData = { providers: [], interpreters: [] };
+void _modes;
+
+// Verify IExtractionPlan typing compiles.
+const _plan: IExtractionPlan = {
+  stages: [{ runParallel: false, passes: [{ providerId: 'pdf-text', interpreterId: 'algo-v1' }] }],
+  combine: CombineStrategy.MAX_CONFIDENCE,
+};
+void _plan;
+
+// Verify IPositionedToken is { text, page, bbox{x,y,w,h}, conf? } (conf optional).
+const _tok: IPositionedToken = { text: 'IBAN', page: 1, bbox: { x: 1, y: 2, w: 3, h: 4 }, conf: 95 };
+const _tokNoConf: IPositionedToken = { text: 'x', page: 2, bbox: { x: 0, y: 0, w: 1, h: 1 } };
+void _tok; void _tokNoConf;
+
+export {};