@abyss-project/probe 2.0.0 → 2.0.1

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

@@ -1,54 +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;
-}
+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

@@ -1,7 +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;
-}
+// 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

@@ -1,33 +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;
-}
+// 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

@@ -1,3 +1,3 @@
-export * from './probe-scan.response';
-export * from './probe-usage.response';
-export * from './probe-webhook.response';
+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

@@ -1,45 +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>>;
+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

@@ -1,25 +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>;
+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

@@ -1,24 +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>>;
+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

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

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

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

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

package/src/types/interface/index.ts

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

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

@@ -1,3 +1,3 @@
-export * from './probe-scan.dto';
-export * from './probe-webhook.dto';
-export * from './probe-webhook-delivery.dto';
+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

@@ -1,67 +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;
-}
+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;
+}