@abyss-project/probe 1.0.0 → 2.0.0

package/src/index.ts

@@ -0,0 +1,205 @@
+import axios from 'axios';
+import axiosRetry, { IAxiosRetryConfig, isNetworkOrIdempotentRequestError } from 'axios-retry';
+import * as probeScanApi from './api/probe-scan.api';
+import * as probeWebhookApi from './api/probe-webhook.api';
+import * as probeScanApplicationApi from './api/probe-scan.application.api';
+import * as probeWebhookApplicationApi from './api/probe-webhook.application.api';
+import * as probeUsageApi from './api/probe-usage.api';
+import * as probeUsageApplicationApi from './api/probe-usage.application.api';
+
+export * from './api';
+export * from './types';
+export * from './utils';
+export * from './constants';
+
+const DEFAULT_BASE_URL = 'https://probe-api.abyss-project.fr/api/';
+
+export const API_KEY_HEADER = 'abyss-api-key';
+/**
+ * Application-level API key header (AbyssProbe application/API-key
+ * authentication). Same literal value every other Abyss service's own core
+ * package independently declares for its `ApplicationMiddleware`.
+ */
+export const API_KEY_APPLICATION_HEADER = 'abyss-api-key-application';
+export const ADMIN_TOKEN_HEADER = 'abyss-admin-token';
+
+/**
+ * Header carrying the HMAC-SHA256 signature of a probe webhook delivery's
+ * raw JSON body. Verify it with {@link verifyProbeWebhookSignature}
+ * (re-exported from './utils').
+ */
+export const PROBE_WEBHOOK_SIGNATURE_HEADER = 'x-probe-signature';
+export const PROBE_WEBHOOK_SIGNATURE_ALGORITHM = 'sha256';
+
+const NUMBER_RETRY_API = 10;
+const BASE_DELAY_BETWEEN_RETRY = 5000;
+const RETRY_CODES = [
+  502, // Bad Gateway
+  503, // Service Unavailable
+];
+
+type CoreConfig = {
+  token?: string;
+  apiKey?: string;
+  adminToken?: string;
+  baseURL?: string;
+};
+
+type AbyssProbeCoreSDK = {
+  probe: {
+    /** `POST /scan` — sync (default) or async depending on `options.mode`. */
+    scan: typeof probeScanApi.scan;
+    /** `POST /scan` forced to `mode: sync` — precisely-typed 200 response. */
+    scanSync: typeof probeScanApi.scanSync;
+    /** `POST /scan?mode=async` — precisely-typed 202 response. */
+    scanAsync: typeof probeScanApi.scanAsync;
+    /** `GET /scan/:scanId` — poll a scan's status/verdict. */
+    getScan: typeof probeScanApi.getScan;
+    /** `GET /scan` — paginated history/search. */
+    listScans: typeof probeScanApi.listScans;
+    /** `GET /usage` — current ACCOUNT_AV_SCAN_UNITS used/limit/remaining for the caller's scope. */
+    usage: {
+      get: typeof probeUsageApi.getProbeUsage;
+    };
+    webhook: {
+      create: typeof probeWebhookApi.createProbeWebhook;
+      list: typeof probeWebhookApi.listProbeWebhook;
+      delete: typeof probeWebhookApi.deleteProbeWebhook;
+      /** `PATCH /webhook/:webhookId` — edit callbackUrl and/or active. */
+      update: typeof probeWebhookApi.updateProbeWebhook;
+      /** `GET /webhook/:webhookId/deliveries` — paginated delivery-attempt history. */
+      listDeliveries: typeof probeWebhookApi.listProbeWebhookDeliveries;
+    };
+    /**
+     * Application/API-key-auth counterpart (Phase 3a) — for inter-service
+     * callers (abyss-storage, external integrations) instead of a
+     * personal/org session. Same request/response contracts as the methods
+     * above, hitting `/application/:applicationId/...` and authenticated
+     * with the `abyss-api-key-application` header ({@link
+     * API_KEY_APPLICATION_HEADER}) instead of the personal `abyss-api-key`.
+     */
+    application: {
+      /** `POST /application/:applicationId/scan` — sync (default) or async depending on `options.mode`. */
+      scan: typeof probeScanApplicationApi.scanApplication;
+      /** `POST /application/:applicationId/scan` forced to `mode: sync` — precisely-typed 200 response. */
+      scanSync: typeof probeScanApplicationApi.scanSyncApplication;
+      /** `POST /application/:applicationId/scan?mode=async` — precisely-typed 202 response. */
+      scanAsync: typeof probeScanApplicationApi.scanAsyncApplication;
+      /** `GET /application/:applicationId/scan/:scanId` — poll a scan's status/verdict. */
+      getScan: typeof probeScanApplicationApi.getScanApplication;
+      /** `GET /application/:applicationId/scan` — paginated history/search. */
+      listScans: typeof probeScanApplicationApi.listScansApplication;
+      /** `GET /application/:applicationId/usage` — current ACCOUNT_AV_SCAN_UNITS used/limit/remaining for the calling application. */
+      usage: {
+        get: typeof probeUsageApplicationApi.getProbeUsageApplication;
+      };
+      webhook: {
+        create: typeof probeWebhookApplicationApi.createProbeWebhookApplication;
+        list: typeof probeWebhookApplicationApi.listProbeWebhookApplication;
+        delete: typeof probeWebhookApplicationApi.deleteProbeWebhookApplication;
+        /** `PATCH /application/:applicationId/webhook/:webhookId` — edit callbackUrl and/or active. */
+        update: typeof probeWebhookApplicationApi.updateProbeWebhookApplication;
+        /** `GET /application/:applicationId/webhook/:webhookId/deliveries` — paginated delivery-attempt history. */
+        listDeliveries: typeof probeWebhookApplicationApi.listProbeWebhookDeliveriesApplication;
+      };
+    };
+  };
+};
+
+export class AbyssProbeCore {
+  private static config = {
+    token: '',
+    apiKey: '',
+    adminToken: '',
+    baseURL: DEFAULT_BASE_URL,
+  };
+  static axios = axios.create({
+    baseURL: this.config.baseURL,
+    withCredentials: true,
+  });
+
+  private static _sdk: AbyssProbeCoreSDK | null = null;
+
+  public static get sdk(): AbyssProbeCoreSDK {
+    if (!AbyssProbeCore._sdk) {
+      AbyssProbeCore._sdk = AbyssProbeCore.buildSDK();
+    }
+    return AbyssProbeCore._sdk;
+  }
+
+  private static buildSDK(): AbyssProbeCoreSDK {
+    return {
+      probe: {
+        scan: probeScanApi.scan,
+        scanSync: probeScanApi.scanSync,
+        scanAsync: probeScanApi.scanAsync,
+        getScan: probeScanApi.getScan,
+        listScans: probeScanApi.listScans,
+        usage: {
+          get: probeUsageApi.getProbeUsage,
+        },
+        webhook: {
+          create: probeWebhookApi.createProbeWebhook,
+          list: probeWebhookApi.listProbeWebhook,
+          delete: probeWebhookApi.deleteProbeWebhook,
+          update: probeWebhookApi.updateProbeWebhook,
+          listDeliveries: probeWebhookApi.listProbeWebhookDeliveries,
+        },
+        application: {
+          scan: probeScanApplicationApi.scanApplication,
+          scanSync: probeScanApplicationApi.scanSyncApplication,
+          scanAsync: probeScanApplicationApi.scanAsyncApplication,
+          getScan: probeScanApplicationApi.getScanApplication,
+          listScans: probeScanApplicationApi.listScansApplication,
+          usage: {
+            get: probeUsageApplicationApi.getProbeUsageApplication,
+          },
+          webhook: {
+            create: probeWebhookApplicationApi.createProbeWebhookApplication,
+            list: probeWebhookApplicationApi.listProbeWebhookApplication,
+            delete: probeWebhookApplicationApi.deleteProbeWebhookApplication,
+            update: probeWebhookApplicationApi.updateProbeWebhookApplication,
+            listDeliveries: probeWebhookApplicationApi.listProbeWebhookDeliveriesApplication,
+          },
+        },
+      },
+    };
+  }
+
+  public static enableAxiosRetry(axiosRetryConfig?: IAxiosRetryConfig): void {
+    axiosRetry(AbyssProbeCore.axios, {
+      retries: NUMBER_RETRY_API,
+      retryDelay: (retryCount) => retryCount * BASE_DELAY_BETWEEN_RETRY,
+      retryCondition: (error) =>
+        isNetworkOrIdempotentRequestError(error) ||
+        RETRY_CODES.includes(error.response?.status || 502),
+      ...axiosRetryConfig,
+    });
+  }
+
+  public static setConfig(config: CoreConfig): void {
+    AbyssProbeCore._sdk = null;
+
+    AbyssProbeCore.config = { ...AbyssProbeCore.config, ...config };
+
+    if (config.baseURL) {
+      AbyssProbeCore.axios.defaults.baseURL = config.baseURL;
+    }
+
+    if (config.token) {
+      AbyssProbeCore.axios.defaults.headers.common.Authorization = `Bearer ${config.token}`;
+    }
+
+    if (config.apiKey) {
+      AbyssProbeCore.axios.defaults.headers.common[API_KEY_HEADER] = `${config.apiKey}`;
+    }
+
+    if (config.adminToken) {
+      AbyssProbeCore.axios.defaults.headers.common[ADMIN_TOKEN_HEADER] = `${config.adminToken}`;
+    }
+  }
+
+  public static getConfig(): CoreConfig {
+    return AbyssProbeCore.config;
+  }
+}

