@abyss-project/tools 2.2.0 → 2.3.0

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