@abyss-project/tools 2.2.0 → 2.3.0

package/dist/utils/probe-scan-cost.utils.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateProbeScanCost = exports.PROBE_SCAN_COST_MODE_WEIGHT = exports.PROBE_SCAN_COST_K_MB = exports.PROBE_SCAN_COST_BASE = void 0;
+const types_1 = require("../types");
+exports.PROBE_SCAN_COST_BASE = 1;
+exports.PROBE_SCAN_COST_K_MB = 1;
+exports.PROBE_SCAN_COST_MODE_WEIGHT = {
+    [types_1.ProbeScanMode.ASYNC]: 1,
+    [types_1.ProbeScanMode.SYNC]: 3,
+};
+const ONE_MB = 1024 * 1024;
+const estimateProbeScanCost = (sizeOctet, mode) => {
+    if (!Number.isFinite(sizeOctet) || sizeOctet <= 0) {
+        return 0;
+    }
+    const megabytes = Math.ceil(sizeOctet / ONE_MB);
+    const weight = exports.PROBE_SCAN_COST_MODE_WEIGHT[mode] ?? exports.PROBE_SCAN_COST_MODE_WEIGHT[types_1.ProbeScanMode.ASYNC];
+    return Math.round((exports.PROBE_SCAN_COST_BASE + exports.PROBE_SCAN_COST_K_MB * megabytes) * weight);
+};
+exports.estimateProbeScanCost = estimateProbeScanCost;
+//# sourceMappingURL=probe-scan-cost.utils.js.map

package/dist/utils/probe-scan-cost.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe-scan-cost.utils.js","sourceRoot":"","sources":["../../src/utils/probe-scan-cost.utils.ts"],"names":[],"mappings":";;;AAuCA,oCAAyC;AAG5B,QAAA,oBAAoB,GAAG,CAAC,CAAC;AAGzB,QAAA,oBAAoB,GAAG,CAAC,CAAC;AAUzB,QAAA,2BAA2B,GAAkC;IACxE,CAAC,qBAAa,CAAC,KAAK,CAAC,EAAE,CAAC;IACxB,CAAC,qBAAa,CAAC,IAAI,CAAC,EAAE,CAAC;CACxB,CAAC;AAGF,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;AA4BpB,MAAM,qBAAqB,GAAG,CACnC,SAAiB,EACjB,IAAsC,EAC9B,EAAE;IACV,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QAClD,OAAO,CAAC,CAAC;IACX,CAAC;IACD,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;IAChD,MAAM,MAAM,GACV,mCAA2B,CAAC,IAAI,CAAC,IAAI,mCAA2B,CAAC,qBAAa,CAAC,KAAK,CAAC,CAAC;IACxF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,4BAAoB,GAAG,4BAAoB,GAAG,SAAS,CAAC,GAAG,MAAM,CAAC,CAAC;AACxF,CAAC,CAAC;AAXW,QAAA,qBAAqB,yBAWhC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abyss-project/tools",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Core package to interact with Abyss-Project Tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/api/index.ts

@@ -60,3 +60,5 @@ export * from './probe-scan.api';
 export * from './probe-webhook.api';
 export * from './probe-scan.application.api';
 export * from './probe-webhook.application.api';
+export * from './probe-usage.api';
+export * from './probe-usage.application.api';

package/src/api/probe-usage.api.ts