package/src/types/enum/api-error.enum.ts

@@ -0,0 +1,33 @@
+export enum ErrorType {
+  apiError = 'api_error',
+  authError = 'authentication_error',
+  resourceError = 'resource_error',
+}
+
+export enum Code {
+  // HTTP Error
+  tokenFailure = 'token_authentication_failure',
+  authenticationFailure = 'authentication_credentials_failure',
+  accessNotAllowed = 'access_not_allowed',
+  notFound = 'not_found',
+  validationError = 'resource_validation_error',
+  constraintError = 'resource_constraint_error',
+  internalServerError = 'internal_server_error',
+  serviceUnavailable = 'service_unavailable',
+  invalidData = 'invalid_data',
+  notImplemented = 'not_implemented',
+  retrospectiveCannotBeModifiedWhenCompleted = 'retrospective_cannot_be_modified_when_completed',
+  retrospectiveActionNotAllowedInPhase = 'retrospective_action_not_allowed_in_phase',
+  retrospectiveVoteBudgetExhausted = 'retrospective_vote_budget_exhausted',
+  retrospectiveActionLimitReached = 'retrospective_action_limit_reached',
+  atlasDocumentLimitReached = 'atlas_document_limit_reached',
+  boardCardDocumentLimitReached = 'board_card_document_limit_reached',
+  boardCardMoveInvalidDestination = 'board_card_move_invalid_destination',
+  boardCardLinkLimitReached = 'board_card_link_limit_reached',
+  boardCardLinkAlreadyExists = 'board_card_link_already_exists',
+  boardCardLinkToSelf = 'board_card_link_to_self',
+  shortLinkProtected = 'short_link_protected',
+  drawImageLimitReached = 'draw_image_limit_reached',
+  drawImageOwnerRequired = 'draw_image_owner_required',
+  drawImageNotInDraw = 'draw_image_not_in_draw',
+}

