@abyss-project/tools 1.0.5 → 1.1.1

package/src/types/interface/api/responses/extraction.response.ts

@@ -0,0 +1,454 @@
+// ──────────────────────────────────────────────
+// Extraction API responses.
+// ──────────────────────────────────────────────
+
+import { IResponse } from '../type-message/response';
+import type { IExtractionPlanPreset, IExtractModesData, IFieldValue } from '../../models/extraction-plan.dto';
+import {
+  IExtractionBankVersion,
+  IExtraction,
+  IExtractionMetadata,
+  IExtractionFeedback,
+  IExtractionFile,
+  IExtractionTemplate,
+  IExtractionTemplateVersion,
+  IExtractionTransaction,
+  IExtractionWebhookDelivery,
+  ExtractionMode,
+} from '../../models/extraction.dto';
+
+// ─── EXTRACT ─────────────────────────────────
+
+export interface IExtractSyncData {
+  extraction_id: string;
+  file_id: string;
+  application_file_id: string | null;
+  cached: boolean;
+  records: IExtractionTransaction[];
+  metadata: IExtractionMetadata;
+  extraction: {
+    mode: ExtractionMode;
+    strategy_used: string | null;
+    confidence: number | null;
+    detected_bank: string | null;
+    detected_version: string | null;
+    balance_validated: boolean | null;
+    duration_ms: number | null;
+    warnings: string[];
+    alternatives: unknown[];
+    /** Whether the OCR layer was used for this extraction run. */
+    used_ocr: boolean;
+    /** Number of pages processed by the OCR layer. */
+    ocr_page_count: number;
+  };
+  documentType: string | null;
+  documentTypeConfidence: number | null;
+  fields: Record<string, { value: unknown; confidence: number }> | null;
+}
+export type IExtractSyncResponse = IResponse<IExtractSyncData>;
+
+export interface IExtractQueueData {
+  job_id: string;
+  status: string;
+  queued_at: string;
+  poll_url: string;
+  documentType: string | null;
+  documentTypeConfidence: number | null;
+  fields: Record<string, { value: unknown; confidence: number }> | null;
+}
+export type IExtractQueueResponse = IResponse<IExtractQueueData>;
+
+export interface IExtractBulkData {
+  accepted: number;
+  rejected: number;
+  jobs: Array<{ index: number; job_id: string }>;
+  errors: Array<{ index: number; error: string }>;
+}
+export type IExtractBulkResponse = IResponse<IExtractBulkData>;
+
+// ─── DETECT ──────────────────────────────────
+
+export interface IDetectData {
+  pdfHash: string;
+  pageCount: number;
+  metadata: {
+    ibans: Array<{ iban: string; bankCode: string; countryCode: string }>;
+    bics: Array<{ bic: string; bankCode: string }>;
+  };
+  candidates: Array<{
+    id: string;
+    bankName: string;
+    version: string;
+    score: number;
+    matchedSignals: string[];
+  }>;
+  durationMs: number;
+}
+export type IDetectResponse = IResponse<IDetectData>;
+
+export interface IDetectBulkData {
+  count: number;
+  results: Array<{ index: number; result?: IDetectData; error?: string }>;
+}
+export type IDetectBulkResponse = IResponse<IDetectBulkData>;
+
+// ─── FILES / EXTRACTIONS ─────────────────────
+
+export interface IListFilesData {
+  data: IExtractionFile[];
+  total?: number;
+}
+export type IListFilesResponse = IListFilesData;
+
+export type IGetFileResponse = IResponse<IExtractionFile>;
+
+export interface IListFileExtractionsData {
+  data: IExtraction[];
+  total?: number;
+}
+export type IListFileExtractionsResponse = IListFileExtractionsData;
+
+export interface IGetExtractionData extends IExtraction {
+  documentType: string | null;
+  documentTypeConfidence: number | null;
+  /**
+   * `fieldsJson` exposed under the public name `fields`. Widened (V2-P1,
+   * ADDITIVE) to the IFieldValue superset — value + confidence stay at the same
+   * path; the plan path adds chosen / sources / signals / agreement provenance.
+   * `executionManifest` + `globalConfidence` are inherited (optional) from
+   * IExtraction.
+   */
+  fields: Record<string, IFieldValue> | null;
+}
+export type IGetExtractionResponse = IResponse<IGetExtractionData>;
+
+export interface ISearchExtractionRecordsResponse {
+  data: IExtractionTransaction[];
+  matched: number;
+  total: number;
+}
+
+export interface IDiffExtractionsData {
+  left: { id: string; mode: ExtractionMode; recordsCount: number | null };
+  right: { id: string; mode: ExtractionMode; recordsCount: number | null };
+  same: number;
+  added: IExtractionTransaction[];
+  removed: IExtractionTransaction[];
+  changed: Array<{ before: IExtractionTransaction; after: IExtractionTransaction; fields: string[] }>;
+  summary: { leftCount: number; rightCount: number; sumDeltaCents: number };
+}
+export type IDiffExtractionsResponse = IResponse<IDiffExtractionsData>;
+
+export interface IAsyncExportData {
+  job_id: string;
+  status: string;
+  poll_url: string;
+}
+export type IAsyncExportResponse = IResponse<IAsyncExportData>;
+
+export interface IGetExportJobData {
+  id: string;
+  status: string;
+  progress: number | object | string | boolean;
+  result: {
+    applicationFileId: string;
+    filename: string;
+    contentType: string;
+    byteSize: number;
+  } | null;
+  error: string | null;
+}
+export type IGetExportJobResponse = IResponse<IGetExportJobData>;
+
+// ─── TEMPLATES ───────────────────────────────
+
+export interface ITemplateAndVersionData {
+  template: IExtractionTemplate;
+  version: IExtractionTemplateVersion;
+  warnings?: string[];
+}
+export type ICreateTemplateResponse = IResponse<ITemplateAndVersionData>;
+export type IUpdateTemplateResponse = IResponse<ITemplateAndVersionData>;
+
+export type IListTemplatesResponse = IResponse<IExtractionTemplate[]>;
+
+export interface IGetTemplateData {
+  template: IExtractionTemplate;
+  latest_version: IExtractionTemplateVersion | null;
+}
+export type IGetTemplateResponse = IResponse<IGetTemplateData>;
+
+export type IListTemplateVersionsResponse = IResponse<IExtractionTemplateVersion[]>;
+
+// Deferred wire-schema rename — must match server SCHEMA constant in
+// extraction-template-portability.service.ts; rename together in the server/main batch.
+export interface IExtractionTemplateCollection {
+  $schema: 'abyss-rcb-template-collection/v1';
+  exported_at: string;
+  templates: Array<{
+    name: string;
+    description: string | null;
+    versions: Array<{
+      version: number;
+      comment: string | null;
+      template_json: Record<string, unknown>;
+    }>;
+  }>;
+}
+
+export interface IImportTemplateCollectionData {
+  imported: Array<{
+    originalName: string;
+    createdName: string;
+    templateId: string;
+    versions: number;
+  }>;
+  errors: Array<{ originalName: string; error: string }>;
+}
+export type IImportTemplateCollectionResponse = IResponse<IImportTemplateCollectionData>;
+
+// ─── JOBS ────────────────────────────────────
+
+export interface IExtractionJob {
+  id: string;
+  status:
+    | 'waiting'
+    | 'active'
+    | 'completed'
+    | 'failed'
+    | 'delayed'
+    | 'paused'
+    | 'pending'
+    | 'stuck';
+  progress: number | object | string | boolean;
+  result: {
+    extractionId: string;
+    fileId: string;
+    cached: boolean;
+    recordsCount: number;
+    strategyUsed: string | null;
+  } | null;
+  error: string | null;
+  createdAt: number;
+  processedOn: number | null;
+  finishedOn: number | null;
+  attemptsMade: number;
+}
+export type IGetJobResponse = IResponse<IExtractionJob>;
+
+// ─── FEEDBACK ────────────────────────────────
+
+export type ICreateFeedbackResponse = IResponse<IExtractionFeedback>;
+export interface IListFeedbackResponse {
+  data: IExtractionFeedback[];
+  total?: number;
+}
+export type IGetFeedbackResponse = IResponse<IExtractionFeedback>;
+
+// ─── HEALTH / STATS ─────────────────────────
+
+export interface IExtractionHealth {
+  status: 'ok' | 'degraded' | 'down';
+  redis: 'ok' | 'down';
+  queue: 'ok' | 'down';
+  worker: 'ok' | 'down';
+  isShuttingDown: boolean;
+  rssMb: number;
+  heapUsedMb: number;
+  uptimeSec: number;
+}
+export type IHealthResponse = IResponse<IExtractionHealth>;
+
+export interface IExtractionStats {
+  waiting: number;
+  active: number;
+  completed: number;
+  failed: number;
+  delayed: number;
+  workerConcurrency: number;
+  isPaused: boolean;
+}
+export type IStatsResponse = IResponse<IExtractionStats>;
+
+export interface IExtractionUsageSummary {
+  totalEvents: number;
+  successCount: number;
+  failedCount: number;
+  cachedCount: number;
+  totalDurationMs: number;
+  totalRecordsExtracted: number;
+  totalBytesProcessed: number;
+  byEventType: Record<string, number>;
+  byBank: Record<string, number>;
+}
+export type ISummaryUsageResponse = IResponse<IExtractionUsageSummary>;
+
+// ─── WEBHOOK DELIVERIES ─────────────────────
+
+export interface IListWebhookDeliveriesResponse {
+  data: IExtractionWebhookDelivery[];
+  total?: number;
+}
+export type IGetWebhookDeliveryResponse = IResponse<IExtractionWebhookDelivery>;
+
+// ─── SHARE (public) ──────────────────────────
+
+export interface IGetSharedExtractionData {
+  id: string;
+  mode: ExtractionMode;
+  strategy_used: string | null;
+  confidence: number | null;
+  records_count: number | null;
+  balance_validated: boolean | null;
+  records: IExtractionTransaction[];
+  metadata: IExtractionMetadata;
+  warnings: string[];
+  share_expires_at: string | null;
+  created_at: string;
+}
+export type IGetSharedExtractionResponse = IResponse<IGetSharedExtractionData>;
+
+export interface IMintShareExtractionData {
+  share_url: string;
+  share_token: string;
+  share_expires_at: string | null;
+}
+export type IMintShareExtractionResponse = IResponse<IMintShareExtractionData>;
+
+// ─── CHANGELOG ──────────────────────────────
+
+export interface IChangelogData {
+  current_version: string;
+  entries: Array<{ version: string; date: string; highlights: string[] }>;
+}
+export type IChangelogResponse = IResponse<IChangelogData>;
+
+// ─── ADMIN: CATALOGUE ────────────────────────
+
+export interface IListBankVersionsAdminResponse {
+  data: IExtractionBankVersion[];
+  total?: number;
+}
+export type IGetBankVersionAdminResponse = IResponse<IExtractionBankVersion>;
+export type IUpsertBankVersionAdminResponse = IResponse<IExtractionBankVersion>;
+
+export interface IReloadBankVersionsAdminData {
+  loaded: number;
+  skipped: number;
+  total: number;
+}
+export type IReloadBankVersionsAdminResponse = IResponse<IReloadBankVersionsAdminData>;
+
+export interface IDetectorReplayAdminData {
+  scanned: number;
+  kept: number;
+  flipped: number;
+  newDetections: number;
+  skipped: number;
+  details: unknown[];
+  durationMs: number;
+}
+export type IDetectorReplayAdminResponse = IResponse<IDetectorReplayAdminData>;
+
+export interface IListRequestLogAdminData {
+  data: Array<{
+    ts: number;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+    userId: string | null;
+    requestId: string | null;
+    rateLimitBucket: string | null;
+  }>;
+  meta: { capacity: number; used: number; oldestTs: number | null; newestTs: number | null };
+}
+
+// ─── METRICS ────────────────────────────────
+
+export interface IExtractionPerBankMetric {
+  bank: string;
+  extractions: number;
+  avgConfidence: number;
+  avgRecords: number;
+  balanceValidatedRate: number;
+  avgDurationMs: number;
+  feedbackOpen: number;
+}
+export type IPerBankMetricsAdminResponse = IResponse<IExtractionPerBankMetric[]>;
+
+export interface IExtractionLatencyBucket {
+  bucket: string;
+  count: number;
+}
+export type ILatencyMetricsAdminResponse = IResponse<IExtractionLatencyBucket[]>;
+
+export interface IExtractionOverviewMetrics {
+  last24h: { extractions: number; failures: number; avgLatencyMs: number };
+  last30d: { extractions: number; uniqueUsers: number };
+}
+export type IOverviewMetricsAdminResponse = IResponse<IExtractionOverviewMetrics>;
+
+// ─── WEBHOOK SUBSCRIPTIONS ──────────────────
+
+import type { IExtractionWebhook } from '../../models/extraction.dto';
+
+export interface IPaginateExtractionWebhookData {
+  rows: IExtractionWebhook[];
+  total: number;
+}
+export type IPaginateExtractionWebhookResponse = IResponse<IPaginateExtractionWebhookData>;
+export type IGetExtractionWebhookResponse = IResponse<{ webhook: IExtractionWebhook }>;
+export type ICreateExtractionWebhookResponse = IResponse<{ webhook: IExtractionWebhook }>;
+export type IUpdateExtractionWebhookResponse = IResponse<{ webhook: IExtractionWebhook }>;
+export type IDeleteExtractionWebhookResponse = IResponse<{ ok: true }>;
+export type IResetSecretExtractionWebhookResponse = IResponse<{ webhook: IExtractionWebhook }>;
+
+// ─── EXTRACTION SETTINGS (P4) ───────────────
+// The server returns only the effective flag, not the full settings row.
+
+/** Response shape for GET /extract/settings and PUT /extract/settings. */
+export interface IGetExtractionSettingsResponse {
+  data: { improvement_default: boolean };
+}
+
+/** Alias: PUT /extract/settings returns the same shape as GET. */
+export type IUpsertExtractionSettingsResponse = IGetExtractionSettingsResponse;
+
+// ─── TRAINING TOGGLE (P4-T8) ─────────────────
+
+/**
+ * Response shape for PATCH /extract/extractions/:id/training.
+ * Returns the updated extraction identifiers relevant to the training state.
+ */
+export interface IToggleExtractionTrainingResponse {
+  data: {
+    id: string;
+    usable_for_training: boolean;
+    training_file_id: string | null;
+  };
+}
+
+// ─── EXTRACTION MODES (V2-P1) ────────────────
+
+/** Response for GET /extract/modes — lists all registered providers + interpreters. */
+export interface IListModesResponse {
+  data: IExtractModesData;
+}
+
+// ─── EXTRACTION PLAN PRESETS (V2-P1) ─────────
+
+/** Response for GET /extract/plans — list all presets (system + scoped). */
+export interface IListPlanPresetsResponse {
+  data: IExtractionPlanPreset[];
+}
+
+/** Response for GET/POST/PUT /extract/plans/:id (and POST /extract/plans/:id/default). */
+export interface IGetPlanPresetResponse {
+  data: IExtractionPlanPreset;
+}
+
+/** Response for DELETE /extract/plans/:id. */
+export interface IDeletePlanPresetResponse {
+  data: { id: string };
+}

