@abyss-project/tools 2.1.0 → 2.3.0

package/dist/types/interface/models/probe-webhook-delivery.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe-webhook-delivery.dto.js","sourceRoot":"","sources":["../../../../src/types/interface/models/probe-webhook-delivery.dto.ts"],"names":[],"mappings":""}

package/dist/types/interface/models/probe-webhook.dto.d.ts

@@ -0,0 +1,8 @@
+export interface IProbeWebhook {
+    id: string;
+    callbackUrl: string;
+    secret: string;
+    active: boolean;
+    createdAt: Date;
+}
+export type IProbeWebhookCreated = IProbeWebhook;

package/dist/types/interface/{api/requests/file-scan.request.js → models/probe-webhook.dto.js}

@@ -1,3 +1,3 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=file-scan.request.js.map
+//# sourceMappingURL=probe-webhook.dto.js.map

package/dist/types/interface/models/probe-webhook.dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe-webhook.dto.js","sourceRoot":"","sources":["../../../../src/types/interface/models/probe-webhook.dto.ts"],"names":[],"mappings":""}

package/dist/types/tests/probe.dto.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/tests/probe.dto.test.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const __1 = require("..");
+const utils_1 = require("../../utils");
+const _verdicts = { clean: true, infected: true };
+const _modes = { sync: true, async: true };
+const _statuses = {
+    queued: true,
+    scanning: true,
+    done: true,
+    error: true,
+};
+const _scanDetail = {
+    scanId: 's1',
+    status: __1.ProbeScanStatus.DONE,
+    verdict: __1.ProbeScanVerdict.CLEAN,
+    viruses: [],
+    context: null,
+    fileName: 'invoice.pdf',
+    fileSize: 1024,
+    mimeType: 'application/pdf',
+    mode: __1.ProbeScanMode.SYNC,
+    startedAt: new Date(),
+    finishedAt: new Date(),
+    costUnits: 3,
+};
+const _historyItem = {
+    scanId: 's1',
+    fileName: 'invoice.pdf',
+    fileSize: 1024,
+    mimeType: 'application/pdf',
+    verdict: __1.ProbeScanVerdict.INFECTED,
+    viruses: ['Eicar-Test-Signature'],
+    mode: __1.ProbeScanMode.ASYNC,
+    status: __1.ProbeScanStatus.DONE,
+    context: { applicationFileId: 'af1' },
+    startedAt: new Date(),
+    finishedAt: new Date(),
+    costUnits: 1,
+    createdAt: new Date(),
+};
+const _scanSyncData = {
+    scanId: 's1',
+    verdict: __1.ProbeScanVerdict.CLEAN,
+    viruses: [],
+    costUnits: 3,
+};
+const _scanAsyncData = { scanId: 's1', status: __1.ProbeScanStatus.QUEUED };
+const _webhook = {
+    id: 'w1',
+    callbackUrl: 'https://example.com/hook',
+    secret: 'shh',
+    active: true,
+    createdAt: new Date(),
+};
+const _webhookCreated = _webhook;
+const _updateBody = { active: false };
+const _updateBody2 = { callbackUrl: 'https://example.com/hook2' };
+const _deliveryPayload = {
+    scanId: 's1',
+    context: null,
+    verdict: __1.ProbeScanVerdict.INFECTED,
+    viruses: ['Eicar-Test-Signature'],
+    costUnits: 5,
+};
+const _deliveryRecord = {
+    id: 'd1',
+    webhookId: 'w1',
+    scanId: 's1',
+    url: 'https://example.com/hook',
+    statusCode: 200,
+    success: true,
+    attemptedAt: new Date(),
+    error: null,
+    createdAt: new Date(),
+};
+const _deliveryRecordAdHoc = { ..._deliveryRecord, webhookId: null };
+const _usage = { used: 10, limit: 1000, remaining: 990 };
+const _usageUnlimited = { used: 10, limit: -1, remaining: -1 };
+const _asyncCost = (0, utils_1.estimateProbeScanCost)(5 * 1024 * 1024, __1.ProbeScanMode.ASYNC);
+const _syncCost = (0, utils_1.estimateProbeScanCost)(5 * 1024 * 1024, __1.ProbeScanMode.SYNC);
+if (_asyncCost >= _syncCost) {
+    throw new Error('estimateProbeScanCost: ASYNC must cost strictly less than SYNC');
+}
+void _verdicts;
+void _modes;
+void _statuses;
+void _scanDetail;
+void _historyItem;
+void _scanSyncData;
+void _scanAsyncData;
+void _webhook;
+void _webhookCreated;
+void _updateBody;
+void _updateBody2;
+void _deliveryPayload;
+void _deliveryRecord;
+void _deliveryRecordAdHoc;
+void _usage;
+void _usageUnlimited;
+//# sourceMappingURL=probe.dto.test.js.map

