@abyss-project/tools 2.1.0 → 2.3.0

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/beam.response.ts

@@ -3,7 +3,6 @@ import { IResponse } from '../type-message/response';
 import { IBeamTransfer, IBeamFile, IBeamRecipient } from '../../models/beam.dto';
 import { IContentShare } from '../../models/content-share.dto';
 import { BeamVisibility, BeamServeDenyReasonCode, BeamDownloadKind } from '../../../enum/beam.enum';
-import { FileScanStatus } from '../../../enum/file-scan-status.enum';
 
 export interface IGetBeamData {
   beamTransfer: IBeamTransfer;
@@ -41,16 +40,7 @@ export type IFinalizeBeamResponse = IResponse<IFinalizeBeamData>;
 // browser-facing view: no owner ids, no password/manage hashes; adds
 // hasPassword/isLocked/hasThumbnail so the front can render the locked state.
 export interface IBeamPublicFile {
-  // AV v3 P3 async-enforce — the listing endpoint (GET /b/:slug) is the ONE
-  // beam serve path that is not gated by beamServingService.gateFile (it is
-  // a metadata list, not a byte stream). Per the link-live-gate-per-file
-  // decision the share link itself always works, but a file whose own
-  // scanStatus is not (yet) CLEAN must not hand out a servable identifier:
-  // id is null and hasThumbnail is forced false so the front cannot build a
-  // download/thumb URL for a pending or quarantined file. A legacy NULL
-  // scanStatus (row written before this column existed) is treated as
-  // servable, matching gateFile.
-  id: string | null;
+  id: string;
   name: string;
   sizeOctet: number;
   mimeType: string | null;
@@ -58,10 +48,6 @@ export interface IBeamPublicFile {
   hasThumbnail: boolean;
   width: number | null;
   height: number | null;
-  // Exposed as-is (never redacted) regardless of servability, so the front
-  // can render an "analysing" placeholder for a withheld file instead of it
-  // just silently vanishing from the list.
-  scanStatus: FileScanStatus | null;
 }
 
 export interface IBeamPublicView {

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

@@ -31,3 +31,6 @@ export * from './recent.response';
 export * from './transfer.response';
 export * from './extraction.response';
 export * from './monitor.response';
+export * from './probe-scan.response';
+export * from './probe-webhook.response';
+export * from './probe-usage.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, IProbeWebhookCreated, 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<IProbeWebhookCreated>;
+
+/** `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/models/atlas-document.dto.ts

@@ -1,19 +1,11 @@
 import { IAtlasPage } from './atlas-page.dto';
 import { IAtlas } from './atlas.dto';
-import { FileScanStatus } from '../../enum/file-scan-status.enum';
 
 export interface IAtlasDocument {
   id: string;
   atlasPageId: string;
   atlasId: string;
   name: string;
-  // AV v3 P2 async-enforce — WIRE CAVEAT: these 4 fields type as always-present
-  // here (the true, always-populated stored/model shape), but the HTTP JSON
-  // response actually redacts all four to `null` while scanStatus is
-  // 'pending_scan' (see the AtlasDocument model's toJSON() override) —
-  // pending_scan grants no servable identifier to any caller, owner included.
-  // A future front consumer of this DTO must treat them as possibly-null at
-  // runtime whenever scanStatus === 'pending_scan', despite the `string` type.
   externalId: string;
   publicAccessId: string;
   thumbnailId: string | null;
@@ -21,16 +13,6 @@ export interface IAtlasDocument {
   sizeOctet: number;
   mimeType: string;
   checksum: string;
-  // AV v3 P2 async-enforce: antivirus verdict mirrored from AbyssStorage,
-  // seeded pending_scan at the UPLOAD webhook, updated by applyScanResult /
-  // purgeInfected on the SCAN_RESULT webhook. Null for rows created before
-  // this column existed. See assertNotPendingScan for the 423 gate.
-  scanStatus: FileScanStatus | null;
-  // Id of the user who requested this upload (currentUser at presign time),
-  // resolved server-side — never client-supplied. Null for an API-key/
-  // anonymous upload. Used ONLY to notify the uploader if the file is later
-  // found infected (purgeInfected) — not a permission/ownership field.
-  uploadedByUserId: string | null;
   createdAt?: Date;
   updatedAt?: Date;
 

package/src/types/interface/models/beam.dto.ts

@@ -2,7 +2,6 @@ import { IOrganization } from './organization.dto';
 import { IUser } from './user.dto';
 import { IProject } from './project.dto';
 import { BeamVisibility, BeamDownloadKind } from '../../enum/beam.enum';
-import { FileScanStatus } from '../../enum/file-scan-status.enum';
 
 export interface IBeamTransfer {
   id: string;
@@ -39,13 +38,6 @@ export interface IBeamTransfer {
 export interface IBeamFile {
   id: string;
   transferId: string;
-  // AV v3 P3 async-enforce — WIRE CAVEAT: typed as always-present here (the
-  // true, always-populated stored/model shape), but the HTTP JSON response
-  // actually redacts this (and thumbnailStorageFileId) to null while
-  // scanStatus is 'pending_scan' (see the BeamFile model's get() override) —
-  // pending_scan grants no servable identifier to any caller. A future front
-  // consumer of this DTO must treat it as possibly-null at runtime whenever
-  // scanStatus === 'pending_scan', despite the `string` type.
   // abyss-storage applicationFileId (PRIVATE bucket); resolved at serve time (B4).
   storageFileId: string;
   thumbnailStorageFileId: string | null;
@@ -59,20 +51,6 @@ export interface IBeamFile {
   position: number;
   createdAt?: Date;
 
-  // AV v3 P3 async-enforce: antivirus verdict mirrored from AbyssStorage,
-  // seeded at attach time (beamUploadService#attachFiles — REQUIRES
-  // pending_scan, a server-side backstop against a client presign that
-  // omitted antivirus enrollment; see resumable-upload.ts) and updated by
-  // applyScanResult / purgeInfected on the SCAN_RESULT webhook. Null for
-  // rows created before this column existed. See
-  // beamServingService#gateFile for the per-file serve gate.
-  scanStatus: FileScanStatus | null;
-  // Id of the user who requested this attach (currentUser at attach time,
-  // resolved server-side — never client-supplied). Null for an anonymous
-  // transfer's attach. Used ONLY to notify the uploader if the file is later
-  // found infected (purgeInfected) — not a permission/ownership field.
-  uploadedByUserId: string | null;
-
   transfer?: IBeamTransfer;
 }
 

package/src/types/interface/models/board-card-document.dto.ts

@@ -1,19 +1,11 @@
 import { IBoardCard } from './board-card.dto';
 import { IBoard } from './board.dto';
-import { FileScanStatus } from '../../enum/file-scan-status.enum';
 
 export interface IBoardCardDocument {
   id: string;
   boardCardId: string;
   boardId: string;
   name: string;
-  // AV v3 P2 async-enforce — WIRE CAVEAT: these 4 fields type as always-present
-  // here (the true, always-populated stored/model shape), but the HTTP JSON
-  // response actually redacts all four to `null` while scanStatus is
-  // 'pending_scan' (see the BoardCardDocument model's toJSON() override) —
-  // pending_scan grants no servable identifier to any caller, owner included.
-  // A future front consumer of this DTO must treat them as possibly-null at
-  // runtime whenever scanStatus === 'pending_scan', despite the `string` type.
   externalId: string;
   publicAccessId: string;
   thumbnailId: string | null;
@@ -21,16 +13,6 @@ export interface IBoardCardDocument {
   checksum: string;
   mimeType: string;
   sizeOctet: number;
-  // AV v3 P2 async-enforce: antivirus verdict mirrored from AbyssStorage,
-  // seeded pending_scan at the UPLOAD webhook, updated by applyScanResult /
-  // purgeInfected on the SCAN_RESULT webhook. Null for rows created before
-  // this column existed. See assertNotPendingScan for the 423 gate.
-  scanStatus: FileScanStatus | null;
-  // Id of the user who requested this upload (currentUser at presign time),
-  // resolved server-side — never client-supplied. Null for an API-key/
-  // anonymous upload. Used ONLY to notify the uploader if the file is later
-  // found infected (purgeInfected) — not a permission/ownership field.
-  uploadedByUserId: string | null;
   updatedAt?: Date;
   createdAt?: Date;
 

package/src/types/interface/models/extraction.dto.ts

@@ -6,7 +6,6 @@
 import { ExtractionWarningCode } from '../../../types/enum/extraction-warning.enum';
 import { ExtractionFeedbackIssueType } from '../../../types/enum/extraction-feedback-issue-type.enum';
 import { DocumentType } from '../../../types/enum/document-type.enum';
-import { FileScanStatus } from '../../enum/file-scan-status.enum';
 import type { IFieldValue, IExecutionManifest, IGlobalConfidence } from './extraction-plan.dto';
 
 // Re-export so consumers can import ExtractionFeedbackIssueType from the DTO barrel.
@@ -67,13 +66,6 @@ export interface IExtractionFile {
   pdfMimeType: string;
   pdfPageCount: number | null;
   pdfFilename: string | null;
-  // AV v3 P3 async-enforce — WIRE CAVEAT: typed always-present here (the
-  // stored/model shape), but the HTTP JSON response redacts this to `null`
-  // while scanStatus is 'pending_scan' (see the ExtractionFile model's
-  // get() override) — pending_scan grants no servable identifier to any
-  // caller, owner included. Never gated for a by-reference (caller-owned)
-  // file: AbyssExtract never mirrors a scan verdict locally for those (see
-  // scanStatus below), gating on the caller's live verdict instead.
   applicationFileId: string | null;
   userExternalId: string | null;
   userMetadata: Record<string, unknown> | null;
@@ -82,15 +74,6 @@ export interface IExtractionFile {
   detectedIban: string | null;
   detectedBic: string | null;
   detectedCurrency: string | null;
-  // AV v3 P3 async-enforce: antivirus verdict mirrored from AbyssStorage for
-  // an ARCHIVE-OWNED file only (seeded at extractionFileService.upsert from
-  // the archive-upload response — see extraction-extract.service.ts#archivePdf).
-  // Null for by-reference files (gated live on the caller's own verdict
-  // instead — no local mirror, since AbyssExtract never receives a
-  // SCAN_RESULT webhook for a file it did not request the scan for) and for
-  // rows created before this column existed. See assertNotPendingScan for
-  // the 423 gate this enables on derived-output endpoints.
-  scanStatus: FileScanStatus | null;
   createdAt: string;
   updatedAt: string;
 }

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

@@ -32,3 +32,6 @@ export * from './content-share.dto';
 export * from './extraction.dto';
 export * from './extraction-plan.dto';
 export * from './extraction-spatial-template.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

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

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

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

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

@@ -0,0 +1,39 @@
+// Mirrors apps/api/src/api/controllers/probe-webhook.controller.ts's local
+// WebhookResponseData / CreateWebhookResponseData. 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;
+}
+
+/**
+ * @deprecated Structurally identical to {@link IProbeWebhook} now that
+ * `secret` is always re-displayable (WS5-7) — kept as a source-compatible
+ * alias (no removal, no consumer breakage) for existing imports that named
+ * this type explicitly for the old "only right after creation" contract.
+ * Prefer {@link IProbeWebhook} directly in new code.
+ */
+export type IProbeWebhookCreated = IProbeWebhook;

package/src/types/tests/beam.dto.spec.ts

@@ -46,8 +46,6 @@ describe('beam DTOs', () => {
       height: 600,
       downloadCount: 0,
       position: 0,
-      scanStatus: null,
-      uploadedByUserId: null,
     };
     const recipient: IBeamRecipient = {
       id: 'r1',