@@ -0,0 +1,47 @@
+// ──────────────────────────────────────────────
+// AbyssProbe usage API — WS5-3 (AbyssProbe UX rework). `GET /usage`: current
+// ACCOUNT_AV_SCAN_UNITS ("tokens") used/limit/remaining for the caller's
+// scope, via the same billing check the quota gate itself already uses (see
+// apps/api/src/utils/probe-scan-billing.util.ts#getProbeScanUsage). Mirrors
+// apps/api/src/api/controllers/probe-usage.controller.ts EXACTLY. No
+// `probe/` path prefix — `@Controller({ prefixPath: '/usage' })` mounts
+// directly at `usage`.
+//
+// See probe-usage.application.api.ts for the application/API-key-auth
+// counterpart (`/application/:applicationId/usage`, Phase 3a).
+// ──────────────────────────────────────────────
+
+import { AbyssToolsCore } from '..';
+import type { IProbeUsageScopeQuery, IProbeUsageResponse } from '../types';
+
+const DEFAULT_API_KEY_HEADER = 'abyss-api-key';
+
+function authHeader(apiKey?: string): Record<string, string> {
+  return apiKey ? { [DEFAULT_API_KEY_HEADER]: apiKey } : {};
+}
+
+/** Renames `organizationId` to the wire's `organization_id` (see probe-scan.api.ts). */
+function serializeProbeQuery<T extends object>(query: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(query as Record<string, unknown>)) {
+    if (value === undefined || value === null) continue;
+    const wireKey = key === 'organizationId' ? 'organization_id' : key;
+    out[wireKey] = value;
+  }
+  return out;
+}
+
+/**
+ * `GET /usage` — current ACCOUNT_AV_SCAN_UNITS consumption for the caller's
+ * scope (personal by default, `organizationId` for an organization scope).
+ */
+export const getProbeUsage = async (
+  scope: IProbeUsageScopeQuery = {},
+  apiKey?: string,
+): Promise<IProbeUsageResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IProbeUsageResponse>('usage', {
+      params: serializeProbeQuery(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;

package/src/api/probe-usage.application.api.ts

@@ -0,0 +1,25 @@
+// ──────────────────────────────────────────────
+// AbyssProbe APPLICATION usage API — WS5-3 (AbyssProbe UX rework). `GET
+// /application/:applicationId/usage`: current ACCOUNT_AV_SCAN_UNITS
+// consumption for the calling application's resolved billing organization.
+// Mirrors apps/api/src/api/controllers/probe-usage-application.controller.ts
+// EXACTLY — the application counterpart of probe-usage.api.ts.
+// ──────────────────────────────────────────────
+
+import { AbyssToolsCore, API_KEY_APPLICATION_HEADER } from '..';
+import type { IProbeUsageResponse } from '../types';
+
+function authHeaderApplication(applicationApiKey?: string): Record<string, string> {
+  return applicationApiKey ? { [API_KEY_APPLICATION_HEADER]: applicationApiKey } : {};
+}
+
+/** `GET /application/:applicationId/usage` — current ACCOUNT_AV_SCAN_UNITS consumption for the calling application. */
+export const getProbeUsageApplication = async (
+  applicationId: string,
+  applicationApiKey?: string,
+): Promise<IProbeUsageResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IProbeUsageResponse>(`application/${applicationId}/usage`, {
+      headers: authHeaderApplication(applicationApiKey),
+    })
+  ).data;

package/src/api/probe-webhook.api.ts

@@ -1,10 +1,9 @@
 // ──────────────────────────────────────────────
 // AbyssProbe webhook subscription API — CRUD over registered `probe_webhooks`
-// (create / list / delete only — no update, no reset-secret: mirrors
-// apps/api/src/api/controllers/probe-webhook.controller.ts's deliberately
-// small surface EXACTLY, see that file's header comment). No `probe/` path
-// prefix — `@Controller({ prefixPath: '/webhook' })` mounts directly at
-// `webhook`.
+// (create / list / delete / update, + paginated delivery history — mirrors
+// apps/api/src/api/controllers/probe-webhook.controller.ts EXACTLY, see that
+// file's header comment). No `probe/` path prefix — `@Controller({
+// prefixPath: '/webhook' })` mounts directly at `webhook`.
 //
 // See probe-webhook.application.api.ts for the application/API-key-auth
 // counterpart of this client (`/application/:applicationId/webhook...`,
@@ -15,10 +14,14 @@
 import { AbyssToolsCore } from '..';
 import type {
   ICreateProbeWebhookBody,
+  IUpdateProbeWebhookBody,
   IProbeWebhookScopeQuery,
+  IListProbeWebhookDeliveriesQuery,
   ICreateProbeWebhookResponse,
   IListProbeWebhookResponse,
   IDeleteProbeWebhookResponse,
+  IUpdateProbeWebhookResponse,
+  IListProbeWebhookDeliveriesResponse,
 } from '../types';
 
 const DEFAULT_API_KEY_HEADER = 'abyss-api-key';
@@ -79,3 +82,38 @@ export const deleteProbeWebhook = async (
       headers: authHeader(apiKey),
     })
   ).data;
