@abyss-project/probe 2.0.0 → 3.0.0

package/src/index.ts

@@ -1,8 +1,9 @@
 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 probeDeliverySubscriptionApi from './api/probe-delivery-subscription.api';
 import * as probeScanApplicationApi from './api/probe-scan.application.api';
+import * as probeDeliverySubscriptionApplicationApi from './api/probe-delivery-subscription.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';
@@ -26,7 +27,9 @@ 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').
+ * (re-exported from './utils'). INTERNAL (P5 #792): AbyssStorage's antivirus
+ * subscription is the only receiver until L2 — the deliveries of a client's
+ * subscription are signed by Flow.
  */
 export const PROBE_WEBHOOK_SIGNATURE_HEADER = 'x-probe-signature';
 export const PROBE_WEBHOOK_SIGNATURE_ALGORITHM = 'sha256';
@@ -61,14 +64,25 @@ type AbyssProbeCoreSDK = {
     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;
+    /**
+     * The subscriptions to the verdict of the caller's scans (`PROBE_SCAN_COMPLETED`), kept in
+     * Flow: personal scope, or an organization with `organizationId`. The deliveries are signed
+     * by Flow; the secret leaves with `create` and `resetSecret` only.
+     */
+    deliverySubscription: {
+      paginate: typeof probeDeliverySubscriptionApi.paginateProbeDeliverySubscription;
+      get: typeof probeDeliverySubscriptionApi.getProbeDeliverySubscription;
+      create: typeof probeDeliverySubscriptionApi.createProbeDeliverySubscription;
+      update: typeof probeDeliverySubscriptionApi.updateProbeDeliverySubscription;
+      delete: typeof probeDeliverySubscriptionApi.deleteProbeDeliverySubscription;
+      resetSecret: typeof probeDeliverySubscriptionApi.resetSecretProbeDeliverySubscription;
+      delivery: {
+        /** Deliveries of every subscription of the scope. */
+        paginateByScope: typeof probeDeliverySubscriptionApi.paginateProbeScopeDelivery;
+        paginate: typeof probeDeliverySubscriptionApi.paginateProbeDelivery;
+        get: typeof probeDeliverySubscriptionApi.getProbeDelivery;
+        replay: typeof probeDeliverySubscriptionApi.replayProbeDelivery;
+      };
     };
     /**
      * Application/API-key-auth counterpart (Phase 3a) — for inter-service
@@ -93,6 +107,22 @@ type AbyssProbeCoreSDK = {
       usage: {
         get: typeof probeUsageApplicationApi.getProbeUsageApplication;
       };
+      /** Same as `probe.deliverySubscription`, for the application (`FULL_ACCESS`). */
+      deliverySubscription: {
+        paginate: typeof probeDeliverySubscriptionApplicationApi.paginateProbeDeliverySubscriptionApplication;
+        get: typeof probeDeliverySubscriptionApplicationApi.getProbeDeliverySubscriptionApplication;
+        create: typeof probeDeliverySubscriptionApplicationApi.createProbeDeliverySubscriptionApplication;
+        update: typeof probeDeliverySubscriptionApplicationApi.updateProbeDeliverySubscriptionApplication;
+        delete: typeof probeDeliverySubscriptionApplicationApi.deleteProbeDeliverySubscriptionApplication;
+        resetSecret: typeof probeDeliverySubscriptionApplicationApi.resetSecretProbeDeliverySubscriptionApplication;
+        delivery: {
+          paginateByScope: typeof probeDeliverySubscriptionApplicationApi.paginateProbeScopeDeliveryApplication;
+          paginate: typeof probeDeliverySubscriptionApplicationApi.paginateProbeDeliveryApplication;
+          get: typeof probeDeliverySubscriptionApplicationApi.getProbeDeliveryApplication;
+          replay: typeof probeDeliverySubscriptionApplicationApi.replayProbeDeliveryApplication;
+        };
+      };
+      /** INTERNAL (P5 #792): AbyssStorage's antivirus subscription, until L2. */
       webhook: {
         create: typeof probeWebhookApplicationApi.createProbeWebhookApplication;
         list: typeof probeWebhookApplicationApi.listProbeWebhookApplication;
@@ -138,12 +168,19 @@ export class AbyssProbeCore {
         usage: {
           get: probeUsageApi.getProbeUsage,
         },
-        webhook: {
-          create: probeWebhookApi.createProbeWebhook,
-          list: probeWebhookApi.listProbeWebhook,
-          delete: probeWebhookApi.deleteProbeWebhook,
-          update: probeWebhookApi.updateProbeWebhook,
-          listDeliveries: probeWebhookApi.listProbeWebhookDeliveries,
+        deliverySubscription: {
+          paginate: probeDeliverySubscriptionApi.paginateProbeDeliverySubscription,
+          get: probeDeliverySubscriptionApi.getProbeDeliverySubscription,
+          create: probeDeliverySubscriptionApi.createProbeDeliverySubscription,
+          update: probeDeliverySubscriptionApi.updateProbeDeliverySubscription,
+          delete: probeDeliverySubscriptionApi.deleteProbeDeliverySubscription,
+          resetSecret: probeDeliverySubscriptionApi.resetSecretProbeDeliverySubscription,
+          delivery: {
+            paginateByScope: probeDeliverySubscriptionApi.paginateProbeScopeDelivery,
+            paginate: probeDeliverySubscriptionApi.paginateProbeDelivery,
+            get: probeDeliverySubscriptionApi.getProbeDelivery,
+            replay: probeDeliverySubscriptionApi.replayProbeDelivery,
+          },
         },
         application: {
           scan: probeScanApplicationApi.scanApplication,
@@ -154,6 +191,26 @@ export class AbyssProbeCore {
           usage: {
             get: probeUsageApplicationApi.getProbeUsageApplication,
           },
+          deliverySubscription: {
+            paginate:
+              probeDeliverySubscriptionApplicationApi.paginateProbeDeliverySubscriptionApplication,
+            get: probeDeliverySubscriptionApplicationApi.getProbeDeliverySubscriptionApplication,
+            create:
+              probeDeliverySubscriptionApplicationApi.createProbeDeliverySubscriptionApplication,
+            update:
+              probeDeliverySubscriptionApplicationApi.updateProbeDeliverySubscriptionApplication,
+            delete:
+              probeDeliverySubscriptionApplicationApi.deleteProbeDeliverySubscriptionApplication,
+            resetSecret:
+              probeDeliverySubscriptionApplicationApi.resetSecretProbeDeliverySubscriptionApplication,
+            delivery: {
+              paginateByScope:
+                probeDeliverySubscriptionApplicationApi.paginateProbeScopeDeliveryApplication,
+              paginate: probeDeliverySubscriptionApplicationApi.paginateProbeDeliveryApplication,
+              get: probeDeliverySubscriptionApplicationApi.getProbeDeliveryApplication,
+              replay: probeDeliverySubscriptionApplicationApi.replayProbeDeliveryApplication,
+            },
+          },
           webhook: {
             create: probeWebhookApplicationApi.createProbeWebhookApplication,
             list: probeWebhookApplicationApi.listProbeWebhookApplication,

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

@@ -30,4 +30,6 @@ export enum Code {
   drawImageLimitReached = 'draw_image_limit_reached',
   drawImageOwnerRequired = 'draw_image_owner_required',
   drawImageNotInDraw = 'draw_image_not_in_draw',
+  /** A scan `callbackUrl` in a scope with no enabled delivery subscription to sign it with (422). */
+  probeCallbackRequiresSubscription = 'probe_callback_requires_subscription',
 }

package/src/types/enum/index.ts

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

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

@@ -18,8 +18,9 @@ export enum ProbeScanVerdict {
 /**
  * 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`.
+ * verdict later through the scope's delivery subscriptions (Flow) and/or the
+ * per-request `callbackUrl` (delivered once through such a subscription), and/or by
+ * polling `GET /scan/:scanId`.
  */
 export enum ProbeScanMode {
   SYNC = 'sync',

package/src/types/index.ts

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

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

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

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

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

@@ -0,0 +1,42 @@
+import type { DeliveryStatus } from '@abyss-project/flow';
+
+// Mirrors apps/api/src/api/validators/probe-delivery-subscription.validator.ts. A client's
+// subscriptions to the verdict of its scans live in Flow; AbyssProbe checks who may manage them
+// and calls Flow for the scope (the caller, an organisation, or an application).
+
+/** Personal scope (default) or an organization, for the personal/org client. */
+export interface IProbeDeliverySubscriptionScopeQuery {
+  organizationId?: string;
+}
+
+export interface IPaginateProbeDeliverySubscriptionQuery
+  extends IProbeDeliverySubscriptionScopeQuery {
+  /** @default 1 */
+  page?: number;
+  /** @default 20 */
+  limit?: number;
+  isEnabled?: boolean;
+}
+
+export interface ICreateProbeDeliverySubscriptionBody {
+  /** Only `PROBE_SCAN_COMPLETED` (`DeliveryEventType.PROBE_SCAN_COMPLETED` of `@abyss-project/flow`). */
+  eventTypes: string[];
+  /** HTTPS endpoint the verdict is POSTed to. */
+  url: string;
+}
+
+/** At least one field is required. */
+export interface IUpdateProbeDeliverySubscriptionBody {
+  eventTypes?: string[];
+  url?: string;
+  isEnabled?: boolean;
+}
+
+/** Deliveries of one subscription, or of every subscription of the scope. */
+export interface IPaginateProbeDeliveryQuery extends IProbeDeliverySubscriptionScopeQuery {
+  /** @default 1 */
+  page?: number;
+  /** @default 20 */
+  limit?: number;
+  status?: DeliveryStatus;
+}

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,11 +1,9 @@
-// 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;
-}
+// Mirrors apps/api/src/api/controllers/probe-webhook-application.controller.ts's
+// CreateBody/UpdateBody and probe-webhook.validator.ts's Joi schemas.
+//
+// INTERNAL (P5 #792): the application webhooks serve AbyssStorage's antivirus subscription until
+// its client subscriptions move to Flow (L2). A client's own subscriptions are the Flow
+// delivery subscriptions (probe-delivery-subscription.request.ts).
 
 export interface ICreateProbeWebhookBody {
   /** HTTPS endpoint the verdict is POSTed to. Required, `https://` only. */
@@ -13,7 +11,7 @@ export interface ICreateProbeWebhookBody {
 }
 
 /**
- * `PATCH /webhook/:webhookId` body (WS5-5) — at least one field required
+ * `PATCH /application/:applicationId/webhook/:webhookId` body (WS5-5) — at least one field required
  * (mirrors probe-webhook.validator.ts#updateBody's `.min(1)`); omitted
  * fields are left unchanged.
  */
@@ -24,8 +22,8 @@ export interface IUpdateProbeWebhookBody {
   active?: boolean;
 }
 
-/** `GET /webhook/:webhookId/deliveries` query (WS5-6) — paginated. */
-export interface IListProbeWebhookDeliveriesQuery extends IProbeWebhookScopeQuery {
+/** `GET /application/:applicationId/webhook/:webhookId/deliveries` query (WS5-6) — paginated. */
+export interface IListProbeWebhookDeliveriesQuery {
   /** @default 1 */
   page?: number;
   /** @default 20 */

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

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

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

@@ -0,0 +1,27 @@
+import type {
+  ICreateDeliverySubscriptionResponse,
+  IDeleteDeliverySubscriptionResponse,
+  IGetDeliveryResponse,
+  IGetDeliverySubscriptionResponse,
+  IPaginateDeliveryResponse,
+  IPaginateDeliverySubscriptionResponse,
+  IReplayDeliveryResponse,
+  IResetSecretDeliverySubscriptionResponse,
+  IUpdateDeliverySubscriptionResponse,
+} from '@abyss-project/flow';
+
+// The answers are Flow's own, passed through: the subscription and delivery models of
+// `@abyss-project/flow`. The secret leaves only with a creation and a reset.
+
+export type IPaginateProbeDeliverySubscriptionResponse = IPaginateDeliverySubscriptionResponse;
+export type IGetProbeDeliverySubscriptionResponse = IGetDeliverySubscriptionResponse;
+/** `secret` is returned here once. */
+export type ICreateProbeDeliverySubscriptionResponse = ICreateDeliverySubscriptionResponse;
+export type IUpdateProbeDeliverySubscriptionResponse = IUpdateDeliverySubscriptionResponse;
+export type IDeleteProbeDeliverySubscriptionResponse = IDeleteDeliverySubscriptionResponse;
+/** The new `secret` is returned here once; the previous one stops signing. */
+export type IResetSecretProbeDeliverySubscriptionResponse =
+  IResetSecretDeliverySubscriptionResponse;
+export type IPaginateProbeDeliveryResponse = IPaginateDeliveryResponse;
+export type IGetProbeDeliveryResponse = IGetDeliveryResponse;
+export type IReplayProbeDeliveryResponse = IReplayDeliveryResponse;

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;
+}