package/dist/types/tests/probe.dto.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.dto.test.js","sourceRoot":"","sources":["../../../src/types/tests/probe.dto.test.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -4,3 +4,5 @@ export * from './shape.utils';
 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/dist/utils/index.js

@@ -20,4 +20,6 @@ __exportStar(require("./shape.utils"), exports);
 __exportStar(require("./icons.utils"), exports);
 __exportStar(require("./enum.utils"), exports);
 __exportStar(require("./extraction-webhook.utils"), exports);
+__exportStar(require("./probe-webhook-signature.utils"), exports);
+__exportStar(require("./probe-scan-cost.utils"), exports);
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,gDAA8B;AAC9B,gDAA8B;AAC9B,gDAA8B;AAC9B,+CAA6B;AAC7B,6DAA2C"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,gDAA8B;AAC9B,gDAA8B;AAC9B,gDAA8B;AAC9B,+CAA6B;AAC7B,6DAA2C;AAC3C,kEAAgD;AAChD,0DAAwC"}

package/dist/utils/probe-scan-cost.utils.d.ts

@@ -0,0 +1,5 @@
+import { ProbeScanMode } from '../types';
+export declare const PROBE_SCAN_COST_BASE = 1;
+export declare const PROBE_SCAN_COST_K_MB = 1;
+export declare const PROBE_SCAN_COST_MODE_WEIGHT: Record<ProbeScanMode, number>;
+export declare const estimateProbeScanCost: (sizeOctet: number, mode: ProbeScanMode | 'sync' | 'async') => number;

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/dist/utils/probe-webhook-signature.utils.d.ts

@@ -0,0 +1,8 @@
+/// <reference types="node" />
+/// <reference types="node" />
+export interface VerifyProbeWebhookSignatureInput {
+    rawBody: string | Buffer;
+    signatureHeader: string | undefined;
+    secret: string;
+}
+export declare function verifyProbeWebhookSignature(input: VerifyProbeWebhookSignatureInput): boolean;

package/dist/utils/probe-webhook-signature.utils.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyProbeWebhookSignature = void 0;
+function verifyProbeWebhookSignature(input) {
+    if (!input.signatureHeader || !input.secret)
+        return false;
+    const crypto = require('crypto');
+    const computed = crypto
+        .createHmac('sha256', input.secret)
+        .update(input.rawBody)
+        .digest('hex');
+    if (input.signatureHeader.length !== computed.length)
+        return false;
+    try {
+        return crypto.timingSafeEqual(Buffer.from(input.signatureHeader, 'hex'), Buffer.from(computed, 'hex'));
+    }
+    catch {
+        return false;
+    }
+}
+exports.verifyProbeWebhookSignature = verifyProbeWebhookSignature;
+//# sourceMappingURL=probe-webhook-signature.utils.js.map

package/dist/utils/probe-webhook-signature.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe-webhook-signature.utils.js","sourceRoot":"","sources":["../../src/utils/probe-webhook-signature.utils.ts"],"names":[],"mappings":";;;AAiCA,SAAgB,2BAA2B,CAAC,KAAuC;IACjF,IAAI,CAAC,KAAK,CAAC,eAAe,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAG1D,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,QAAQ,GAAW,MAAM;SAC5B,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC;SAClC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC;SACrB,MAAM,CAAC,KAAK,CAAC,CAAC;IAEjB,IAAI,KAAK,CAAC,eAAe,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAEnE,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,eAAe,CAC3B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,CAAC,EACzC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,CAC7B,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QAGP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAtBD,kEAsBC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abyss-project/tools",
-  "version": "2.1.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

