@abyss-project/tools 1.0.5 → 1.2.0

package/src/types/interface/models/{rcb.dto.ts → extraction.dto.ts}

@@ -1,267 +1,317 @@
-// ──────────────────────────────────────────────
-// RCB (Relevé de Compte Bancaire) DTOs.
-// Mirror server-side Sequelize models, dates serialized as ISO strings.
-// ──────────────────────────────────────────────
-
-export type RcbExtractionMode = 'auto' | 'hint' | 'template';
-export type RcbProcessingMode = 'sync' | 'queue';
-export type RcbExtractionStatus = 'pending' | 'completed' | 'failed' | 'cached';
-
-export type RcbFeedbackIssueType =
-  | 'missing_record'
-  | 'wrong_sign'
-  | 'wrong_amount'
-  | 'wrong_date'
-  | 'wrong_description'
-  | 'duplicate'
-  | 'other';
-
-export type RcbFeedbackStatus = 'open' | 'triaged' | 'fixed' | 'closed';
-
-export type RcbUsageEventType =
-  | 'extract.sync.success'
-  | 'extract.sync.cached'
-  | 'extract.sync.failed'
-  | 'extract.queue.enqueued'
-  | 'extract.queue.success'
-  | 'extract.queue.cached'
-  | 'extract.queue.failed'
-  | 'template.run.success'
-  | 'template.run.failed';
-
-export interface IRcbBankHint {
-  bank: string;
-  version?: string;
-}
-
-export interface IRcbTransaction {
-  date?: string;
-  description?: string;
-  amount?: number;
-  balance?: number;
-  valueDate?: string;
-  bookingDate?: string;
-  reference?: string;
-  [k: string]: unknown;
-}
-
-export interface IRcbExtractionMetadata {
-  iban?: string;
-  bic?: string;
-  bank?: string;
-  accountHolder?: string;
-  periodStart?: string;
-  periodEnd?: string;
-  openingBalance?: number;
-  closingBalance?: number;
-  currency?: string;
-  [k: string]: unknown;
-}
-
-export interface IRcbFile {
-  id: string;
-  userId: string;
-  applicationId: string | null;
-  pdfHash: string;
-  pdfSizeBytes: number;
-  pdfMimeType: string;
-  pdfPageCount: number | null;
-  pdfFilename: string | null;
-  applicationFileId: string | null;
-  userExternalId: string | null;
-  userMetadata: Record<string, unknown> | null;
-  detectedBank: string | null;
-  detectedVersion: string | null;
-  detectedIban: string | null;
-  detectedBic: string | null;
-  detectedCurrency: string | null;
-  createdAt: string;
-  updatedAt: string;
-}
-
-// Structured warning emitted by the extraction orchestrator. The `code`
-// is the i18n key suffix, `data` carries numeric/string values the UI
-// formats locally (currencies, dates, etc.).
-export enum RcbWarningCode {
-  NO_RECORDS = 'no_records',
-  NO_IBAN = 'no_iban',
-  NO_BALANCES = 'no_balances',
-  BALANCE_MISMATCH = 'balance_mismatch',
-}
-
-export interface IRcbWarning {
-  code: RcbWarningCode;
-  data?: {
-    actualCents?: number;
-    expectedCents?: number;
-    currency?: string;
-  };
-}
-
-export interface IRcbExtraction {
-  id: string;
-  fileId: string;
-  mode: RcbExtractionMode;
-  hintBank: string | null;
-  hintVersion: string | null;
-  templateId: string | null;
-  templateVersion: number | null;
-  status: RcbExtractionStatus;
-  strategyUsed: string | null;
-  confidence: number | null;
-  recordsCount: number | null;
-  balanceValidated: boolean | null;
-  durationMs: number | null;
-  error: string | null;
-  recordsJson: IRcbTransaction[] | null;
-  metadataJson: IRcbExtractionMetadata | null;
-  warningsJson: IRcbWarning[] | null;
-  tags: string[] | null;
-  note: string | null;
-  shareToken: string | null;
-  shareExpiresAt: string | null;
-  createdAt: string;
-}
-
-export interface IRcbTemplate {
-  id: string;
-  userId: string;
-  name: string;
-  description: string | null;
-  isActive: boolean;
-  createdAt: string;
-  updatedAt: string;
-}
-
-/**
- * Spatial zone on a PDF page (PDF coords: origin bottom-left, points).
- * Restricts regex matching to a specific rectangle.
- */
-export interface IRcbTemplateZone {
-  name: string;
-  page: number; // 1-indexed
-  x: number;
-  y: number;
-  w: number;
-  h: number;
-}
-
-/**
- * Typed shape of the template DSL JSON stored in `templateJson`. Mirrors
- * `TemplateDSL` server-side. UI editors should narrow `templateJson` to this
- * shape via `templateJson as IRcbTemplateDsl`.
- */
-export interface IRcbTemplateDsl {
-  regex_iban?: string;
-  regex_bic?: string;
-  period?: { regex: string };
-  balance?: { opening_regex?: string; closing_regex?: string };
-  transactions?: {
-    row_pattern: string;
-    date_format?: string;
-    amount_locale?: 'fr' | 'en';
-    sign_rule?: 'explicit' | 'keyword';
-  };
-  skip_patterns?: string[];
-  zones?: IRcbTemplateZone[];
-}
-
-export interface IRcbTemplateVersion {
-  id: string;
-  templateId: string;
-  version: number;
-  templateJson: Record<string, unknown>;
-  comment: string | null;
-  createdAt: string;
-}
-
-export interface IRcbFeedback {
-  id: string;
-  extractionId: string;
-  userId: string;
-  issueType: RcbFeedbackIssueType;
-  description: string | null;
-  status: RcbFeedbackStatus;
-  createdAt: string;
-}
-
-export interface IRcbWebhookDelivery {
-  id: string;
-  userId: string | null;
-  organizationId: string | null;
-  projectId: string | null;
-  createdByUserId: string | null;
-  webhookId: string | null;
-  jobId: string | null;
-  event: string;
-  url: string;
-  payloadJson: Record<string, unknown>;
-  attempts: number;
-  lastStatus: number | null;
-  lastError: string | null;
-  deliveredAt: string | null;
-  createdAt: string;
-  updatedAt: string;
-}
-
-// Webhook event identifier. Values mirror AbyssApplicationEvent's RCB_*
-// entries so a logger.log(applicationEvent: ...) and a webhook delivery
-// can never drift.
-export enum RcbWebhookEvent {
-  EXTRACT_COMPLETED = 'rcb.extract.completed',
-  EXTRACT_FAILED = 'rcb.extract.failed',
-  EXTRACT_LOW_CONFIDENCE = 'rcb.extract.low-confidence',
-  EXTRACT_BALANCE_KO = 'rcb.extract.balance-ko',
-  FILE_ARCHIVED = 'rcb.file.archived',
-  SHARE_MINTED = 'rcb.share.minted',
-  SHARE_REVOKED = 'rcb.share.revoked',
-  FEEDBACK_SUBMITTED = 'rcb.feedback.submitted',
-  JOB_FAILED = 'rcb.job.failed',
-  EXPORT_COMPLETED = 'rcb.export.completed',
-  EXPORT_FAILED = 'rcb.export.failed',
-}
-
-export const RCB_WEBHOOK_EVENTS: RcbWebhookEvent[] =
-  Object.values(RcbWebhookEvent);
-
-export interface IRcbWebhook {
-  id: string;
-  userId: string | null;
-  organizationId: string | null;
-  projectId: string | null;
-  createdByUserId: string | null;
-  webhookUrl: string;
-  webhookSecret: string;
-  isEnabled: boolean;
-  name: string;
-  description: string;
-  scopes: RcbWebhookEvent[];
-  consecutiveFailures: number;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface IRcbQuota {
-  userId: string;
-  tier: string;
-  monthlyExtractCap: number | null;
-  monthlyExtractedCap: number | null;
-  monthlyBytesCap: number | null;
-  queueOnlyAboveCount: number | null;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface IRcbBankVersion {
-  id: string;
-  bank: string;
-  version: string;
-  validFrom: string | null;
-  validTo: string | null;
-  detectorJson: Record<string, unknown>;
-  parserKind: string;
-  configJson: Record<string, unknown>;
-  isActive: boolean;
-  createdAt: string;
-  updatedAt: string;
-}
+// ──────────────────────────────────────────────
+// Extraction DTOs.
+// Mirror server-side Sequelize models, dates serialized as ISO strings.
+// ──────────────────────────────────────────────
+
+import { ExtractionWarningCode } from '../../../types/enum/extraction-warning.enum';
+import { ExtractionFeedbackIssueType } from '../../../types/enum/extraction-feedback-issue-type.enum';
+import type {
+  IFieldValue,
+  IExecutionManifest,
+  IGlobalConfidence,
+} from './extraction-plan.dto';
+
+// Re-export so consumers can import ExtractionFeedbackIssueType from the DTO barrel.
+export { ExtractionFeedbackIssueType };
+
+export type ExtractionMode = 'auto' | 'hint' | 'template';
+export type ProcessingMode = 'sync' | 'queue';
+export type ExtractionStatus = 'pending' | 'completed' | 'failed' | 'cached';
+
+export type ExtractionFeedbackStatus = 'open' | 'triaged' | 'fixed' | 'closed';
+
+export type ExtractionUsageEventType =
+  | 'extract.sync.success'
+  | 'extract.sync.cached'
+  | 'extract.sync.failed'
+  | 'extract.queue.enqueued'
+  | 'extract.queue.success'
+  | 'extract.queue.cached'
+  | 'extract.queue.failed'
+  | 'template.run.success'
+  | 'template.run.failed';
+
+export interface IExtractionBankHint {
+  bank: string;
+  version?: string;
+}
+
+export interface IExtractionTransaction {
+  date?: string;
+  description?: string;
+  amount?: number;
+  balance?: number;
+  valueDate?: string;
+  bookingDate?: string;
+  reference?: string;
+  [k: string]: unknown;
+}
+
+export interface IExtractionMetadata {
+  iban?: string;
+  bic?: string;
+  bank?: string;
+  accountHolder?: string;
+  periodStart?: string;
+  periodEnd?: string;
+  openingBalance?: number;
+  closingBalance?: number;
+  currency?: string;
+  [k: string]: unknown;
+}
+
+export interface IExtractionFile {
+  id: string;
+  userId: string;
+  applicationId: string | null;
+  pdfHash: string;
+  pdfSizeBytes: number;
+  pdfMimeType: string;
+  pdfPageCount: number | null;
+  pdfFilename: string | null;
+  applicationFileId: string | null;
+  userExternalId: string | null;
+  userMetadata: Record<string, unknown> | null;
+  detectedBank: string | null;
+  detectedVersion: string | null;
+  detectedIban: string | null;
+  detectedBic: string | null;
+  detectedCurrency: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// Re-export ExtractionWarningCode so consumers can import it from the dto barrel.
+export { ExtractionWarningCode };
+
+export interface IExtractionWarning {
+  code: ExtractionWarningCode;
+  data?: {
+    /** Balance mismatch data (bank_statement). */
+    actualCents?: number;
+    expectedCents?: number;
+    currency?: string;
+    /**
+     * Adapter-specific validation error/warning type string, e.g.
+     * `ACTIF_PASSIF_MISMATCH`, `TOTAL_MISMATCH`, `MRZ_INVALID`.
+     * Present when `code === ExtractionWarningCode.ADAPTER_VALIDATION_ERROR`.
+     */
+    type?: string;
+    /** Human-readable explanation from the adapter's ValidationResult. */
+    message?: string;
+  };
+}
+
+export interface IExtraction {
+  id: string;
+  fileId: string;
+  mode: ExtractionMode;
+  hintBank: string | null;
+  hintVersion: string | null;
+  templateId: string | null;
+  templateVersion: number | null;
+  status: ExtractionStatus;
+  strategyUsed: string | null;
+  confidence: number | null;
+  recordsCount: number | null;
+  balanceValidated: boolean | null;
+  durationMs: number | null;
+  error: string | null;
+  recordsJson: IExtractionTransaction[] | null;
+  metadataJson: IExtractionMetadata | null;
+  warningsJson: IExtractionWarning[] | null;
+  tags: string[] | null;
+  note: string | null;
+  shareToken: string | null;
+  shareExpiresAt: string | null;
+  documentType: string | null;
+  documentTypeConfidence: number | null;
+  /**
+   * Persisted per-field results. Widened (V2-P1, ADDITIVE) to the IFieldValue
+   * superset: value + confidence stay at the SAME path (old readers unaffected),
+   * and the plan path additionally surfaces chosen / sources / signals /
+   * agreement provenance. Legacy template/hints rows persist only value +
+   * confidence (still a valid IFieldValue subset on the wire).
+   */
+  fieldsJson: Record<string, IFieldValue> | null;
+  improvementConsent: boolean;
+  usableForTraining: boolean;
+  supportTicketId: string | null;
+  /** AbyssExtract-owned training copy (extraction-training bucket). Purgeable. */
+  trainingFileId: string | null;
+  /** Whether the OCR layer was used for this extraction run. */
+  usedOcr: boolean;
+  /** Number of pages processed by the OCR layer. */
+  ocrPageCount: number;
+  /**
+   * Frozen execution manifest (resolved plan + per-pass impl/version) — the
+   * reproducible recipe. Present on plan-path rows; absent (null/undefined) on
+   * legacy template/hints rows. ADDITIVE, optional.
+   */
+  executionManifest?: IExecutionManifest | null;
+  /**
+   * Auditable global confidence (stats + aggregation + per-pass contributions).
+   * Surfaced where available; optional/absent otherwise. ADDITIVE, optional.
+   */
+  globalConfidence?: IGlobalConfidence | null;
+  createdAt: string;
+}
+
+export interface IExtractionTemplate {
+  id: string;
+  userId: string;
+  name: string;
+  description: string | null;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Spatial zone on a PDF page (PDF coords: origin bottom-left, points).
+ * Restricts regex matching to a specific rectangle.
+ */
+export interface IExtractionTemplateZone {
+  name: string;
+  page: number; // 1-indexed
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/**
+ * Typed shape of the template DSL JSON stored in `templateJson`. Mirrors
+ * `TemplateDSL` server-side. UI editors should narrow `templateJson` to this
+ * shape via `templateJson as IExtractionTemplateDsl`.
+ */
+export interface IExtractionTemplateDsl {
+  regex_iban?: string;
+  regex_bic?: string;
+  period?: { regex: string };
+  balance?: { opening_regex?: string; closing_regex?: string };
+  transactions?: {
+    row_pattern: string;
+    date_format?: string;
+    amount_locale?: 'fr' | 'en';
+    sign_rule?: 'explicit' | 'keyword';
+  };
+  skip_patterns?: string[];
+  zones?: IExtractionTemplateZone[];
+}
+
+export interface IExtractionTemplateVersion {
+  id: string;
+  templateId: string;
+  version: number;
+  templateJson: Record<string, unknown>;
+  comment: string | null;
+  createdAt: string;
+}
+
+export interface IExtractionFeedback {
+  id: string;
+  extractionId: string;
+  userId: string;
+  issueType: ExtractionFeedbackIssueType;
+  fieldKey: string | null;
+  expectedValue: string | null;
+  description: string | null;
+  supportTicketId: string | null;
+  status: ExtractionFeedbackStatus;
+  createdAt: string;
+}
+
+export interface IExtractionWebhookDelivery {
+  id: string;
+  userId: string | null;
+  organizationId: string | null;
+  projectId: string | null;
+  createdByUserId: string | null;
+  webhookId: string | null;
+  jobId: string | null;
+  event: string;
+  url: string;
+  payloadJson: Record<string, unknown>;
+  attempts: number;
+  lastStatus: number | null;
+  lastError: string | null;
+  deliveredAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// Webhook event identifier. Values mirror AbyssApplicationEvent's RCB_*
+// entries so a logger.log(applicationEvent: ...) and a webhook delivery
+// can never drift.
+export enum ExtractionWebhookEvent {
+  EXTRACT_COMPLETED = 'rcb.extract.completed',
+  EXTRACT_FAILED = 'rcb.extract.failed',
+  EXTRACT_LOW_CONFIDENCE = 'rcb.extract.low-confidence',
+  EXTRACT_BALANCE_KO = 'rcb.extract.balance-ko',
+  FILE_ARCHIVED = 'rcb.file.archived',
+  SHARE_MINTED = 'rcb.share.minted',
+  SHARE_REVOKED = 'rcb.share.revoked',
+  FEEDBACK_SUBMITTED = 'rcb.feedback.submitted',
+  JOB_FAILED = 'rcb.job.failed',
+  EXPORT_COMPLETED = 'rcb.export.completed',
+  EXPORT_FAILED = 'rcb.export.failed',
+}
+
+export const EXTRACTION_WEBHOOK_EVENTS: ExtractionWebhookEvent[] =
+  Object.values(ExtractionWebhookEvent);
+
+export interface IExtractionWebhook {
+  id: string;
+  userId: string | null;
+  organizationId: string | null;
+  projectId: string | null;
+  createdByUserId: string | null;
+  webhookUrl: string;
+  webhookSecret: string;
+  isEnabled: boolean;
+  name: string;
+  description: string;
+  scopes: ExtractionWebhookEvent[];
+  consecutiveFailures: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface IExtractionBankVersion {
+  id: string;
+  bank: string;
+  version: string;
+  validFrom: string | null;
+  validTo: string | null;
+  detectorJson: Record<string, unknown>;
+  parserKind: string;
+  configJson: Record<string, unknown>;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// ─── EXTRACTION SETTINGS (P4) ────────────────────────────────────────────────
+
+/**
+ * Scope discriminator for extraction settings.
+ * 'user' = personal scope; 'org' = organization scope.
+ */
+export enum ExtractionSettingsScopeKind {
+  USER = 'user',
+  ORG = 'org',
+}
+
+/** Per-scope improvement-consent settings row. */
+export interface IExtractionSettings {
+  id: string;
+  /** Set for personal scope. XOR with organizationId. */
+  userId: string | null;
+  /** Set for organization scope. XOR with userId. */
+  organizationId: string | null;
+  /** Factory default for per-extraction improvementConsent. OFF (false) by default. */
+  improvementDefault: boolean;
+  createdAt: string;
+  updatedAt: string;
+}

package/src/types/interface/models/index.ts

@@ -1,31 +1,34 @@
-export * from './user.dto';
-export * from './organization.dto';
-export * from './project.dto';
-export * from './atlas.dto';
-export * from './atlas-document.dto';
-export * from './atlas-group.dto';
-export * from './atlas-page.dto';
-export * from './atlas-page-content.dto';
-export * from './draw.dto';
-export * from './memo.dto';
-export * from './retrospective.dto';
-export * from './retrospective-section.dto';
-export * from './retrospective-card.dto';
-export * from './retrospective-member.dto';
-export * from './short-link.dto';
-export * from './short-link-click.dto';
-export * from './board.dto';
-export * from './board-activity.dto';
-export * from './board-card.dto';
-export * from './board-card-checklist.dto';
-export * from './board-card-checklist-row.dto';
-export * from './board-card-comment.dto';
-export * from './board-card-document.dto';
-export * from './board-card-label.dto';
-export * from './board-card-member.dto';
-export * from './board-column.dto';
-export * from './board-label.dto';
-export * from './team.dto';
-export * from './tag.dto';
-export * from './content-share.dto';
-export * from './rcb.dto';
+export * from './user.dto';
+export * from './organization.dto';
+export * from './project.dto';
+export * from './atlas.dto';
+export * from './atlas-document.dto';
+export * from './atlas-group.dto';
+export * from './atlas-page.dto';
+export * from './atlas-page-content.dto';
+export * from './draw.dto';
+export * from './memo.dto';
+export * from './retrospective.dto';
+export * from './retrospective-section.dto';
+export * from './retrospective-card.dto';
+export * from './retrospective-member.dto';
+export * from './short-link.dto';
+export * from './short-link-click.dto';
+export * from './beam.dto';
+export * from './board.dto';
+export * from './board-activity.dto';
+export * from './board-card.dto';
+export * from './board-card-checklist.dto';
+export * from './board-card-checklist-row.dto';
+export * from './board-card-comment.dto';
+export * from './board-card-document.dto';
+export * from './board-card-label.dto';
+export * from './board-card-member.dto';
+export * from './board-column.dto';
+export * from './board-label.dto';
+export * from './team.dto';
+export * from './tag.dto';
+export * from './content-share.dto';
+export * from './extraction.dto';
+export * from './extraction-plan.dto';
+export * from './extraction-spatial-template.dto';