package/src/types/interface/api/responses/index.ts

@@ -1,32 +1,33 @@
-export * from './abyss.admin.response';
-export * from './atlas.response';
-export * from './atlas.public.response';
-export * from './atlas-document.response';
-export * from './atlas-group.response';
-export * from './atlas-page.response';
-export * from './board.response';
-export * from './board-card.response';
-export * from './board-card-checklist.response';
-export * from './board-card-comment.response';
-export * from './board-card-document.response';
-export * from './board-column.response';
-export * from './board-label.response';
-export * from './draw.response';
-export * from './draw.public.response';
-export * from './memo.response';
-export * from './retrospective.response';
-export * from './retrospective.public.response';
-export * from './retrospective-card.response';
-export * from './retrospective-member.response';
-export * from './retrospective-section.response';
-export * from './short-link.response';
-export * from './short-link.public.response';
-export * from './short-link.admin.response';
-export * from './metrics.response';
-export * from './tag.response';
-export * from './enriched-paginate.response';
-export * from './count.response';
-export * from './recent.response';
-export * from './transfer.response';
-export * from './rcb.response';
-export * from './monitor.response';
+export * from './abyss.admin.response';
+export * from './atlas.response';
+export * from './atlas.public.response';
+export * from './atlas-document.response';
+export * from './atlas-group.response';
+export * from './atlas-page.response';
+export * from './board.response';
+export * from './board-card.response';
+export * from './board-card-checklist.response';
+export * from './board-card-comment.response';
+export * from './board-card-document.response';
+export * from './board-column.response';
+export * from './board-label.response';
+export * from './draw.response';
+export * from './draw.public.response';
+export * from './memo.response';
+export * from './retrospective.response';
+export * from './retrospective.public.response';
+export * from './retrospective-card.response';
+export * from './retrospective-member.response';
+export * from './retrospective-section.response';
+export * from './short-link.response';
+export * from './short-link.public.response';
+export * from './short-link.admin.response';
+export * from './beam.response';
+export * from './metrics.response';
+export * from './tag.response';
+export * from './enriched-paginate.response';
+export * from './count.response';
+export * from './recent.response';
+export * from './transfer.response';
+export * from './extraction.response';
+export * from './monitor.response';

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