+
+/**
+ * `PATCH /webhook/:webhookId` (WS5-5) — edit `callbackUrl` and/or `active`.
+ * At least one field is required. Scoped like {@link deleteProbeWebhook}
+ * (404, never 403, for a webhookId outside the resolved scope). The response
+ * includes `secret` — re-displayable now, see {@link IProbeWebhook}.
+ */
+export const updateProbeWebhook = async (
+  webhookId: string,
+  body: IUpdateProbeWebhookBody,
+  scope: IProbeWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<IUpdateProbeWebhookResponse> =>
+  (
+    await AbyssToolsCore.axios.patch<IUpdateProbeWebhookResponse>(`webhook/${webhookId}`, body, {
+      params: serializeProbeQuery(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+
+/**
+ * `GET /webhook/:webhookId/deliveries` (WS5-6) — paginated delivery-attempt
+ * history for one registered webhook. Scoped like {@link deleteProbeWebhook}.
+ */
+export const listProbeWebhookDeliveries = async (
+  webhookId: string,
+  query: IListProbeWebhookDeliveriesQuery = {},
+  apiKey?: string,
+): Promise<IListProbeWebhookDeliveriesResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IListProbeWebhookDeliveriesResponse>(
+      `webhook/${webhookId}/deliveries`,
+      { params: serializeProbeQuery(query), headers: authHeader(apiKey) },
+    )
+  ).data;

package/src/api/probe-webhook.application.api.ts

@@ -1,8 +1,8 @@
 // ──────────────────────────────────────────────
 // AbyssProbe APPLICATION webhook subscription API — CRUD over registered
-// `probe_webhooks` owned by a calling application (create / list / delete
-// only — no update, no reset-secret: same deliberately small surface as the
-// personal/org client, see probe-webhook.api.ts's header comment). Mirrors
+// `probe_webhooks` owned by a calling application (create / list / delete /
+// update, + paginated delivery history — same surface as the personal/org
+// client, see probe-webhook.api.ts's header comment). Mirrors
 // apps/api/src/api/controllers/probe-webhook-application.controller.ts
 // EXACTLY — the application counterpart of probe-webhook.api.ts, for
 // inter-service callers (abyss-storage, external integrations)
@@ -10,7 +10,9 @@
 //
 // Reuses every request/response TYPE verbatim (`ICreateProbeWebhookBody`,
 // `ICreateProbeWebhookResponse`, `IListProbeWebhookResponse`,
-// `IDeleteProbeWebhookResponse`) — never redefined here. No scope
+// `IDeleteProbeWebhookResponse`, `IUpdateProbeWebhookBody`,
+// `IUpdateProbeWebhookResponse`, `IListProbeWebhookDeliveriesQuery`,
+// `IListProbeWebhookDeliveriesResponse`) — never redefined here. No scope
 // argument/query on any of these calls (unlike the personal/org client's
 // `IProbeWebhookScopeQuery`) — an application caller's scope is entirely its
 // `:applicationId` URL segment, resolved server-side by
@@ -25,15 +27,29 @@
 import { AbyssToolsCore, API_KEY_APPLICATION_HEADER } from '..';
 import type {
   ICreateProbeWebhookBody,
+  IUpdateProbeWebhookBody,
+  IListProbeWebhookDeliveriesQuery,
   ICreateProbeWebhookResponse,
   IListProbeWebhookResponse,
   IDeleteProbeWebhookResponse,
+  IUpdateProbeWebhookResponse,
+  IListProbeWebhookDeliveriesResponse,
 } from '../types';
 
 function authHeaderApplication(applicationApiKey?: string): Record<string, string> {
   return applicationApiKey ? { [API_KEY_APPLICATION_HEADER]: applicationApiKey } : {};
 }
 
+/** Renames nothing (no `organizationId` ever travels on an application call) — drops undefined/null and ISO-stringifies `Date`s, mirroring probe-scan.application.api.ts's own local helper. */
+function serializeProbeQuery<T extends object>(query: T): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(query as Record<string, unknown>)) {
+    if (value === undefined || value === null) continue;
+    out[key] = value instanceof Date ? value.toISOString() : value;
+  }
+  return out;
+}
+
 /**
  * `POST /application/:applicationId/webhook` — register a callbackUrl owned
  * by the calling application. The response's `secret` field (HMAC signing
@@ -85,3 +101,41 @@ export const deleteProbeWebhookApplication = async (
       { headers: authHeaderApplication(applicationApiKey) },
     )
   ).data;
+
+/**
+ * `PATCH /application/:applicationId/webhook/:webhookId` (WS5-5) — edit
+ * `callbackUrl` and/or `active` on a webhook owned by the calling
+ * application. Cross-tenant guarded server-side (404, never 403). The
+ * response includes `secret` — re-displayable now, see {@link IProbeWebhook}.
+ */
+export const updateProbeWebhookApplication = async (
+  applicationId: string,
+  webhookId: string,
+  body: IUpdateProbeWebhookBody,
+  applicationApiKey?: string,
+): Promise<IUpdateProbeWebhookResponse> =>
+  (
+    await AbyssToolsCore.axios.patch<IUpdateProbeWebhookResponse>(
+      `application/${applicationId}/webhook/${webhookId}`,
+      body,
+      { headers: authHeaderApplication(applicationApiKey) },
+    )
+  ).data;
+
+/**
+ * `GET /application/:applicationId/webhook/:webhookId/deliveries` (WS5-6) —
+ * paginated delivery-attempt history for one webhook owned by the calling
+ * application. Cross-tenant guarded server-side (404, never 403).
+ */
+export const listProbeWebhookDeliveriesApplication = async (
+  applicationId: string,
+  webhookId: string,
+  query: Omit<IListProbeWebhookDeliveriesQuery, 'organizationId'> = {},
+  applicationApiKey?: string,
+): Promise<IListProbeWebhookDeliveriesResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IListProbeWebhookDeliveriesResponse>(
+      `application/${applicationId}/webhook/${webhookId}/deliveries`,
+      { params: serializeProbeQuery(query), headers: authHeaderApplication(applicationApiKey) },
+    )
+  ).data;

package/src/index.ts

@@ -36,6 +36,8 @@ import * as probeScanApi from './api/probe-scan.api';
 import * as probeWebhookApi from './api/probe-webhook.api';
 import * as probeScanApplicationApi from './api/probe-scan.application.api';
 import * as probeWebhookApplicationApi from './api/probe-webhook.application.api';
+import * as probeUsageApi from './api/probe-usage.api';
+import * as probeUsageApplicationApi from './api/probe-usage.application.api';
 
 export * from './api';
 export * from './types';
@@ -347,10 +349,18 @@ type AbyssToolsCoreSDK = {
     getScan: typeof probeScanApi.getScan;
     /** `GET /scan` — paginated history/search. */
     listScans: typeof probeScanApi.listScans;
+    /** `GET /usage` — current ACCOUNT_AV_SCAN_UNITS used/limit/remaining for the caller's scope. */
+    usage: {
+      get: typeof probeUsageApi.getProbeUsage;
+    };
     webhook: {
       create: typeof probeWebhookApi.createProbeWebhook;
       list: typeof probeWebhookApi.listProbeWebhook;
       delete: typeof probeWebhookApi.deleteProbeWebhook;
+      /** `PATCH /webhook/:webhookId` — edit callbackUrl and/or active. */
+      update: typeof probeWebhookApi.updateProbeWebhook;
+      /** `GET /webhook/:webhookId/deliveries` — paginated delivery-attempt history. */
+      listDeliveries: typeof probeWebhookApi.listProbeWebhookDeliveries;
     };
     /**
      * Application/API-key-auth counterpart (Phase 3a) — for inter-service
@@ -371,10 +381,18 @@ type AbyssToolsCoreSDK = {
       getScan: typeof probeScanApplicationApi.getScanApplication;
       /** `GET /application/:applicationId/scan` — paginated history/search. */
       listScans: typeof probeScanApplicationApi.listScansApplication;
+      /** `GET /application/:applicationId/usage` — current ACCOUNT_AV_SCAN_UNITS used/limit/remaining for the calling application. */
+      usage: {
+        get: typeof probeUsageApplicationApi.getProbeUsageApplication;
+      };
       webhook: {
         create: typeof probeWebhookApplicationApi.createProbeWebhookApplication;
         list: typeof probeWebhookApplicationApi.listProbeWebhookApplication;
         delete: typeof probeWebhookApplicationApi.deleteProbeWebhookApplication;
+        /** `PATCH /application/:applicationId/webhook/:webhookId` — edit callbackUrl and/or active. */
+        update: typeof probeWebhookApplicationApi.updateProbeWebhookApplication;
+        /** `GET /application/:applicationId/webhook/:webhookId/deliveries` — paginated delivery-attempt history. */
+        listDeliveries: typeof probeWebhookApplicationApi.listProbeWebhookDeliveriesApplication;
       };
     };
   };