@@ -54,3 +54,11 @@ export * from './extraction-plan-preset.api';
 
 // Monitor (liveness)
 export * from './monitor.api';
+
+// Probe (antivirus scanning)
+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-scan.api.test.ts

@@ -0,0 +1,21 @@
+// Type-level compile test for the probe-scan api surface.
+// No jest runner in this SDK package; compile guard only (mirrors this
+// package's own extraction-plan-preset.api.test.ts).
+// Run: npx tsc --noEmit (from packages/abyss_tools_core), or `npm run build`.
+
+import * as api from './probe-scan.api';
+
+// All five functions must be exported with these exact signatures.
+const _scan: typeof api.scan = api.scan;
+const _scanSync: typeof api.scanSync = api.scanSync;
+const _scanAsync: typeof api.scanAsync = api.scanAsync;
+const _getScan: typeof api.getScan = api.getScan;
+const _listScans: typeof api.listScans = api.listScans;
+
+void _scan;
+void _scanSync;
+void _scanAsync;
+void _getScan;
+void _listScans;
+
+export {};

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

@@ -0,0 +1,191 @@
+// ──────────────────────────────────────────────
+// AbyssProbe scan API — POST /scan (sync + async), GET /scan/:scanId (poll),
+// GET /scan (history/search). Mirrors
+// apps/api/src/api/controllers/probe-scan.controller.ts EXACTLY (see that
+// file for the full contract this client targets). AbyssProbe's controllers
+// add no extra path segment (`@Controller({ prefixPath: '/scan' })`), so
+// these calls hit `scan`/`scan/:id` directly — no `probe/` prefix.
+//
+// File-upload dual environment handling (browser `FormData`/`Blob` vs Node
+// `Buffer`/stream + the `form-data` package) mirrors this package's own
+// extraction.api.ts (`detect`/`postExtract`): AbyssProbe is meant to be
+// called from the abyss-main UI (a browser) as well as from Node services
+// (abyss-storage, external integrators). `form-data` is lazy-`require`d
+// (never statically imported) so a browser bundle never tries to resolve
+// the Node-only package.
+//
+// `authHeader`/`serializeProbeQuery` are kept LOCAL and unexported (not a
+// shared utils file) — same convention as every other extract/*.api.ts file
+// in this package (each redefines its own tiny per-call apiKey helper; see
+// extraction.api.ts / extraction-settings.api.ts / extraction-plan-preset.api.ts).
+//
+// See probe-scan.application.api.ts for the application/API-key-auth
+// counterpart of this client (`/application/:applicationId/scan...`, Phase
+// 3a) — it reuses this file's `buildScanForm` and every request/response
+// type verbatim; only the URL prefix, the extra `applicationId` argument,
+// and the auth header differ.
+// ──────────────────────────────────────────────
+
+import { AbyssToolsCore } from '..';
+import { ProbeScanMode } from '../types';
+import type {
+  IScanOptions,
+  IListScansQuery,
+  IScanResponse,
+  IScanSyncResponse,
+  IScanAsyncResponse,
+  IGetScanResponse,
+  IPaginateScanResponse,
+} from '../types';
+
+const DEFAULT_API_KEY_HEADER = 'abyss-api-key';
+
+function authHeader(apiKey?: string): Record<string, string> {
+  return apiKey ? { [DEFAULT_API_KEY_HEADER]: apiKey } : {};
+}
+
+/**
+ * Turn a request/query options object into axios `params`: drops
+ * undefined/null, ISO-stringifies `Date`s, and renames `organizationId` to
+ * the wire's `organization_id` (the one snake_case key AbyssProbe's own
+ * controllers actually expect — see probe-scope.helper.ts#readOrganizationId
+ * — every other field name is already camelCase on both sides).
+ */
+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;
+}
+
+/** Anything `sdk.probe.scan` accepts as the file to submit. */
+export type ProbeScanFileInput = Buffer | Uint8Array | NodeJS.ReadableStream | Blob;
+
+function isBrowserEnv(): boolean {
+  return typeof window !== 'undefined' && typeof FormData !== 'undefined';
+}
+
+async function loadNodeFormData(): Promise<any> {
+  // Indirect eval so bundlers (esbuild/vite/webpack) do not try to resolve
+  // the Node-only "form-data" package when this file is included in a
+  // browser bundle. The require only ever runs at runtime on Node.
+  // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+  const nodeRequire: NodeRequire = new Function('return require')();
+  return nodeRequire('form-data');
+}
+
+export interface BuiltScanForm {
+  form: unknown;
+  headers: Record<string, string>;
+}
+
+/**
+ * Exported (not just this file's own `scan` internals) so
+ * probe-scan.application.api.ts reuses this EXACT multipart-building logic
+ * (browser `FormData`/`Blob` vs Node `Buffer`/stream + lazy-required
+ * `form-data`) rather than duplicating it — the file-upload contract is
+ * identical for a personal/org caller and an application caller; only the
+ * URL/auth differ (see that file's header comment).
+ */
+export async function buildScanForm(
+  file: ProbeScanFileInput,
+  options: IScanOptions,
+): Promise<BuiltScanForm> {
+  const filename = options.filename ?? 'file';
+
+  if (isBrowserEnv()) {
+    const form = new FormData();
+    const blob =
+      file instanceof Blob ? file : new Blob([file as BlobPart], { type: options.mimeType });
+    form.append('file', blob, filename);
+    if (options.context) form.append('context', JSON.stringify(options.context));
+    if (options.callbackUrl) form.append('callbackUrl', options.callbackUrl);
+    return { form, headers: {} };
+  }
+
+  const FormDataCtor = await loadNodeFormData();
+  const form = new FormDataCtor();
+  const filePart =
+    Buffer.isBuffer(file) || file instanceof Uint8Array ? Buffer.from(file as Uint8Array) : file;
+  form.append('file', filePart, { filename, contentType: options.mimeType });
+  if (options.context) form.append('context', JSON.stringify(options.context));
+  if (options.callbackUrl) form.append('callbackUrl', options.callbackUrl);
+  const headers = typeof form.getHeaders === 'function' ? form.getHeaders() : {};
+  return { form, headers };
+}
+
+/**
+ * `POST /scan` — SYNC by default, ASYNC when `options.mode = ProbeScanMode.ASYNC`
+ * (same endpoint, query-param-selected — see the controller's doc comment).
+ * `mode` and `organizationId` travel as query params; `context`
+ * (JSON-encoded) and `callbackUrl` travel as multipart text fields alongside
+ * the file.
+ *
+ * Returns the SYNC (200, verdict inline) or ASYNC (202, `{ scanId, status:
+ * 'queued' }`) shape depending on `options.mode` — see {@link IScanResponse}.
+ * Prefer {@link scanSync} / {@link scanAsync} for a precisely-typed return
+ * instead of the union.
+ */
+export const scan = async (
+  file: ProbeScanFileInput,
+  options: IScanOptions = {},
+  apiKey?: string,
+): Promise<IScanResponse> => {
+  const { form, headers } = await buildScanForm(file, options);
+  return (
+    await AbyssToolsCore.axios.post<IScanResponse>('scan', form, {
+      params: serializeProbeQuery({ mode: options.mode, organizationId: options.organizationId }),
+      headers: { ...headers, ...authHeader(apiKey) },
+      maxBodyLength: Infinity,
+      maxContentLength: Infinity,
+    })
+  ).data;
+};
+
+/** {@link scan}, forced to `mode: sync` — HTTP 200, verdict returned inline. */
+export const scanSync = async (
+  file: ProbeScanFileInput,
+  options: Omit<IScanOptions, 'mode' | 'callbackUrl'> = {},
+  apiKey?: string,
+): Promise<IScanSyncResponse> =>
+  scan(file, { ...options, mode: ProbeScanMode.SYNC }, apiKey) as Promise<IScanSyncResponse>;
+
+/** {@link scan}, forced to `mode: async` — HTTP 202, job queued. */
+export const scanAsync = async (
+  file: ProbeScanFileInput,
+  options: Omit<IScanOptions, 'mode'> = {},
+  apiKey?: string,
+): Promise<IScanAsyncResponse> =>
+  scan(file, { ...options, mode: ProbeScanMode.ASYNC }, apiKey) as Promise<IScanAsyncResponse>;
+
+/**
+ * `GET /scan/:scanId` — poll the queued -> scanning -> done/error
+ * progression of an ASYNC scan (also answers for a SYNC scan's row). Cross-
+ * tenant guarded server-side (404, never 403) — needs no scope query param,
+ * the scanId alone determines it.
+ */
+export const getScan = async (scanId: string, apiKey?: string): Promise<IGetScanResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IGetScanResponse>(`scan/${scanId}`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+
+/**
+ * `GET /scan` — paginated scan history/search for the caller's scope
+ * (personal by default, `organizationId` for an organization scope), newest
+ * first. See {@link IListScansQuery} for the available filters.
+ */
+export const listScans = async (
+  query: IListScansQuery = {},
+  apiKey?: string,
+): Promise<IPaginateScanResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IPaginateScanResponse>('scan', {
+      params: serializeProbeQuery(query),
+      headers: authHeader(apiKey),
+    })
+  ).data;

