@abyss-project/tools 2.2.0 → 2.4.0

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

@@ -1,13 +1,14 @@
 import { IResponse } from '../type-message/response';
-import { IProbeWebhook, IProbeWebhookCreated } from '../../models';
+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. The only response that ever carries `secret`. */
+/** `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. */
+/** `GET /webhook` — HTTP 200. A flat scope-filtered list, NOT paginated. `secret` included per row (WS5-7). */
 export interface IListProbeWebhookData {
   webhooks: IProbeWebhook[];
 }
@@ -15,3 +16,9 @@ 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/probe-scan.dto.ts

@@ -8,9 +8,13 @@ import { ProbeScanMode, ProbeScanStatus, ProbeScanVerdict } from '../../enum';
 
 /**
  * `GET /scan/:scanId` shape (poll the queued -> scanning -> done/error
- * progression). Deliberately minimal: no fileName/fileSize/mimeType/mode/
- * timestamps, no internal ownership columns (userId/organizationId/
- * callbackUrl) — a caller polling by id already knows what it submitted.
+ * 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;
@@ -21,14 +25,27 @@ export interface IProbeScanDetail {
   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. Richer than
- * {@link IProbeScanDetail} (adds fileName/fileSize/mimeType/mode/timestamps)
- * but still never echoes internal ownership columns (userId, organizationId,
- * callbackUrl) — a caller already knows their own scope from the request
- * they made.
+ * 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;
@@ -44,5 +61,7 @@ export interface IProbeScanHistoryItem {
   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

@@ -23,4 +23,51 @@ export interface IProbeWebhookDeliveryPayload {
   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

@@ -1,25 +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 carries `secret` except right
-// after creation (see IProbeWebhookCreated below); never echoes the
-// internal ownership columns (userId/organizationId/applicationId) either,
-// same discipline as the scan models.
+// 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;
 }
 
 /**
- * Create-only response shape: the ONE time `secret` is ever returned by the
- * API ("Secret generated server-side, returned once on create"). Store it
- * immediately — there is no reset-secret / re-reveal endpoint (see this
- * package's header note on the deliberately small CRUD surface).
+ * @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 interface IProbeWebhookCreated extends IProbeWebhook {
-  secret: string;
-}
+export type IProbeWebhookCreated = IProbeWebhook;

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

@@ -1,9 +1,10 @@
 // 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-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 ../api/extraction-plan-preset.api.test.ts). Run: npx tsc --noEmit.
+// probe-webhook.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
+// ../api/extraction-plan-preset.api.test.ts). Run: npx tsc --noEmit.
 
 import {
   ProbeScanVerdict,
@@ -13,10 +14,18 @@ import {
   IProbeScanHistoryItem,
   IProbeWebhook,
   IProbeWebhookCreated,
+  IProbeWebhookDelivery,
   IProbeWebhookDeliveryPayload,
   IScanSyncData,
   IScanAsyncData,
+  IUpdateProbeWebhookBody,
+  IProbeUsageData,
 } from '..';
+// estimateProbeScanCost lives in src/utils/ (a SIBLING of src/types/, not
+// re-exported by the types barrel this file otherwise imports from) — see
+// probe-scan-cost.utils.ts's own header comment for why it is a plain
+// top-level export rather than a `sdk.probe.*` method.
+import { estimateProbeScanCost } from '../../utils';
 
 // Enum exhaustiveness: fails to compile if a member is added/removed/renamed
 // here without updating this file — a cheap drift guard for values
@@ -31,17 +40,24 @@ const _statuses: Record<ProbeScanStatus, true> = {
   error: true,
 };
 
-// GET /scan/:scanId
+// GET /scan/:scanId — WS5-4: full metadata parity with IProbeScanHistoryItem
+// (fileName/fileSize/mimeType/mode/startedAt/finishedAt/costUnits).
 const _scanDetail: IProbeScanDetail = {
   scanId: 's1',
   status: ProbeScanStatus.DONE,
   verdict: ProbeScanVerdict.CLEAN,
   viruses: [],
   context: null,
+  fileName: 'invoice.pdf',
+  fileSize: 1024,
+  mimeType: 'application/pdf',
+  mode: ProbeScanMode.SYNC,
+  startedAt: new Date(),
+  finishedAt: new Date(),
+  costUnits: 3,
 };
 
-// GET /scan history row — richer than IProbeScanDetail (fileName/fileSize/
-// mimeType/mode/timestamps), still never the internal ownership columns.
+// GET /scan history row — WS5-1: costUnits added.
 const _historyItem: IProbeScanHistoryItem = {
   scanId: 's1',
   fileName: 'invoice.pdf',
@@ -54,35 +70,75 @@ const _historyItem: IProbeScanHistoryItem = {
   context: { applicationFileId: 'af1' },
   startedAt: new Date(),
   finishedAt: new Date(),
+  costUnits: 1,
   createdAt: new Date(),
 };
 
-// POST /scan — sync (200) / async (202) data shapes.
+// POST /scan — sync (200) / async (202) data shapes. WS5-1: costUnits added to the sync shape (always known/billed by the time a 200 is returned).
 const _scanSyncData: IScanSyncData = {
   scanId: 's1',
   verdict: ProbeScanVerdict.CLEAN,
   viruses: [],
+  costUnits: 3,
 };
 const _scanAsyncData: IScanAsyncData = { scanId: 's1', status: ProbeScanStatus.QUEUED };
 
-// Webhook subscription — list/get shape vs the create-only `secret` shape.
+// Webhook subscription — WS5-7: secret is now ALWAYS present (list/create/
+// update), IProbeWebhookCreated is a source-compatible alias of IProbeWebhook.
 const _webhook: IProbeWebhook = {
   id: 'w1',
   callbackUrl: 'https://example.com/hook',
+  secret: 'shh',
   active: true,
   createdAt: new Date(),
 };
-const _webhookCreated: IProbeWebhookCreated = { ..._webhook, secret: 'shh' };
+const _webhookCreated: IProbeWebhookCreated = _webhook;
+
+// PATCH /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' };
 
 // Webhook delivery payload — the exact body signed by x-probe-signature
-// (see verifyProbeWebhookSignature).
+// (see verifyProbeWebhookSignature). WS5-1: costUnits added.
 const _deliveryPayload: IProbeWebhookDeliveryPayload = {
   scanId: 's1',
   context: null,
   verdict: ProbeScanVerdict.INFECTED,
   viruses: ['Eicar-Test-Signature'],
+  costUnits: 5,
 };
 
+// GET /webhook/:webhookId/deliveries row (WS5-6) — a persisted delivery-attempt.
+const _deliveryRecord: IProbeWebhookDelivery = {
+  id: 'd1',
+  webhookId: 'w1',
+  scanId: 's1',
+  url: 'https://example.com/hook',
+  statusCode: 200,
+  success: true,
+  attemptedAt: new Date(),
+  error: null,
+  createdAt: new Date(),
+};
+// webhookId is nullable (ad-hoc per-request callbackUrl with no matching registration).
+const _deliveryRecordAdHoc: IProbeWebhookDelivery = { ..._deliveryRecord, webhookId: null };
+
+// GET /usage data shape (WS5-3).
+const _usage: IProbeUsageData = { used: 10, limit: 1000, remaining: 990 };
+// -1 is the established "unlimited" sentinel (see estimateProbeScanCost's
+// server-side counterpart, utils/billing-emit.util.ts#UNLIMITED_EXPIRY_DAYS).
+const _usageUnlimited: IProbeUsageData = { used: 10, limit: -1, remaining: -1 };
+
+// estimateProbeScanCost (WS5-2) — pure shared cost model, ASYNC must cost
+// strictly less than SYNC for the same size (the scanner UI's "background
+// analysis saves tokens" tooltip depends on this). A one-byte compile-time
+// smoke check; the full behavioural suite lives in probe-scan-cost.utils.test.ts.
+const _asyncCost: number = estimateProbeScanCost(5 * 1024 * 1024, ProbeScanMode.ASYNC);
+const _syncCost: number = estimateProbeScanCost(5 * 1024 * 1024, ProbeScanMode.SYNC);
+if (_asyncCost >= _syncCost) {
+  throw new Error('estimateProbeScanCost: ASYNC must cost strictly less than SYNC');
+}
+
 void _verdicts;
 void _modes;
 void _statuses;
@@ -92,6 +148,12 @@ void _scanSyncData;
 void _scanAsyncData;
 void _webhook;
 void _webhookCreated;
+void _updateBody;
+void _updateBody2;
 void _deliveryPayload;
+void _deliveryRecord;
+void _deliveryRecordAdHoc;
+void _usage;
+void _usageUnlimited;
 
 export {};

package/src/utils/index.ts

@@ -5,3 +5,4 @@ export * from './icons.utils';
 export * from './enum.utils';
 export * from './extraction-webhook.utils';
 export * from './probe-webhook-signature.utils';
+export * from './probe-scan-cost.utils';

package/src/utils/probe-scan-cost.utils.ts

@@ -0,0 +1,101 @@
+// ──────────────────────────────────────────────
+// AbyssProbe scan cost model — pure, shared (client + server, no endpoint).
+//
+// Ported from abyss-storage's OWN weighted AV-scan cost model
+// (`apps/api/src/services/av-scan-usage.ts#computeAvScanCost`, introduced in
+// storage commit 317e4a0 "wire the weighted AV-scan quota", since made dead
+// code there by the AV v3 Phase 3b-2 hand-off — "storage never bills —
+// AbyssProbe does" — but the FORMULA itself is exactly what AbyssProbe's own
+// weighted billing needs, so it is ported here verbatim rather than
+// reinvented):
+//
+//   cost = round( (BASE + K_MB * ceil(sizeOctet / 1 MiB)) * MODE_WEIGHT[mode] )
+//
+// ASYNC costs LESS than SYNC (MODE_WEIGHT.async=1 < MODE_WEIGHT.sync=3) — a
+// synchronous scan holds the caller's request (and an engine worker) until
+// the verdict and cannot be batched/load-balanced, so it costs more than an
+// asynchronous (queued) scan of the SAME bytes. This is the numeric backing
+// for the scanner UI's "l'analyse en arrière-plan économise des tokens"
+// tooltip (WS1).
+//
+// PURE + DETERMINISTIC + no I/O: this is the SINGLE source of truth for
+// AbyssProbe's scan cost, used on BOTH sides of the wire —
+//   - server (apps/api/src/services/probe-scan.service.ts): the REAL cost
+//     billed via recordProbeScanUsage and persisted on probe_scans.costUnits
+//     once a scan reaches a verdict (DONE).
+//   - client (the AbyssProbe UI, or any external caller): a cost PREVIEW
+//     before scanning — call this with the picked file's size and the
+//     intended mode to show the estimated token cost, matching exactly what
+//     the server will bill (no separate "estimate" formula to drift out of
+//     sync with the real one — same function, same constants, both sides).
+//
+// Deliberately NOT exposed as an HTTP endpoint (no `POST /scan/estimate`):
+// the whole point of a pure function is that the client can compute it
+// locally, instantly, with zero round-trip — see this package's root README
+// note on `sdk.probe.*`'s HTTP-call-only convention; a helper like this one
+// (and `verifyProbeWebhookSignature` before it) is instead a plain top-level
+// export, not a `sdk.probe.*` method.
+// ──────────────────────────────────────────────
+
+import { ProbeScanMode } from '../types';
+
+/** Flat floor every scanned file pays (the "one scan" cost). Tunable. */
+export const PROBE_SCAN_COST_BASE = 1;
+
+/** Additional units per (ceil'd) mebibyte of scanned bytes. Tunable. */
+export const PROBE_SCAN_COST_K_MB = 1;
+
+/**
+ * Per-mode cost multiplier. A synchronous scan blocks the caller's request
+ * (and an engine worker) until the verdict and cannot be queued/batched, so
+ * it costs strictly MORE than an asynchronous scan of the same bytes —
+ * ASYNC < SYNC is a load-bearing invariant relied on by the scanner UI's
+ * "background analysis saves tokens" messaging (WS1). Tunable, but this
+ * ordering must never be inverted.
+ */
+export const PROBE_SCAN_COST_MODE_WEIGHT: Record<ProbeScanMode, number> = {
+  [ProbeScanMode.ASYNC]: 1,
+  [ProbeScanMode.SYNC]: 3,
+};
+
+/** One mebibyte, the unit the per-MB term is quantised to. */
+const ONE_MB = 1024 * 1024;
+
+/**
+ * Weighted cost of one AbyssProbe scan, in `ACCOUNT_AV_SCAN_UNITS` ("tokens"
+ * in the UI). Pure + deterministic — same inputs always produce the same
+ * output, no I/O, safe to call from a browser or a server.
+ *
+ * Returns `0` for a non-finite / non-positive `sizeOctet` (nothing to scan,
+ * nothing to bill) rather than throwing — a defensive, never-crash contract
+ * appropriate for a client-side cost preview that might run ahead of full
+ * input validation (e.g. while a file is still being selected).
+ *
+ * `mode` defaults to the (cheaper) ASYNC weight when given an unrecognised
+ * value, mirroring the ported formula's own `MODE_WEIGHT[mode] ?? MODE_WEIGHT.async`
+ * fallback — never silently the MORE expensive weight.
+ *
+ * `mode`'s type is widened to `| 'sync' | 'async'` alongside the enum
+ * itself, NOT just `ProbeScanMode`: apps/api's own server-side
+ * `database/probe-scan.enum.ts#ProbeScanMode` is a SEPARATE TypeScript enum
+ * declaration (kept server-local — see that file's header comment on why —
+ * with the identical 'sync'/'async' runtime values, so the wire format never
+ * drifts). TypeScript string enums are nominal: a same-valued member of that
+ * OTHER enum is not directly assignable to THIS package's `ProbeScanMode`
+ * parameter type, but IS assignable to a plain string-literal type matching
+ * its value — so the server can call this exact function (`scan.mode`,
+ * `estimateProbeScanCost`'s whole reason for living being ONE shared formula
+ * on both sides of the wire, see this file's header comment) without a cast.
+ */
+export const estimateProbeScanCost = (
+  sizeOctet: number,
+  mode: ProbeScanMode | 'sync' | 'async',
+): number => {
+  if (!Number.isFinite(sizeOctet) || sizeOctet <= 0) {
+    return 0;
+  }
+  const megabytes = Math.ceil(sizeOctet / ONE_MB);
+  const weight =
+    PROBE_SCAN_COST_MODE_WEIGHT[mode] ?? PROBE_SCAN_COST_MODE_WEIGHT[ProbeScanMode.ASYNC];
+  return Math.round((PROBE_SCAN_COST_BASE + PROBE_SCAN_COST_K_MB * megabytes) * weight);
+};