@@ -775,10 +793,15 @@ export class AbyssToolsCore {
         scanAsync: probeScanApi.scanAsync,
         getScan: probeScanApi.getScan,
         listScans: probeScanApi.listScans,
+        usage: {
+          get: probeUsageApi.getProbeUsage,
+        },
         webhook: {
           create: probeWebhookApi.createProbeWebhook,
           list: probeWebhookApi.listProbeWebhook,
           delete: probeWebhookApi.deleteProbeWebhook,
+          update: probeWebhookApi.updateProbeWebhook,
+          listDeliveries: probeWebhookApi.listProbeWebhookDeliveries,
         },
         application: {
           scan: probeScanApplicationApi.scanApplication,
@@ -786,10 +809,15 @@ export class AbyssToolsCore {
           scanAsync: probeScanApplicationApi.scanAsyncApplication,
           getScan: probeScanApplicationApi.getScanApplication,
           listScans: probeScanApplicationApi.listScansApplication,
+          usage: {
+            get: probeUsageApplicationApi.getProbeUsageApplication,
+          },
           webhook: {
             create: probeWebhookApplicationApi.createProbeWebhookApplication,
             list: probeWebhookApplicationApi.listProbeWebhookApplication,
             delete: probeWebhookApplicationApi.deleteProbeWebhookApplication,
+            update: probeWebhookApplicationApi.updateProbeWebhookApplication,
+            listDeliveries: probeWebhookApplicationApi.listProbeWebhookDeliveriesApplication,
           },
         },
       },

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

@@ -29,3 +29,4 @@ export * from './transfer.request';
 export * from './extraction.request';
 export * from './probe-scan.request';
 export * from './probe-webhook.request';
+export * from './probe-usage.request';

package/src/types/interface/api/requests/probe-usage.request.ts

@@ -0,0 +1,7 @@
+// WS5-3 (AbyssProbe UX rework) — `GET /usage` / `GET /application/:applicationId/usage`.
+// Mirrors apps/api/src/api/validators/probe-usage.validator.ts's Joi schema.
+
+/** `GET /usage` query — personal scope (default) or an organization. Not needed for the application variant (its scope is the `:applicationId` URL segment). */
+export interface IProbeUsageScopeQuery {
+  organizationId?: string;
+}

package/src/types/interface/api/requests/probe-webhook.request.ts

@@ -1,7 +1,8 @@
 // Mirrors apps/api/src/api/controllers/probe-webhook.controller.ts's
-// ScopeQuery/CreateBody and probe-webhook.validator.ts's Joi schemas.
+// ScopeQuery/CreateBody/UpdateBody and probe-webhook.validator.ts's Joi
+// schemas.
 
-/** Shared by create/list/delete — personal scope (default) or an organization. */
+/** Shared by create/list/delete/update — personal scope (default) or an organization. */
 export interface IProbeWebhookScopeQuery {
   organizationId?: string;
 }
@@ -10,3 +11,23 @@ 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/index.ts

@@ -33,3 +33,4 @@ 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

@@ -12,6 +12,13 @@ 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>;
 

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

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