@abyss-project/probe 2.0.1 → 3.0.0

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-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-webhook.request.ts

@@ -1,33 +1,31 @@
-// 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-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. */
+  callbackUrl: string;
+}
+
+/**
+ * `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.
+ */
+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 /application/:applicationId/webhook/:webhookId/deliveries` query (WS5-6) — paginated. */
+export interface IListProbeWebhookDeliveriesQuery {
+  /** @default 1 */
+  page?: number;
+  /** @default 20 */
+  limit?: number;
+}

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-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/models/probe-webhook-delivery.dto.ts

@@ -1,73 +1,70 @@
-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`).
-//
-// `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
- * {@link verifyProbeWebhookSignature} (this package's root / utils).
- */
-export interface IProbeWebhookDeliveryPayload {
-  scanId: string;
-  /** Free-form caller reference, echoed back verbatim (see IProbeScanHistoryItem#context). */
-  context: Record<string, unknown> | null;
-  verdict: ProbeScanVerdict;
-  /** [] when clean. */
-  viruses: string[];
-  /**
-   * `ACCOUNT_AV_SCAN_UNITS` this scan consumed (WS5-1). Delivery only ever
-   * happens on a DONE scan, where the cost is always already computed and
-   * billed — see {@link IProbeScanHistoryItem#costUnits}.
-   */
-  costUnits: number | null;
-}
-
-// ─── Delivery HISTORY (WS5-6) ────────────────
-//
-// The interface above is the PAYLOAD a webhook receiver gets POSTed. This
-// section is a DIFFERENT concept: the persisted AUDIT ROW AbyssProbe keeps
-// of its OWN delivery attempts (one row per attempt — mirrors
-// apps/api/src/database/models/probe-webhook-delivery.model.ts EXACTLY,
-// itself modelled after this package's own extraction-webhook
-// delivery-history shape, trimmed to AbyssProbe's simpler
-// one-attempt-per-row reality — see that model's header comment). Read via
-// `GET /webhook/:webhookId/deliveries` (`sdk.probe.webhook.listDeliveries`).
-
-/**
- * One persisted delivery-attempt row, as returned (paginated) by
- * `GET /webhook/:webhookId/deliveries`.
- */
-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.
-   */
-  webhookId: string | null;
-  /** The scan whose verdict this delivery carried. */
-  scanId: string;
-  /** The exact URL this attempt POSTed to. */
-  url: string;
-  /** HTTP status code received. null when the request never got a response (network error / timeout / abort). */
-  statusCode: number | null;
-  /** true only for a 2xx response. */
-  success: boolean;
-  /** When this attempt was made. */
-  attemptedAt: Date;
-  /** Failure reason (HTTP non-2xx status, or the caught network/timeout error's message). null on success. */
-  error: string | null;
-  createdAt: Date;
-}
+import { ProbeScanVerdict } from '../../enum';
+
+// 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.
+
+/**
+ * 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 {
+  scanId: string;
+  /** Free-form caller reference, echoed back verbatim (see IProbeScanHistoryItem#context). */
+  context: Record<string, unknown> | null;
+  verdict: ProbeScanVerdict;
+  /** [] when clean. */
+  viruses: string[];
+  /**
+   * `ACCOUNT_AV_SCAN_UNITS` this scan consumed (WS5-1). Delivery only ever
+   * happens on a DONE scan, where the cost is always already computed and
+   * billed — see {@link IProbeScanHistoryItem#costUnits}.
+   */
+  costUnits: number | null;
+}
+
+// ─── Delivery HISTORY (WS5-6) ────────────────
+//
+// The interface above is the PAYLOAD a webhook receiver gets POSTed. This
+// section is a DIFFERENT concept: the persisted AUDIT ROW AbyssProbe keeps
+// of its OWN delivery attempts (one row per attempt — mirrors
+// apps/api/src/database/models/probe-webhook-delivery.model.ts EXACTLY,
+// itself modelled after this package's own extraction-webhook
+// delivery-history shape, trimmed to AbyssProbe's simpler
+// one-attempt-per-row reality — see that model's header comment). Read via
+// `GET /webhook/:webhookId/deliveries` (`sdk.probe.webhook.listDeliveries`).
+
+/**
+ * One persisted delivery-attempt row, as returned (paginated) by
+ * `GET /webhook/:webhookId/deliveries`.
+ */
+export interface IProbeWebhookDelivery {
+  id: string;
+  /**
+   * 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. */
+  scanId: string;
+  /** The exact URL this attempt POSTed to. */
+  url: string;
+  /** HTTP status code received. null when the request never got a response (network error / timeout / abort). */
+  statusCode: number | null;
+  /** true only for a 2xx response. */
+  success: boolean;
+  /** When this attempt was made. */
+  attemptedAt: Date;
+  /** Failure reason (HTTP non-2xx status, or the caught network/timeout error's message). null on success. */
+  error: string | null;
+  createdAt: Date;
+}