package/src/types/enum/index.ts

@@ -0,0 +1,2 @@
+export * from './api-error.enum';
+export * from './probe-scan.enum';

package/src/types/enum/probe-scan.enum.ts

@@ -0,0 +1,44 @@
+// Mirrors apps/api/src/database/probe-scan.enum.ts EXACTLY (same string
+// values — this SDK talks to that API over the wire, so the values must
+// match byte-for-byte). Kept as a single file here too, on purpose: the
+// server groups all three enums in one file for the same reason (they are
+// one cohesive scan vocabulary), see that file's header comment.
+
+/**
+ * Antivirus scan verdict. `null` on the wire while the scan has not reached
+ * `DONE` yet (see {@link ProbeScanStatus}) — a scan that never completes
+ * (e.g. the engine throws) is left at its last real status with no
+ * fabricated verdict.
+ */
+export enum ProbeScanVerdict {
+  CLEAN = 'clean',
+  INFECTED = 'infected',
+}
+
+/**
+ * How the scan was (or will be) run: `SYNC` blocks the request until the
+ * engine returns the verdict inline; `ASYNC` queues the job and delivers the
+ * verdict later via a registered webhook and/or the per-request
+ * `callbackUrl`, and/or by polling `GET /scan/:scanId`.
+ */
+export enum ProbeScanMode {
+  SYNC = 'sync',
+  ASYNC = 'async',
+}
+
+/**
+ * Scan lifecycle. A SYNC scan skips `QUEUED` entirely (created directly at
+ * `SCANNING`). An ASYNC scan is created at `QUEUED`, flipped to `SCANNING`
+ * once a worker picks the job off the queue, then to `DONE` or `ERROR`.
+ *
+ * `ERROR` (async-only) is a TERMINAL, no-verdict state — there is no
+ * automatic requeue/retry (the uploaded bytes are deleted the moment the job
+ * ends, success or failure). A caller that wants to retry submits a brand
+ * new `POST /scan?mode=async`.
+ */
+export enum ProbeScanStatus {
+  QUEUED = 'queued',
+  SCANNING = 'scanning',
+  DONE = 'done',
+  ERROR = 'error',
+}

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './enum';
+export * from './interface';

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

