@abyss-project/tools 1.0.3 → 1.1.1

package/src/types/interface/api/requests/extraction.request.ts

@@ -0,0 +1,366 @@
+// ──────────────────────────────────────────────
+// Extraction API requests.
+// ──────────────────────────────────────────────
+
+import {
+  ExtractionMode,
+  ExtractionFeedbackIssueType,
+  ExtractionFeedbackStatus,
+  ProcessingMode,
+  IExtractionBankHint,
+} from '../../models/extraction.dto';
+import type { IExtractionPlan } from '../../models/extraction-plan.dto';
+
+// ─── SCOPE ───────────────────────────────────
+//
+// Ownership-scope query params shared by the content/template routes. The
+// accepted combinations differ by resource, so the three semantic aliases
+// below share the same wire shape but document which endpoints accept which
+// scope. `project_id` always requires `organization_id`.
+
+/** Base wire shape for the ownership-scope query params. */
+export interface IExtractionScopeQuery {
+  organization_id?: string;
+  project_id?: string;
+}
+
+/**
+ * Scope for FILES + EXTRACTIONS. Owner is USER or PROJECT only — a bare
+ * `organization_id` is rejected (org-wide visibility goes through
+ * content_share / the shared-with-me endpoint), so pass `project_id` too.
+ */
+export type IExtractionContentScopeQuery = IExtractionScopeQuery;
+
+/**
+ * Scope for TEMPLATES. Owner is USER, PROJECT or ORGANIZATION — a bare
+ * `organization_id` authors an org-wide template reusable across every
+ * project of the org.
+ */
+export type IExtractionTemplateScopeQuery = IExtractionScopeQuery;
+
+// ─── EXTRACT ─────────────────────────────────
+
+export interface IExtractBody {
+  /** Inline PDF buffer — multipart upload only. SDK helpers wrap this. */
+  pdf?: Buffer | Uint8Array;
+  storage_file_id?: string;
+  mode: ExtractionMode;
+  hint?: IExtractionBankHint;
+  template_id?: string;
+  template?: Record<string, unknown>;
+  pdf_filename?: string;
+  user_external_id?: string;
+  user_metadata?: Record<string, unknown>;
+  archive?: boolean;
+  force?: boolean;
+  processing?: ProcessingMode;
+  /**
+   * Per-extraction override for the improvement-consent default.
+   * When omitted the scope's improvementDefault is used.
+   */
+  improvementConsent?: boolean;
+  /**
+   * Inline extraction plan override. When provided, takes precedence over
+   * plan_preset_id and the scope's default preset.
+   */
+  plan?: IExtractionPlan;
+  /**
+   * ID of a saved plan preset to use. Ignored when plan is also provided.
+   */
+  plan_preset_id?: string;
+}
+
+export interface IExtractBulkBody {
+  items: Array<{
+    storage_file_id?: string;
+    pdf_base64?: string;
+    mode: ExtractionMode;
+    hint?: IExtractionBankHint;
+    template_id?: string;
+    template?: Record<string, unknown>;
+    pdf_filename?: string;
+    user_external_id?: string;
+    user_metadata?: Record<string, unknown>;
+    archive?: boolean;
+    force?: boolean;
+  }>;
+}
+
+// ─── DETECT ──────────────────────────────────
+
+export interface IDetectBulkBody {
+  items: Array<{ pdf_base64: string; pdf_filename?: string }>;
+}
+
+// ─── FILES ───────────────────────────────────
+
+export interface IListFilesQuery extends IExtractionContentScopeQuery {
+  hash?: string;
+  external_id?: string;
+  application_file_id?: string;
+  bank?: string;
+  from?: string;
+  to?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface IGetFileParams {
+  fileId: string;
+}
+
+export interface IPatchFileBody {
+  user_external_id?: string | null;
+  user_metadata?: Record<string, unknown> | null;
+}
+
+// ─── EXTRACTIONS ─────────────────────────────
+
+export interface IGetExtractionParams {
+  extractionId: string;
+}
+
+export interface IPatchExtractionBody {
+  tags?: string[] | null;
+  note?: string | null;
+}
+
+export interface ISearchExtractionRecordsQuery {
+  q?: string;
+  amount_min?: number;
+  amount_max?: number;
+  sign?: 'debit' | 'credit';
+  date_from?: string;
+  date_to?: string;
+  sort?: 'date' | 'amount' | 'description';
+  sort_dir?: 'asc' | 'desc';
+  limit?: number;
+  offset?: number;
+}
+
+export interface IExportExtractionQuery {
+  format: 'csv' | 'json';
+  delimiter?: ',' | ';' | '\t';
+}
+
+export interface IAsyncExportExtractionBody {
+  format: 'csv' | 'json';
+  delimiter?: ',' | ';' | '\t';
+}
+
+// ─── TEMPLATES ───────────────────────────────
+
+export interface ICreateTemplateBody {
+  name: string;
+  description?: string;
+  template_json: Record<string, unknown>;
+  comment?: string;
+}
+
+export interface IUpdateTemplateBody {
+  template_json: Record<string, unknown>;
+  comment?: string;
+}
+
+export interface IPatchTemplateMetaBody {
+  name?: string;
+  description?: string | null;
+  is_active?: boolean;
+}
+
+// ─── FEEDBACK ────────────────────────────────
+
+/**
+ * Body for POST /extract/feedback.
+ *
+ * Wire fields are snake_case to match every other extract request body and the
+ * server controller (`extraction-extract.controller.ts#submitFeedback`).
+ * `field_key` localizes the issue to a single extracted field; `expected_value`
+ * carries the value the user expected — both feed the structured training signal.
+ * Every submission also mints a SupportTicket; the returned feedback DTO carries
+ * the resulting `supportTicketId` (see the feedback ↔ SupportTicket bridge ADR).
+ */
+export interface ISubmitFeedbackExtractionBody {
+  extraction_id: string;
+  issue_type: ExtractionFeedbackIssueType;
+  /** Extracted field the issue is about (e.g. `iban`, `closingBalance`). */
+  field_key?: string;
+  /** Value the user expected for the reported field. */
+  expected_value?: string;
+  description?: string;
+}
+
+export interface IPatchFeedbackBody {
+  status: ExtractionFeedbackStatus;
+}
+
+export interface IListFeedbackQuery {
+  extraction_id?: string;
+  status?: ExtractionFeedbackStatus;
+  issue_type?: ExtractionFeedbackIssueType;
+  limit?: number;
+  offset?: number;
+}
+
+// ─── USAGE ───────────────────────────────────
+
+export interface IListUsageQuery {
+  application_id?: string;
+  event_type?: string;
+  from?: string;
+  to?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface ISummaryUsageQuery {
+  from?: string;
+  to?: string;
+}
+
+// ─── WEBHOOK DELIVERIES ─────────────────────
+
+export interface IListWebhookDeliveriesQuery {
+  job_id?: string;
+  event?: string;
+  delivered?: boolean;
+  from?: string;
+  to?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface IReplayWebhookDeliveryBody {
+  url?: string;
+  secret?: string;
+}
+
+// ─── SHARE ───────────────────────────────────
+
+export interface IMintShareExtractionBody {
+  expires_in_days?: number;
+}
+
+// ─── ADMIN: CATALOGUE ────────────────────────
+
+export interface IUpsertBankVersionAdminBody {
+  bank: string;
+  version: string;
+  valid_from?: string | null;
+  valid_to?: string | null;
+  detector_json: Record<string, unknown>;
+  parser_kind: string;
+  config_json: Record<string, unknown>;
+  is_active?: boolean;
+}
+
+export interface IToggleBankVersionActiveAdminBody {
+  is_active: boolean;
+}
+
+export interface IDetectorReplayAdminBody {
+  detected_bank?: string;
+  from?: string;
+  to?: string;
+  limit?: number;
+}
+
+export interface IListRequestLogAdminQuery {
+  since_ms?: number;
+  status_min?: number;
+  status_max?: number;
+  user_id?: string;
+  path_prefix?: string;
+  limit?: number;
+}
+
+// ─── WEBHOOK SUBSCRIPTIONS ──────────────────
+
+import type { ExtractionWebhookEvent } from '../../models/extraction.dto';
+
+export interface IExtractionWebhookScopeQuery {
+  organization_id?: string;
+  project_id?: string;
+}
+
+export interface IPaginateExtractionWebhookQuery extends IExtractionWebhookScopeQuery {
+  name?: string;
+  event?: ExtractionWebhookEvent;
+  isEnabled?: boolean;
+  page?: number;
+  limit?: number;
+}
+
+export interface ICreateExtractionWebhookBody {
+  webhookUrl: string;
+  name?: string;
+  description?: string;
+  isEnabled?: boolean;
+  scopes: ExtractionWebhookEvent[];
+}
+
+export interface IUpdateExtractionWebhookBody {
+  webhookUrl?: string;
+  name?: string;
+  description?: string;
+  isEnabled?: boolean;
+  scopes?: ExtractionWebhookEvent[];
+}
+
+// ─── SHARED FILES (content_share-backed) ────
+
+export interface IListSharedFilesQuery extends IExtractionWebhookScopeQuery {
+  limit?: number;
+  offset?: number;
+}
+
+// ─── EXTRACTION SETTINGS (P4 / T7) ──────────
+//
+// GET /extract/settings  — scope is resolved by the server from standard
+//   ?organization_id / ?project_id query params (same as other extract routes).
+// PUT /extract/settings  — body is { improvement_default: boolean }.
+
+/** Optional scope query params for GET /extract/settings. */
+export interface IGetExtractionSettingsQuery {
+  /** Organization scope — omit for personal (user) scope. */
+  organization_id?: string;
+  /** Project scope — takes precedence over organization_id when both are present. */
+  project_id?: string;
+}
+
+/** Body for PUT /extract/settings — upsert the improvement default for a scope. */
+export interface IUpsertExtractionSettingsBody {
+  /** Factory default for per-extraction improvementConsent. */
+  improvement_default: boolean;
+}
+
+// ─── TRAINING TOGGLE (P4-T8) ─────────────────
+
+/** Body for PATCH /extract/extractions/:id/training. */
+export interface IToggleExtractionTrainingBody {
+  /** Set to true to include the extraction in the training dataset; false to exclude. */
+  usable: boolean;
+}
+
+// ─── EXTRACTION PLAN PRESETS (V2-P1) ─────────
+
+/** Body for POST /extract/plans — create a new plan preset. */
+export interface ICreatePlanPresetBody {
+  name: string;
+  plan: IExtractionPlan;
+}
+
+/** Body for PUT /extract/plans/:id — update a plan preset. */
+export interface IUpdatePlanPresetBody {
+  name?: string;
+  plan?: IExtractionPlan;
+}
+
+/** Body for POST /extract/plans/:id/default — set as default (id is path param). */
+export interface ISetDefaultPlanPresetBody {}
+
+/** Query params for GET /extract/plans. */
+export interface IListPlanPresetQuery {
+  organization_id?: string;
+  project_id?: string;
+}

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

@@ -1,28 +1,29 @@
-export * from './abyss.admin.request';
-export * from './atlas.request';
-export * from './atlas.public.request';
-export * from './atlas-document.request';
-export * from './atlas-group.request';
-export * from './atlas-page.request';
-export * from './board.request';
-export * from './board-card.request';
-export * from './board-card-checklist.request';
-export * from './board-card-comment.request';
-export * from './board-card-document.request';
-export * from './board-column.request';
-export * from './board-label.request';
-export * from './draw.request';
-export * from './draw.public.request';
-export * from './memo.request';
-export * from './retrospective.request';
-export * from './retrospective.public.request';
-export * from './retrospective-card.request';
-export * from './retrospective-member.request';
-export * from './retrospective-section.request';
-export * from './short-link.request';
-export * from './short-link.public.request';
-export * from './short-link.admin.request';
-export * from './metrics.request';
-export * from './tag.request';
-export * from './transfer.request';
-export * from './rcb.request';
+export * from './abyss.admin.request';
+export * from './atlas.request';
+export * from './atlas.public.request';
+export * from './atlas-document.request';
+export * from './atlas-group.request';
+export * from './atlas-page.request';
+export * from './board.request';
+export * from './board-card.request';
+export * from './board-card-checklist.request';
+export * from './board-card-comment.request';
+export * from './board-card-document.request';
+export * from './board-column.request';
+export * from './board-label.request';
+export * from './draw.request';
+export * from './draw.public.request';
+export * from './memo.request';
+export * from './retrospective.request';
+export * from './retrospective.public.request';
+export * from './retrospective-card.request';
+export * from './retrospective-member.request';
+export * from './retrospective-section.request';
+export * from './short-link.request';
+export * from './short-link.public.request';
+export * from './short-link.admin.request';
+export * from './beam.request';
+export * from './metrics.request';
+export * from './tag.request';
+export * from './transfer.request';
+export * from './extraction.request';

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

@@ -0,0 +1,122 @@
+import { BasePaginate } from '../type-message/base-paginate';
+import { IResponse } from '../type-message/response';
+import { IBeamTransfer, IBeamFile, IBeamRecipient } from '../../models/beam.dto';
+import { IContentShare } from '../../models/content-share.dto';
+import { BeamVisibility, BeamServeDenyReasonCode } from '../../../enum/beam.enum';
+
+export interface IGetBeamData {
+  beamTransfer: IBeamTransfer;
+}
+export type IGetBeamResponse = IResponse<IGetBeamData>;
+
+export type IPaginateBeamResponse = IResponse<BasePaginate<IBeamTransfer>>;
+
+export interface ICreateBeamData {
+  beamTransfer: IBeamTransfer;
+}
+export type ICreateBeamResponse = IResponse<ICreateBeamData>;
+
+export interface IUpdateBeamData {
+  beamTransfer: IBeamTransfer;
+}
+export type IUpdateBeamResponse = IResponse<IUpdateBeamData>;
+
+export interface IDeleteBeamData {}
+export type IDeleteBeamResponse = IResponse<IDeleteBeamData>;
+
+export type IAddBeamFilesResponse = IResponse<{ files: IBeamFile[] }>;
+
+export interface IFinalizeBeamData {
+  slug: string;
+  viewUrl: string;
+  manageToken: string;
+  manageUrl: string;
+  expiresAt: string;
+}
+
+export type IFinalizeBeamResponse = IResponse<IFinalizeBeamData>;
+
+// Public serving (B3) — safe, purpose-built projection of a transfer for the
+// browser-facing view: no owner ids, no password/manage hashes; adds
+// hasPassword/isLocked/hasThumbnail so the front can render the locked state.
+export interface IBeamPublicFile {
+  id: string;
+  name: string;
+  sizeOctet: number;
+  mimeType: string | null;
+  isImage: boolean;
+  hasThumbnail: boolean;
+  width: number | null;
+  height: number | null;
+}
+
+export interface IBeamPublicView {
+  slug: string;
+  title: string | null;
+  message: string | null;
+  visibility: BeamVisibility;
+  hasPassword: boolean;
+  isLocked: boolean;
+  expiresAt: string | null;
+  fileCount: number;
+  totalSizeOctet: number;
+  downloadCount: number;
+  files: IBeamPublicFile[];
+}
+
+// `transfer` is null on the discovery-path denials the VIEW surfaces (404
+// not-found / hidden, 410 expired, 403 max-downloads): the metadata projection
+// is intentionally absent and `reason` carries the machine-readable denial code
+// so the front renders the correct state rather than inferring it from the bare
+// HTTP status (spec §17.1). On a 200 `transfer` is non-null (visible transfer,
+// possibly password-locked) and `reason` is omitted.
+export type IGetBeamPublicResponse = IResponse<{
+  transfer: IBeamPublicView | null;
+  reason?: BeamServeDenyReasonCode;
+}>;
+
+export interface IUnlockBeamPublicData {
+  unlockToken: string;
+  expiresIn: number;
+}
+
+export type IUnlockBeamPublicResponse = IResponse<IUnlockBeamPublicData>;
+
+// Management lifecycle (B4): renew/reactivate return the refreshed transfer.
+export interface IRenewBeamData {
+  beamTransfer: IBeamTransfer;
+}
+export type IRenewBeamResponse = IResponse<IRenewBeamData>;
+
+export interface IReactivateBeamData {
+  beamTransfer: IBeamTransfer;
+}
+export type IReactivateBeamResponse = IResponse<IReactivateBeamData>;
+
+// Sharing (B4): create returns the new grant, list returns every grant, revoke
+// returns an empty envelope (the delete cascade is server-side).
+export interface ICreateBeamShareData {
+  contentShare: IContentShare;
+}
+export type ICreateBeamShareResponse = IResponse<ICreateBeamShareData>;
+
+export interface IListBeamSharesData {
+  contentShares: IContentShare[];
+}
+export type IListBeamSharesResponse = IResponse<IListBeamSharesData>;
+
+export interface IRevokeBeamShareData {}
+export type IRevokeBeamShareResponse = IResponse<IRevokeBeamShareData>;
+
+// Recipients (B5): add returns how many were enqueued vs rate-limited by the
+// anti-abuse caps; list returns every recipient row of the transfer.
+export interface IAddRecipientsBeamData {
+  enqueued: number;
+  rateLimited: number;
+}
+export type IAddRecipientsBeamResponse = IResponse<IAddRecipientsBeamData>;
+
+export interface IListRecipientsBeamData {
+  recipients: IBeamRecipient[];
+}
+export type IListRecipientsBeamResponse = IResponse<IListRecipientsBeamData>;