@@ -0,0 +1,67 @@
+import { IOrganization } from './organization.dto';
+import { IUser } from './user.dto';
+import { IProject } from './project.dto';
+import { BeamVisibility } from '../../enum/beam.enum';
+
+export interface IBeamTransfer {
+  id: string;
+  slug: string;
+  // sha256 of the anonymous management token; the plaintext is returned once at
+  // finalize (B5) and never stored.
+  manageTokenHash: string | null;
+  userId: string | null;
+  organizationId: string | null;
+  projectId: string | null;
+  createdByUserId: string | null;
+  visibility: BeamVisibility;
+  passwordHash: string | null;
+  title: string | null;
+  message: string | null;
+  isActive: boolean;
+  expiresAt: Date | null;
+  finalizedAt: Date | null;
+  maxDownloads: number | null;
+  downloadCount: number;
+  lastDownloadedAt: Date | null;
+  totalSizeOctet: number;
+  fileCount: number;
+  createdAt?: Date;
+  updatedAt?: Date;
+
+  user?: IUser | null;
+  project?: IProject | null;
+  organization?: IOrganization | null;
+  files?: IBeamFile[];
+  recipients?: IBeamRecipient[];
+}
+
+export interface IBeamFile {
+  id: string;
+  transferId: string;
+  // abyss-storage applicationFileId (PRIVATE bucket); resolved at serve time (B4).
+  storageFileId: string;
+  thumbnailStorageFileId: string | null;
+  name: string;
+  mimeType: string | null;
+  sizeOctet: number;
+  isImage: boolean;
+  width: number | null;
+  height: number | null;
+  downloadCount: number;
+  position: number;
+  createdAt?: Date;
+
+  transfer?: IBeamTransfer;
+}
+
+export interface IBeamRecipient {
+  id: string;
+  transferId: string;
+  email: string;
+  locale: string | null;
+  sentAt: Date | null;
+  firstOpenedAt: Date | null;
+  createdAt?: Date;
+
+  transfer?: IBeamTransfer;
+}