@@ -0,0 +1,5 @@
+export * from './requests';
+export * from './responses';
+export * from './type-message/response';
+export * from './type-message/api-error';
+export * from './type-message/base-paginate';

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

@@ -0,0 +1,3 @@
+export * from './probe-scan.request';
+export * from './probe-usage.request';
+export * from './probe-webhook.request';

package/src/types/interface/api/requests/probe-scan.request.ts

@@ -0,0 +1,54 @@
+import { ProbeScanMode, ProbeScanStatus, ProbeScanVerdict } from '../../../enum';
+
+// Mirrors apps/api/src/api/controllers/probe-scan.controller.ts's ScanBody +
+// HistoryQuery, and apps/api/src/api/validators/probe-scan.validator.ts's
+// historyQuery() Joi schema (field names/optionality).
+
+/**
+ * Options accepted by `sdk.probe.scan(file, options)` — `POST /scan`. `mode`
+ * and `organizationId` travel as query params (`?mode=async&organization_id=`);
+ * `context` and `callbackUrl` travel as multipart text fields alongside the
+ * file — the sdk client handles that split, callers just pass one object.
+ */
+export interface IScanOptions {
+  /** sync (default — verdict returned inline) or async (queued, 202 + webhook/poll). */
+  mode?: ProbeScanMode;
+  /** Personal scope (default) or an organization the caller belongs to. */
+  organizationId?: string;
+  /** Free-form caller reference (e.g. `{ applicationFileId }`), stored verbatim. */
+  context?: Record<string, unknown>;
+  /** ASYNC-only per-request delivery override (https only). Ignored for a SYNC scan. */
+  callbackUrl?: string;
+  /** Filename reported to the server (defaults to `'file'`). Cosmetic only. */
+  filename?: string;
+  /**
+   * Content-Type stamped on the file part when the caller passes raw bytes
+   * (`Buffer`/`Uint8Array`). Ignored when the file is already a `Blob` — a
+   * browser `File` and `fs.openAsBlob(path)` carry their own type.
+   */
+  mimeType?: string;
+}
+
+/**
+ * `GET /scan` query — all filters optional, combined with AND.
+ * `contextKey`/`contextValue` must be supplied together (business-reference
+ * search inside the free-form `context` JSONB column) — supplying one
+ * without the other is rejected by the API (400).
+ */
+export interface IListScansQuery {
+  organizationId?: string;
+  verdict?: ProbeScanVerdict;
+  mode?: ProbeScanMode;
+  status?: ProbeScanStatus;
+  /** Date range on `createdAt`, inclusive at both ends. */
+  from?: Date;
+  to?: Date;
+  /** Case-insensitive partial match on the original file name. */
+  fileName?: string;
+  contextKey?: string;
+  contextValue?: string;
+  /** @default 1 */
+  page?: number;
+  /** @default 20, server max 200. */
+  limit?: number;
+}