package/src/api/probe-scan.application.api.test.ts

@@ -0,0 +1,21 @@
+// Type-level compile test for the probe-scan APPLICATION api surface.
+// No jest runner in this SDK package; compile guard only (mirrors
+// probe-scan.api.test.ts).
+// Run: npx tsc --noEmit (from packages/abyss_tools_core), or `npm run build`.
+
+import * as api from './probe-scan.application.api';
+
+// All five functions must be exported with these exact signatures.
+const _scan: typeof api.scanApplication = api.scanApplication;
+const _scanSync: typeof api.scanSyncApplication = api.scanSyncApplication;
+const _scanAsync: typeof api.scanAsyncApplication = api.scanAsyncApplication;
+const _getScan: typeof api.getScanApplication = api.getScanApplication;
+const _listScans: typeof api.listScansApplication = api.listScansApplication;
+
+void _scan;
+void _scanSync;
+void _scanAsync;
+void _getScan;
+void _listScans;
+
+export {};

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

@@ -0,0 +1,157 @@
+// ──────────────────────────────────────────────
+// AbyssProbe APPLICATION scan API — POST /application/:applicationId/scan
+// (sync + async), GET /application/:applicationId/scan/:scanId (poll),
+// GET /application/:applicationId/scan (history/search). Mirrors
+// apps/api/src/api/controllers/probe-scan-application.controller.ts EXACTLY
+// (see that file for the full contract this client targets) — the
+// application counterpart of probe-scan.api.ts, for inter-service callers
+// (abyss-storage, external integrations) authenticating with a project API
+// key instead of a personal/org session.
+//
+// Reuses probe-scan.api.ts's `buildScanForm` (same dual-environment
+// multipart handling — browser `FormData`/`Blob` vs Node `Buffer`/stream +
+// lazy-required `form-data`) and every request/response TYPE verbatim
+// (`IScanOptions`, `IListScansQuery`, `IScanResponse`, `IScanSyncResponse`,
+// `IScanAsyncResponse`, `IGetScanResponse`, `IPaginateScanResponse`) — never
+// redefined here. `organizationId` is `Omit`'d from every option/query type
+// below: unlike the personal/org route's `?organization_id=` override, an
+// application caller's scope is entirely its `:applicationId` URL segment,
+// resolved server-side by ProbeApplicationMiddleware (round-trips to
+// abyss-main) — there is no scope query param to send.
+//
+// `authHeaderApplication` is kept LOCAL and unexported, same convention as
+// the personal/org client's own `authHeader` (see probe-scan.api.ts's header
+// comment) — 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 { ProbeScanMode } from '../types';
+import type {
+  IScanOptions,
+  IListScansQuery,
+  IScanResponse,
+  IScanSyncResponse,
+  IScanAsyncResponse,
+  IGetScanResponse,
+  IPaginateScanResponse,
+} from '../types';
+import { buildScanForm } from './probe-scan.api';
+import type { ProbeScanFileInput } from './probe-scan.api';
+
+function authHeaderApplication(applicationApiKey?: string): Record<string, string> {
+  return applicationApiKey ? { [API_KEY_APPLICATION_HEADER]: applicationApiKey } : {};
+}
+
+/**
+ * Turn a request/query options object into axios `params`: drops
+ * undefined/null and ISO-stringifies `Date`s. No key-renaming here (unlike
+ * probe-scan.api.ts#serializeProbeQuery's `organizationId` -> `organization_id`
+ * rename) — an application call never carries `organizationId` (`Omit`'d
+ * from every option/query type in this file), so there is nothing to rename.
+ */
+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/scan` — SYNC by default, ASYNC when
+ * `options.mode = ProbeScanMode.ASYNC` (identical contract to {@link
+ * ../probe-scan.api.scan | the personal/org `scan`} — see that function's
+ * doc comment for the full sequence). `mode` travels as a query param;
+ * `context` (JSON-encoded) and `callbackUrl` travel as multipart text fields
+ * alongside the file.
+ *
+ * Returns the SYNC (200, verdict inline) or ASYNC (202, `{ scanId, status:
+ * 'queued' }`) shape depending on `options.mode` — see {@link IScanResponse}.
+ * Prefer {@link scanSyncApplication} / {@link scanAsyncApplication} for a
+ * precisely-typed return instead of the union.
+ */
+export const scanApplication = async (
+  applicationId: string,
+  file: ProbeScanFileInput,
+  options: Omit<IScanOptions, 'organizationId'> = {},
+  applicationApiKey?: string,
+): Promise<IScanResponse> => {
+  const { form, headers } = await buildScanForm(file, options);
+  return (
+    await AbyssToolsCore.axios.post<IScanResponse>(`application/${applicationId}/scan`, form, {
+      params: serializeProbeQuery({ mode: options.mode }),
+      headers: { ...headers, ...authHeaderApplication(applicationApiKey) },
+      maxBodyLength: Infinity,
+      maxContentLength: Infinity,
+    })
+  ).data;
+};
+
+/** {@link scanApplication}, forced to `mode: sync` — HTTP 200, verdict returned inline. */
+export const scanSyncApplication = async (
+  applicationId: string,
+  file: ProbeScanFileInput,
+  options: Omit<IScanOptions, 'organizationId' | 'mode' | 'callbackUrl'> = {},
+  applicationApiKey?: string,
+): Promise<IScanSyncResponse> =>
+  scanApplication(
+    applicationId,
+    file,
+    { ...options, mode: ProbeScanMode.SYNC },
+    applicationApiKey,
+  ) as Promise<IScanSyncResponse>;
+
+/** {@link scanApplication}, forced to `mode: async` — HTTP 202, job queued. */
+export const scanAsyncApplication = async (
+  applicationId: string,
+  file: ProbeScanFileInput,
+  options: Omit<IScanOptions, 'organizationId' | 'mode'> = {},
+  applicationApiKey?: string,
+): Promise<IScanAsyncResponse> =>
+  scanApplication(
+    applicationId,
+    file,
+    { ...options, mode: ProbeScanMode.ASYNC },
+    applicationApiKey,
+  ) as Promise<IScanAsyncResponse>;
+
+/**
+ * `GET /application/:applicationId/scan/:scanId` — poll the queued ->
+ * scanning -> done/error progression of an ASYNC scan (also answers for a
+ * SYNC scan's row). Cross-tenant guarded server-side by a direct
+ * `applicationId` column comparison (404, never 403) — needs no scope
+ * argument beyond `applicationId` itself, the scanId alone determines the
+ * rest.
+ */
+export const getScanApplication = async (
+  applicationId: string,
+  scanId: string,
+  applicationApiKey?: string,
+): Promise<IGetScanResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IGetScanResponse>(
+      `application/${applicationId}/scan/${scanId}`,
+      { headers: authHeaderApplication(applicationApiKey) },
+    )
+  ).data;
+
+/**
+ * `GET /application/:applicationId/scan` — paginated scan history/search for
+ * the calling application, newest first. Same filters as the personal/org
+ * `GET /scan` minus `organizationId` (see {@link IListScansQuery}) — the
+ * `:applicationId` URL segment is already the entire scope.
+ */
+export const listScansApplication = async (
+  applicationId: string,
+  query: Omit<IListScansQuery, 'organizationId'> = {},
+  applicationApiKey?: string,
+): Promise<IPaginateScanResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IPaginateScanResponse>(`application/${applicationId}/scan`, {
+      params: serializeProbeQuery(query),
+      headers: authHeaderApplication(applicationApiKey),
+    })
+  ).data;