@abyss-project/tools 2.1.0 → 2.3.0

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.test.ts

@@ -0,0 +1,17 @@
+// Type-level compile test for the probe-webhook api surface.
+// No jest runner in this SDK package; compile guard only.
+// Run: npx tsc --noEmit (from packages/abyss_tools_core), or `npm run build`.
+
+import * as api from './probe-webhook.api';
+
+// All three functions must be exported — deliberately no update/reset-secret
+// (see probe-webhook.controller.ts's header comment on the small CRUD surface).
+const _create: typeof api.createProbeWebhook = api.createProbeWebhook;
+const _list: typeof api.listProbeWebhook = api.listProbeWebhook;
+const _delete: typeof api.deleteProbeWebhook = api.deleteProbeWebhook;
+
+void _create;
+void _list;
+void _delete;
+
+export {};

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

@@ -0,0 +1,119 @@
+// ──────────────────────────────────────────────
+// AbyssProbe webhook subscription API — CRUD over registered `probe_webhooks`
+// (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...`,
+// Phase 3a) — it reuses every request/response type verbatim; only the URL
+// prefix, the extra `applicationId` argument, and the auth header differ.
+// ──────────────────────────────────────────────
+
+import { AbyssToolsCore } from '..';
+import type {
+  ICreateProbeWebhookBody,
+  IUpdateProbeWebhookBody,
+  IProbeWebhookScopeQuery,
+  IListProbeWebhookDeliveriesQuery,
+  ICreateProbeWebhookResponse,
+  IListProbeWebhookResponse,
+  IDeleteProbeWebhookResponse,
+  IUpdateProbeWebhookResponse,
+  IListProbeWebhookDeliveriesResponse,
+} 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 instanceof Date ? value.toISOString() : value;
+  }
+  return out;
+}
+
+/**
+ * `POST /webhook` — register a callbackUrl for the caller's scope. The
+ * response's `secret` field (HMAC signing secret) is returned ONLY here —
+ * store it immediately, it cannot be re-revealed later.
+ */
+export const createProbeWebhook = async (
+  body: ICreateProbeWebhookBody,
+  scope: IProbeWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<ICreateProbeWebhookResponse> =>
+  (
+    await AbyssToolsCore.axios.post<ICreateProbeWebhookResponse>('webhook', body, {
+      params: serializeProbeQuery(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+
+/** `GET /webhook` — flat, scope-filtered list (not paginated — bounded by WEBHOOK_MAX_PER_SCOPE server-side). */
+export const listProbeWebhook = async (
+  scope: IProbeWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<IListProbeWebhookResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IListProbeWebhookResponse>('webhook', {
+      params: serializeProbeQuery(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+
+/** `DELETE /webhook/:webhookId`. */
+export const deleteProbeWebhook = async (
+  webhookId: string,
+  scope: IProbeWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<IDeleteProbeWebhookResponse> =>
+  (
+    await AbyssToolsCore.axios.delete<IDeleteProbeWebhookResponse>(`webhook/${webhookId}`, {
+      params: serializeProbeQuery(scope),
+      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.test.ts

@@ -0,0 +1,18 @@
+// Type-level compile test for the probe-webhook APPLICATION api surface.
+// No jest runner in this SDK package; compile guard only (mirrors
+// probe-webhook.api.test.ts).
+// Run: npx tsc --noEmit (from packages/abyss_tools_core), or `npm run build`.
+
+import * as api from './probe-webhook.application.api';
+
+// All three functions must be exported — deliberately no update/reset-secret
+// (see probe-webhook.api.ts's header comment on the small CRUD surface).
+const _create: typeof api.createProbeWebhookApplication = api.createProbeWebhookApplication;
+const _list: typeof api.listProbeWebhookApplication = api.listProbeWebhookApplication;
+const _delete: typeof api.deleteProbeWebhookApplication = api.deleteProbeWebhookApplication;
+
+void _create;
+void _list;
+void _delete;
+
+export {};

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

@@ -0,0 +1,141 @@
+// ──────────────────────────────────────────────
+// AbyssProbe APPLICATION webhook subscription API — CRUD over registered
+// `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)
+// authenticating with a project API key instead of a personal/org session.
+//
+// Reuses every request/response TYPE verbatim (`ICreateProbeWebhookBody`,
+// `ICreateProbeWebhookResponse`, `IListProbeWebhookResponse`,
+// `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
+// ProbeApplicationMiddleware; there is nothing to select between.
+//
+// `authHeaderApplication` is kept LOCAL and unexported, same convention as
+// the personal/org client's own `authHeader` — it sends
+// `API_KEY_APPLICATION_HEADER` (`abyss-api-key-application`, imported from
+// this package's root) instead of the personal `abyss-api-key` header.
+// ──────────────────────────────────────────────
+
+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
+ * secret) is returned ONLY here — store it immediately, it cannot be
+ * re-revealed later.
+ */
+export const createProbeWebhookApplication = async (
+  applicationId: string,
+  body: ICreateProbeWebhookBody,
+  applicationApiKey?: string,
+): Promise<ICreateProbeWebhookResponse> =>
+  (
+    await AbyssToolsCore.axios.post<ICreateProbeWebhookResponse>(
+      `application/${applicationId}/webhook`,
+      body,
+      { headers: authHeaderApplication(applicationApiKey) },
+    )
+  ).data;
+
+/**
+ * `GET /application/:applicationId/webhook` — flat list of the calling
+ * application's own webhooks (not paginated — bounded by
+ * WEBHOOK_MAX_PER_SCOPE server-side).
+ */
+export const listProbeWebhookApplication = async (
+  applicationId: string,
+  applicationApiKey?: string,
+): Promise<IListProbeWebhookResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IListProbeWebhookResponse>(
+      `application/${applicationId}/webhook`,
+      { headers: authHeaderApplication(applicationApiKey) },
+    )
+  ).data;
+
+/**
+ * `DELETE /application/:applicationId/webhook/:webhookId` — cross-tenant
+ * guarded server-side by a direct `applicationId` comparison (404, never
+ * 403).
+ */
+export const deleteProbeWebhookApplication = async (
+  applicationId: string,
+  webhookId: string,
+  applicationApiKey?: string,
+): Promise<IDeleteProbeWebhookResponse> =>
+  (
+    await AbyssToolsCore.axios.delete<IDeleteProbeWebhookResponse>(
+      `application/${applicationId}/webhook/${webhookId}`,
+      { 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

@@ -32,6 +32,12 @@ import * as extractionApi from './api/extraction.api';
 import * as extractionSettingsApi from './api/extraction-settings.api';
 import * as extractionPlanPresetApi from './api/extraction-plan-preset.api';
 import * as monitorApi from './api/monitor.api';
+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';
@@ -42,8 +48,24 @@ export * from './server-sent-events';
 const DEFAULT_BASE_URL = 'https://tools-api.abyss-project.fr/api/';
 
 export const API_KEY_HEADER = 'abyss-api-key';
+/**
+ * Application-level API key header (Phase 3a — AbyssProbe application/API-key
+ * authentication). Same literal value every other Abyss service's own core
+ * package independently declares for its `ApplicationMiddleware` (abyss-
+ * storage, abyss-monitor, abyss-console — see
+ * probe-application.middleware.ts for the mirrored resolution logic).
+ */
+export const API_KEY_APPLICATION_HEADER = 'abyss-api-key-application';
 export const ADMIN_TOKEN_HEADER = 'abyss-admin-token';
 
+/**
+ * Header carrying the HMAC-SHA256 signature of a probe webhook delivery's
+ * raw JSON body (see apps/api/src/services/probe-webhook-delivery.service.ts).
+ * Verify it with {@link verifyProbeWebhookSignature} (re-exported from './utils').
+ */
+export const PROBE_WEBHOOK_SIGNATURE_HEADER = 'x-probe-signature';
+export const PROBE_WEBHOOK_SIGNATURE_ALGORITHM = 'sha256';
+
 const NUMBER_RETRY_API = 10;
 const BASE_DELAY_BETWEEN_RETRY = 5000;
 const RETRY_CODES = [
@@ -316,6 +338,64 @@ type AbyssToolsCoreSDK = {
   monitor: {
     up: typeof monitorApi.upMonitor;
   };
+  probe: {
+    /** `POST /scan` — sync (default) or async depending on `options.mode`. */
+    scan: typeof probeScanApi.scan;
+    /** `POST /scan` forced to `mode: sync` — precisely-typed 200 response. */
+    scanSync: typeof probeScanApi.scanSync;
+    /** `POST /scan?mode=async` — precisely-typed 202 response. */
+    scanAsync: typeof probeScanApi.scanAsync;
+    /** `GET /scan/:scanId` — poll a scan's status/verdict. */
+    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
+     * callers (abyss-storage, external integrations) instead of a
+     * personal/org session. Same request/response contracts as the methods
+     * above, hitting `/application/:applicationId/...` and authenticated
+     * with the `abyss-api-key-application` header ({@link
+     * API_KEY_APPLICATION_HEADER}) instead of the personal `abyss-api-key`.
+     */
+    application: {
+      /** `POST /application/:applicationId/scan` — sync (default) or async depending on `options.mode`. */
+      scan: typeof probeScanApplicationApi.scanApplication;
+      /** `POST /application/:applicationId/scan` forced to `mode: sync` — precisely-typed 200 response. */
+      scanSync: typeof probeScanApplicationApi.scanSyncApplication;
+      /** `POST /application/:applicationId/scan?mode=async` — precisely-typed 202 response. */
+      scanAsync: typeof probeScanApplicationApi.scanAsyncApplication;
+      /** `GET /application/:applicationId/scan/:scanId` — poll a scan's status/verdict. */
+      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;
+      };
+    };
+  };
   tag: {
     list: typeof tagApi.listTag;
     create: typeof tagApi.createTag;
@@ -707,6 +787,40 @@ export class AbyssToolsCore {
       monitor: {
         up: monitorApi.upMonitor,
       },
+      probe: {
+        scan: probeScanApi.scan,
+        scanSync: probeScanApi.scanSync,
+        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,
+          scanSync: probeScanApplicationApi.scanSyncApplication,
+          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,
+          },
+        },
+      },
       tag: {
         list: tagApi.listTag,
         create: tagApi.createTag,

package/src/types/enum/api-error.enum.ts

@@ -20,29 +20,4 @@ export enum Code {
   atlasDocumentLimitReached = 'atlas_document_limit_reached',
   boardCardDocumentLimitReached = 'board_card_document_limit_reached',
   boardCardMoveInvalidDestination = 'board_card_move_invalid_destination',
-  // AV v3 P2 async-enforce: thrown by assertNotPendingScan while a document's
-  // antivirus scan is still running (scanStatus === 'pending_scan'). Mapped
-  // to HTTP 423 in http-response-error.module.ts.
-  boardCardDocumentAnalysing = 'board_card_document_analysing',
-  atlasDocumentAnalysing = 'atlas_document_analysing',
-  // AV v3 P3 async-enforce: thrown by extractionFileService.assertNotPendingScan
-  // while an ARCHIVE-OWNED extraction_files row's antivirus scan is still
-  // running (scanStatus === 'pending_scan'). Gates only derived OUTPUTS
-  // (bundle/records/diff/export/share) — never the extraction metadata
-  // itself, which already ran synchronously before any verdict was known.
-  // Mapped to HTTP 423 in http-response-error.module.ts.
-  extractionFileAnalysing = 'extraction_file_analysing',
-  // AV v3 P3 async-enforce server backstop: thrown by
-  // beamUploadService.attachFiles when a resolved storage file's scanStatus
-  // is not PENDING_SCAN at attach time. AbyssBeam's presign is front-driven
-  // (resumable-upload.ts calls AbyssStorage directly, never through this
-  // backend), so a client could omit `antivirus: { scan: true }` on its own
-  // presign request; a properly-enrolled fresh upload is always
-  // PENDING_SCAN the moment attach is called (the async worker has not run
-  // yet), so anything else — most tellingly a null/absent scanStatus,
-  // meaning no scan was ever requested — means enrollment was bypassed and
-  // the attach is rejected outright. Not mapped in http-response-error
-  // .module.ts's statusByCode table, so it falls through to the default 400
-  // (a rejected request, not a "still analysing" 423 state).
-  beamFileNotEnrolled = 'beam_file_not_enrolled',
 }

package/src/types/enum/index.ts

@@ -11,4 +11,4 @@ export * from './extraction-feedback-issue-type.enum';
 export * from './provider-kind.enum';
 export * from './interpreter-kind.enum';
 export * from './combine-strategy.enum';
-export * from './file-scan-status.enum';
+export * from './probe-scan.enum';

package/src/types/enum/probe-scan.enum.ts

@@ -0,0 +1,44 @@
+// Mirrors apps/api/src/database/probe-scan.enum.ts EXACTLY (same string
+// values — this SDK talks to that API over the wire, so the values must
+// match byte-for-byte). Kept as a single file here too, on purpose: the
+// server groups all three enums in one file for the same reason (they are
+// one cohesive scan vocabulary), see that file's header comment.
+
+/**
+ * Antivirus scan verdict. `null` on the wire while the scan has not reached
+ * `DONE` yet (see {@link ProbeScanStatus}) — a scan that never completes
+ * (e.g. the engine throws) is left at its last real status with no
+ * fabricated verdict.
+ */
+export enum ProbeScanVerdict {
+  CLEAN = 'clean',
+  INFECTED = 'infected',
+}
+
+/**
+ * How the scan was (or will be) run: `SYNC` blocks the request until the
+ * engine returns the verdict inline; `ASYNC` queues the job and delivers the
+ * verdict later via a registered webhook and/or the per-request
+ * `callbackUrl`, and/or by polling `GET /scan/:scanId`.
+ */
+export enum ProbeScanMode {
+  SYNC = 'sync',
+  ASYNC = 'async',
+}
+
+/**
+ * Scan lifecycle. A SYNC scan skips `QUEUED` entirely (created directly at
+ * `SCANNING`). An ASYNC scan is created at `QUEUED`, flipped to `SCANNING`
+ * once a worker picks the job off the queue, then to `DONE` or `ERROR`.
+ *
+ * `ERROR` (async-only) is a TERMINAL, no-verdict state — there is no
+ * automatic requeue/retry (the uploaded bytes are deleted the moment the job
+ * ends, success or failure). A caller that wants to retry submits a brand
+ * new `POST /scan?mode=async`.
+ */
+export enum ProbeScanStatus {
+  QUEUED = 'queued',
+  SCANNING = 'scanning',
+  DONE = 'done',
+  ERROR = 'error',
+}

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

@@ -27,3 +27,6 @@ export * from './metrics.request';
 export * from './tag.request';
 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-scan.request.ts

@@ -0,0 +1,50 @@
+import { ProbeScanMode, ProbeScanStatus, ProbeScanVerdict } from '../../../enum';
+
+// Mirrors apps/api/src/api/controllers/probe-scan.controller.ts's ScanBody +
+// HistoryQuery, and apps/api/src/api/validators/probe-scan.validator.ts's
+// historyQuery() Joi schema (field names/optionality).
+
+/**
+ * Options accepted by `sdk.probe.scan(file, options)` — `POST /scan`. `mode`
+ * and `organizationId` travel as query params (`?mode=async&organization_id=`);
+ * `context` and `callbackUrl` travel as multipart text fields alongside the
+ * file — the sdk client handles that split, callers just pass one object.
+ */
+export interface IScanOptions {
+  /** sync (default — verdict returned inline) or async (queued, 202 + webhook/poll). */
+  mode?: ProbeScanMode;
+  /** Personal scope (default) or an organization the caller belongs to. */
+  organizationId?: string;
+  /** Free-form caller reference (e.g. `{ applicationFileId }`), stored verbatim. */
+  context?: Record<string, unknown>;
+  /** ASYNC-only per-request delivery override (https only). Ignored for a SYNC scan. */
+  callbackUrl?: string;
+  /** Filename reported to the server (defaults to `'file'`). Cosmetic only. */
+  filename?: string;
+  /** Content-Type hint used when constructing a Blob from a raw buffer/Uint8Array in a browser context. */
+  mimeType?: string;
+}
+
+/**
+ * `GET /scan` query — all filters optional, combined with AND.
+ * `contextKey`/`contextValue` must be supplied together (business-reference
+ * search inside the free-form `context` JSONB column) — supplying one
+ * without the other is rejected by the API (400).
+ */
+export interface IListScansQuery {
+  organizationId?: string;
+  verdict?: ProbeScanVerdict;
+  mode?: ProbeScanMode;
+  status?: ProbeScanStatus;
+  /** Date range on `createdAt`, inclusive at both ends. */
+  from?: Date;
+  to?: Date;
+  /** Case-insensitive partial match on the original file name. */
+  fileName?: string;
+  contextKey?: string;
+  contextValue?: string;
+  /** @default 1 */
+  page?: number;
+  /** @default 20, server max 200. */
+  limit?: number;
+}

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