package/src/types/interface/api/requests/probe-usage.request.ts

@@ -0,0 +1,7 @@
+// WS5-3 (AbyssProbe UX rework) — `GET /usage` / `GET /application/:applicationId/usage`.
+// Mirrors apps/api/src/api/validators/probe-usage.validator.ts's Joi schema.
+
+/** `GET /usage` query — personal scope (default) or an organization. Not needed for the application variant (its scope is the `:applicationId` URL segment). */
+export interface IProbeUsageScopeQuery {
+  organizationId?: string;
+}

package/src/types/interface/api/requests/probe-webhook.request.ts

@@ -0,0 +1,33 @@
+// Mirrors apps/api/src/api/controllers/probe-webhook.controller.ts's
+// ScopeQuery/CreateBody/UpdateBody and probe-webhook.validator.ts's Joi
+// schemas.
+
+/** Shared by create/list/delete/update — personal scope (default) or an organization. */
+export interface IProbeWebhookScopeQuery {
+  organizationId?: string;
+}
+
+export interface ICreateProbeWebhookBody {
+  /** HTTPS endpoint the verdict is POSTed to. Required, `https://` only. */
+  callbackUrl: string;
+}
+
+/**
+ * `PATCH /webhook/:webhookId` body (WS5-5) — at least one field required
+ * (mirrors probe-webhook.validator.ts#updateBody's `.min(1)`); omitted
+ * fields are left unchanged.
+ */
+export interface IUpdateProbeWebhookBody {
+  /** HTTPS endpoint the verdict is POSTed to, `https://` only. */
+  callbackUrl?: string;
+  /** Disabled webhooks are skipped by dispatch (soft-off, not deleted). */
+  active?: boolean;
+}
+
+/** `GET /webhook/:webhookId/deliveries` query (WS5-6) — paginated. */
+export interface IListProbeWebhookDeliveriesQuery extends IProbeWebhookScopeQuery {
+  /** @default 1 */
+  page?: number;
+  /** @default 20 */
+  limit?: number;
+}

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

@@ -0,0 +1,3 @@
+export * from './probe-scan.response';
+export * from './probe-usage.response';
+export * from './probe-webhook.response';

package/src/types/interface/api/responses/probe-scan.response.ts

@@ -0,0 +1,45 @@
+import { IResponse } from '../type-message/response';
+import { BasePaginate } from '../type-message/base-paginate';
+import { ProbeScanStatus, ProbeScanVerdict } from '../../../enum';
+import { IProbeScanDetail, IProbeScanHistoryItem } from '../../models';
+
+// Mirrors apps/api/src/api/controllers/probe-scan.controller.ts's local
+// ScanSyncResponseData / ScanAsyncResponseData / GetScanResponseData /
+// PaginateScanResponseData EXACTLY.
+
+/** `POST /scan` (default, or explicit `?mode=sync`) — HTTP 200. */
+export interface IScanSyncData {
+  scanId: string;
+  verdict: ProbeScanVerdict;
+  viruses: string[];
+  /**
+   * `ACCOUNT_AV_SCAN_UNITS` this scan consumed (WS5-1/2 — see
+   * `estimateProbeScanCost`). Always a number here (never null): a SYNC
+   * response is only ever sent once the scan has reached a verdict, at
+   * which point the cost is always known and already billed.
+   */
+  costUnits: number;
+}
+export type IScanSyncResponse = IResponse<IScanSyncData>;
+
+/** `POST /scan?mode=async` — HTTP 202, job queued. */
+export interface IScanAsyncData {
+  scanId: string;
+  status: ProbeScanStatus.QUEUED;
+}
+export type IScanAsyncResponse = IResponse<IScanAsyncData>;
+
+/**
+ * `POST /scan`'s actual response body is one or the other of the two data
+ * shapes above, discriminated by the request's own `mode` (sync -> 200 +
+ * {@link IScanSyncData}, async -> 202 + {@link IScanAsyncData}). A caller
+ * that only ever uses one mode should prefer the sdk's `scanSync`/`scanAsync`
+ * wrappers, which return the precise, non-union type.
+ */
+export type IScanResponse = IScanSyncResponse | IScanAsyncResponse;
+
+/** `GET /scan/:scanId` — HTTP 200. */
+export type IGetScanResponse = IResponse<IProbeScanDetail>;
+
+/** `GET /scan` — HTTP 200, paginated history/search. */
+export type IPaginateScanResponse = IResponse<BasePaginate<IProbeScanHistoryItem>>;

