@abyss-project/probe 2.0.0 → 3.0.0

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

package/src/types/interface/models/probe-webhook-delivery.dto.ts

@@ -1,19 +1,19 @@
 import { ProbeScanVerdict } from '../../enum';
 
-// Mirrors apps/api/src/services/probe-webhook-delivery.service.ts's
-// ProbeWebhookPayload EXACTLY (same field set, same JSON.stringify'd body a
-// receiver's raw request body will deserialize into) — this is the payload
-// AbyssProbe POSTs to every registered webhook's `callbackUrl` (and to a
-// scan's own per-request `callbackUrl`, see probe-scan docs) once an ASYNC
-// scan reaches a verdict (`status: DONE`).
+// What AbyssProbe announces once a scan reaches a verdict (`status: DONE`): the `data` of the
+// `PROBE_SCAN_COMPLETED` event that Flow delivers to a client's delivery subscription (Flow's
+// envelope `{ deliveryId, eventType, source, occurredAt, data }`), and the JSON body of the
+// internal webhook AbyssStorage still receives until L2. Mirrors
+// apps/api/src/services/probe-webhook-delivery.service.ts's ProbeWebhookPayload EXACTLY.
 //
 // `verdict` is typed as the concrete enum here (not `string` like the
 // server's internal type) because delivery only ever happens on a DONE scan,
 // where the verdict is always set — see dispatchProbeScanWebhooks's guard.
 
 /**
- * Body of a webhook delivery, signed via HMAC-SHA256 of
- * `JSON.stringify(payload)` — see {@link PROBE_WEBHOOK_SIGNATURE_HEADER} and
+ * Payload of a finished scan. Flow signs the deliveries of a client's subscription (see
+ * `@abyss-project/flow`); the internal webhook is signed via HMAC-SHA256 of
+ * `JSON.stringify(payload)` — {@link PROBE_WEBHOOK_SIGNATURE_HEADER} and
  * {@link verifyProbeWebhookSignature} (this package's root / utils).
  */
 export interface IProbeWebhookDeliveryPayload {
@@ -49,12 +49,9 @@ export interface IProbeWebhookDeliveryPayload {
 export interface IProbeWebhookDelivery {
   id: string;
   /**
-   * The registered webhook this delivery targeted. null for a delivery to a
-   * scan's own ad-hoc per-request `callbackUrl` that matched no registered
-   * webhook (see the server model's own doc comment) — such a row is never
-   * reachable via this webhook-scoped endpoint in practice (there is no
-   * webhookId to query it under), but the field stays nullable to mirror the
-   * server column's real type.
+   * The registered webhook this delivery targeted. Always set today (a scan's
+   * `callbackUrl` is delivered by Flow, not by this history); the field stays
+   * nullable to mirror the server column's real type.
    */
   webhookId: string | null;
   /** The scan whose verdict this delivery carried. */

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

@@ -1,29 +1,29 @@
-// Mirrors apps/api/src/api/controllers/probe-webhook.controller.ts's local
-// WebhookResponseData. Public shape of a registered `probe_webhooks` row —
-// never echoes the internal ownership columns
-// (userId/organizationId/applicationId), same discipline as the scan models.
-//
-// WS5-7 (AbyssProbe UX rework): `secret` is ALWAYS re-displayable now —
-// returned on every read (GET /webhook list, and PATCH /webhook/:id), not
-// just once on create. Mirrors how AbyssExtract's own webhook model
-// (`IExtractionWebhookDelivery`'s sibling `ExtractionWebhook` — see
-// apps/api/src/database/models/extraction-webhook.model.ts /
-// extraction-webhook.controller.ts) has always exposed its
-// `webhookSecret` column on every response, never a once-only reveal. This
-// lets a consumer (e.g. abyss-storage's own webhook registration) read its
-// secret back at any time instead of relying on a log-once bootstrap.
-
-export interface IProbeWebhook {
-  id: string;
-  /** HTTPS endpoint the verdict is POSTed to. */
-  callbackUrl: string;
-  /**
-   * Server-generated HMAC-SHA256 signing secret. Re-displayable: returned on
-   * every read (list/create/update), not once-only — see this interface's
-   * own header note (WS5-7).
-   */
-  secret: string;
-  /** Disabled webhooks are skipped by dispatch (soft-off, not deleted). */
-  active: boolean;
-  createdAt: Date;
-}
+// Mirrors apps/api/src/api/controllers/probe-webhook.controller.ts's local
+// WebhookResponseData. Public shape of a registered `probe_webhooks` row —
+// never echoes the internal ownership columns
+// (userId/organizationId/applicationId), same discipline as the scan models.
+//
+// WS5-7 (AbyssProbe UX rework): `secret` is ALWAYS re-displayable now —
+// returned on every read (GET /webhook list, and PATCH /webhook/:id), not
+// just once on create. Mirrors how AbyssExtract's own webhook model
+// (`IExtractionWebhookDelivery`'s sibling `ExtractionWebhook` — see
+// apps/api/src/database/models/extraction-webhook.model.ts /
+// extraction-webhook.controller.ts) has always exposed its
+// `webhookSecret` column on every response, never a once-only reveal. This
+// lets a consumer (e.g. abyss-storage's own webhook registration) read its
+// secret back at any time instead of relying on a log-once bootstrap.
+
+export interface IProbeWebhook {
+  id: string;
+  /** HTTPS endpoint the verdict is POSTed to. */
+  callbackUrl: string;
+  /**
+   * Server-generated HMAC-SHA256 signing secret. Re-displayable: returned on
+   * every read (list/create/update), not once-only — see this interface's
+   * own header note (WS5-7).
+   */
+  secret: string;
+  /** Disabled webhooks are skipped by dispatch (soft-off, not deleted). */
+  active: boolean;
+  createdAt: Date;
+}

package/src/types/tests/probe.dto.test.ts

@@ -1,6 +1,6 @@
 // Type-level compile test for AbyssProbe's DTO/response shapes — asserts
 // they match the server contract (probe-scan.controller.ts /
-// probe-webhook.controller.ts / probe-usage.controller.ts /
+// probe-webhook-application.controller.ts / probe-usage.controller.ts /
 // probe-webhook-delivery.service.ts) at compile time: any incompatible
 // rename/removal on either side fails `npm run build` here. No jest runner
 // in this SDK package; compile guard only (mirrors
@@ -19,6 +19,13 @@ import {
   IScanAsyncData,
   IUpdateProbeWebhookBody,
   IProbeUsageData,
+  ICreateProbeDeliverySubscriptionBody,
+  IUpdateProbeDeliverySubscriptionBody,
+  IPaginateProbeDeliveryQuery,
+  IPaginateProbeDeliverySubscriptionQuery,
+  ICreateProbeDeliverySubscriptionResponse,
+  IGetProbeDeliverySubscriptionResponse,
+  Code,
 } from '..';
 // estimateProbeScanCost lives in src/utils/ (a SIBLING of src/types/, not
 // re-exported by the types barrel this file otherwise imports from) — see
@@ -92,7 +99,7 @@ const _webhook: IProbeWebhook = {
   createdAt: new Date(),
 };
 
-// PATCH /webhook/:webhookId body (WS5-5) — every field optional (at least one required server-side).
+// PATCH /application/:applicationId/webhook/:webhookId body (WS5-5) — every field optional (at least one required server-side).
 const _updateBody: IUpdateProbeWebhookBody = { active: false };
 const _updateBody2: IUpdateProbeWebhookBody = { callbackUrl: 'https://example.com/hook2' };
 
@@ -106,7 +113,7 @@ const _deliveryPayload: IProbeWebhookDeliveryPayload = {
   costUnits: 5,
 };
 
-// GET /webhook/:webhookId/deliveries row (WS5-6) — a persisted delivery-attempt.
+// GET /application/:applicationId/webhook/:webhookId/deliveries row (WS5-6) — a persisted delivery-attempt.
 const _deliveryRecord: IProbeWebhookDelivery = {
   id: 'd1',
   webhookId: 'w1',
@@ -118,9 +125,31 @@ const _deliveryRecord: IProbeWebhookDelivery = {
   error: null,
   createdAt: new Date(),
 };
-// webhookId is nullable (ad-hoc per-request callbackUrl with no matching registration).
+// webhookId stays nullable: it mirrors the column's real type.
 const _deliveryRecordAdHoc: IProbeWebhookDelivery = { ..._deliveryRecord, webhookId: null };
 
+// Delivery subscriptions (P5 #792) — the client's subscriptions live in Flow; the body names the
+// one event and the URL, the scope is the caller (or `organizationId`, or the application).
+const _createSubscription: ICreateProbeDeliverySubscriptionBody = {
+  eventTypes: ['PROBE_SCAN_COMPLETED'],
+  url: 'https://example.com/hook',
+};
+const _updateSubscription: IUpdateProbeDeliverySubscriptionBody = { isEnabled: false };
+const _subscriptionQuery: IPaginateProbeDeliverySubscriptionQuery = {
+  organizationId: 'o1',
+  isEnabled: true,
+  page: 1,
+  limit: 20,
+};
+const _deliveryQuery: IPaginateProbeDeliveryQuery = { organizationId: 'o1', page: 2 };
+// The secret is on the creation answer only.
+declare const created: ICreateProbeDeliverySubscriptionResponse;
+declare const read: IGetProbeDeliverySubscriptionResponse;
+const _secret: string = created.data.secret;
+// @ts-expect-error a read never carries the secret
+const _noSecret: string = read.data.secret;
+const _callbackCode: Code = Code.probeCallbackRequiresSubscription;
+
 // GET /usage data shape (WS5-3).
 const _usage: IProbeUsageData = { used: 10, limit: 1000, remaining: 990 };
 // -1 is the established "unlimited" sentinel (see estimateProbeScanCost's
@@ -145,6 +174,13 @@ void _historyItem;
 void _scanSyncData;
 void _scanAsyncData;
 void _webhook;
+void _createSubscription;
+void _updateSubscription;
+void _subscriptionQuery;
+void _deliveryQuery;
+void _secret;
+void _noSecret;
+void _callbackCode;
 void _updateBody;
 void _updateBody2;
 void _deliveryPayload;

package/src/utils/enum.utils.ts

@@ -1 +1 @@
-export type ValueOf<T> = T[keyof T];
+export type ValueOf<T> = T[keyof T];

package/src/utils/error.utils.ts

@@ -1,30 +1,30 @@
-import { Code, ErrorType } from '../types';
-
-type ErrorParams = { code: Code; type: ErrorType; message?: string };
-
-export class ServiceException extends Error {
-  private readonly code: Code;
-
-  private readonly type: ErrorType;
-
-  getCode(): Code {
-    return this.code;
-  }
-
-  getType(): ErrorType {
-    return this.type;
-  }
-
-  constructor(params: ErrorParams) {
-    super(params.message);
-    this.code = params.code;
-    this.type = params.type;
-  }
-}
-
-export const handleError = (error: Error | ErrorParams, _params?: ErrorParams): Error => {
-  if (error instanceof Error) {
-    return error;
-  }
-  return new ServiceException(error);
-};
+import { Code, ErrorType } from '../types';
+
+type ErrorParams = { code: Code; type: ErrorType; message?: string };
+
+export class ServiceException extends Error {
+  private readonly code: Code;
+
+  private readonly type: ErrorType;
+
+  getCode(): Code {
+    return this.code;
+  }
+
+  getType(): ErrorType {
+    return this.type;
+  }
+
+  constructor(params: ErrorParams) {
+    super(params.message);
+    this.code = params.code;
+    this.type = params.type;
+  }
+}
+
+export const handleError = (error: Error | ErrorParams, _params?: ErrorParams): Error => {
+  if (error instanceof Error) {
+    return error;
+  }
+  return new ServiceException(error);
+};

package/src/utils/index.ts

@@ -1,4 +1,4 @@
-export * from './error.utils';
-export * from './enum.utils';
-export * from './probe-webhook-signature.utils';
-export * from './probe-scan-cost.utils';
+export * from './error.utils';
+export * from './enum.utils';
+export * from './probe-webhook-signature.utils';
+export * from './probe-scan-cost.utils';