package/src/types/interface/api/responses/probe-usage.response.ts

@@ -0,0 +1,25 @@
+import { IResponse } from '../type-message/response';
+
+// WS5-3 (AbyssProbe UX rework) — mirrors
+// apps/api/src/api/controllers/probe-usage.controller.ts's local response
+// shape EXACTLY. Current ACCOUNT_AV_SCAN_UNITS ("tokens") consumption for the
+// caller's scope, via the same billing check the quota gate itself uses.
+
+export interface IProbeUsageData {
+  /** Units consumed so far in the current billing period. */
+  used: number;
+  /**
+   * Plan cap. `-1` is this codebase's established "unlimited" sentinel (see
+   * `utils/billing-emit.util.ts#UNLIMITED_EXPIRY_DAYS` server-side) — an
+   * unmetered plan tier reports `-1` here rather than `Infinity`/`null`, so
+   * treat a negative value as "no cap", never a literal negative quota.
+   */
+  limit: number;
+  /**
+   * `limit - used`, floored at 0 — except it mirrors `limit`'s own `-1`
+   * sentinel unchanged when `limit` is unlimited (never a finite number in
+   * that case).
+   */
+  remaining: number;
+}
+export type IProbeUsageResponse = IResponse<IProbeUsageData>;

package/src/types/interface/api/responses/probe-webhook.response.ts

@@ -0,0 +1,24 @@
+import { IResponse } from '../type-message/response';
+import { BasePaginate } from '../type-message/base-paginate';
+import { IProbeWebhook, IProbeWebhookDelivery } from '../../models';
+
+// Mirrors apps/api/src/api/controllers/probe-webhook.controller.ts's local
+// response shapes EXACTLY.
+
+/** `POST /webhook` — HTTP 201. `secret` is re-displayable (WS5-7) — also returned by GET/PATCH, not just here. */
+export type ICreateProbeWebhookResponse = IResponse<IProbeWebhook>;
+
+/** `GET /webhook` — HTTP 200. A flat scope-filtered list, NOT paginated. `secret` included per row (WS5-7). */
+export interface IListProbeWebhookData {
+  webhooks: IProbeWebhook[];
+}
+export type IListProbeWebhookResponse = IResponse<IListProbeWebhookData>;
+
+/** `DELETE /webhook/:webhookId` — HTTP 200. */
+export type IDeleteProbeWebhookResponse = IResponse<{ ok: true }>;
+
+/** `PATCH /webhook/:webhookId` — HTTP 200 (WS5-5). `secret` included, same as every other webhook read. */
+export type IUpdateProbeWebhookResponse = IResponse<IProbeWebhook>;
+
+/** `GET /webhook/:webhookId/deliveries` — HTTP 200, paginated (WS5-6). */
+export type IListProbeWebhookDeliveriesResponse = IResponse<BasePaginate<IProbeWebhookDelivery>>;

package/src/types/interface/api/type-message/api-error.ts

@@ -0,0 +1,7 @@
+import { Code, ErrorType } from '../../../enum';
+
+export interface IApiError {
+  code: Code;
+  type: ErrorType;
+  message?: string;
+}

package/src/types/interface/api/type-message/base-paginate.ts

@@ -0,0 +1,11 @@
+export interface BasePaginate<T> {
+  maxPages: number;
+  currentPage: number;
+  data: T[];
+  totalItems: number;
+}
+
+export interface QueryPaginate {
+  page?: number;
+  limit?: number;
+}

package/src/types/interface/api/type-message/response.ts

@@ -0,0 +1,6 @@
+import { IApiError } from './api-error';
+
+export interface IResponse<T> {
+  data: T;
+  error?: IApiError | Error;
+}

package/src/types/interface/index.ts

@@ -0,0 +1,2 @@
+export * from './models';
+export * from './api';

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

@@ -0,0 +1,3 @@
+export * from './probe-scan.dto';
+export * from './probe-webhook.dto';
+export * from './probe-webhook-delivery.dto';

package/src/types/interface/models/probe-scan.dto.ts

@@ -0,0 +1,67 @@
+import { ProbeScanMode, ProbeScanStatus, ProbeScanVerdict } from '../../enum';
+
+// Mirrors apps/api/src/api/controllers/probe-scan.controller.ts's local
+// response interfaces. AbyssProbe deliberately returns TWO different scan
+// shapes depending on the endpoint — never the raw `probe_scans` row, and
+// never a single one-size-fits-all model — so this file mirrors that with
+// two distinct interfaces rather than forcing one canonical "IProbeScan".
+
+/**
+ * `GET /scan/:scanId` shape (poll the queued -> scanning -> done/error
+ * progression). WS5-4 (AbyssProbe UX rework) widened this to full metadata
+ * parity with {@link IProbeScanHistoryItem} (fileName/fileSize/mimeType/
+ * mode/startedAt/finishedAt/costUnits) — the scanner UI's "Détails" section
+ * needs the same info whether it got there via the list or via a direct
+ * poll — still never echoing internal ownership columns (userId,
+ * organizationId, callbackUrl) — a caller polling by id already knows what
+ * it submitted.
+ */
+export interface IProbeScanDetail {
+  scanId: string;
+  status: ProbeScanStatus;
+  /** null until `status` is DONE. */
+  verdict: ProbeScanVerdict | null;
+  /** null until `status` is DONE; [] when DONE and clean. */
+  viruses: string[] | null;
+  /** Free-form caller reference echoed back verbatim (see IProbeScanHistoryItem#context). */
+  context: Record<string, unknown> | null;
+  fileName: string;
+  fileSize: number;
+  mimeType: string;
+  mode: ProbeScanMode;
+  /** Set the moment the engine call starts (SYNC: row-creation time; ASYNC: when a worker picks the job off the queue). */
+  startedAt: Date;
+  /** Set once the engine call returns. null while status is not DONE. */
+  finishedAt: Date | null;
+  /**
+   * `ACCOUNT_AV_SCAN_UNITS` this scan consumed (see `estimateProbeScanCost`
+   * — this package's own shared pure cost model). null until `status` is
+   * DONE; stays null forever for a scan that errors out (no verdict was ever
+   * reached, so nothing was ever billed).
+   */
+  costUnits: number | null;
+}
+
+/**
+ * One row of `GET /scan`'s paginated history/search list. Never echoes
+ * internal ownership columns (userId, organizationId, callbackUrl) — a
+ * caller already knows their own scope from the request they made.
+ */
+export interface IProbeScanHistoryItem {
+  scanId: string;
+  fileName: string;
+  fileSize: number;
+  mimeType: string;
+  verdict: ProbeScanVerdict | null;
+  viruses: string[] | null;
+  mode: ProbeScanMode;
+  status: ProbeScanStatus;
+  context: Record<string, unknown> | null;
+  /** Set the moment the engine call starts (SYNC: row-creation time; ASYNC: when a worker picks the job off the queue). */
+  startedAt: Date;
+  /** Set once the engine call returns. null while status is not DONE. */
+  finishedAt: Date | null;
+  /** See {@link IProbeScanDetail#costUnits}. */
+  costUnits: number | null;
+  createdAt: Date;
+}