@abyss-project/probe 2.0.0 → 3.0.0

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

@@ -1,203 +1,203 @@
-// ──────────────────────────────────────────────
-// 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.
-//
-// Multipart bodies are built with the global `FormData` + `Blob` — the same
-// code in a browser and on Node, mirroring this package's own
-// extraction.api.ts. axios serializes a spec-compliant FormData on both and
-// sets the multipart boundary itself, so no content-type header is ever set by
-// hand. AbyssProbe is called from the abyss-main UI (a browser) as well as
-// from Node services (abyss-storage, external integrators).
-//
-// A Node caller holding a file ON DISK passes `await fs.openAsBlob(path)`,
-// which requires Node >= 19.8 — hence `engines.node` in package.json.
-// `FormData` and `Blob` alone would only need Node 18, but openAsBlob is this
-// client's documented way to send a file, and promising 18.x only to fail at
-// runtime is worse than refusing the install. A caller that already holds its
-// bytes passes a `Buffer`/`Uint8Array` and has no such constraint (see
-// {@link ProbeScanFileInput}).
-//
-// `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 { AbyssProbeCore } 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.
- *
- * `Blob` covers the browser's `File` (a `Blob` subclass) and, on Node, a
- * FILE-BACKED blob from `await fs.openAsBlob(path)` (Node >= 19.8): its bytes
- * are read from disk as the request body is written, so scanning a file at the
- * 2 GiB ceiling never holds the file in memory. `Uint8Array` (and therefore
- * `Buffer`) is for a caller that already holds the bytes.
- *
- * A Node `Readable` is NOT accepted. The body is a spec `FormData`, whose
- * parts must have a known length, so a stream could only be honoured by
- * buffering it whole — precisely what a 2 GiB scan must not do. A caller
- * holding a path passes `await fs.openAsBlob(path)` instead.
- */
-export type ProbeScanFileInput = Blob | Uint8Array;
-
-/**
- * The file as one multipart part.
- *
- * A `Blob` is used as-is, keeping whatever streaming its implementation gives
- * (a file-backed `openAsBlob` reads from disk lazily); raw bytes are wrapped
- * in a `Blob` carrying `mimeType`. `Buffer` is never named here — this code
- * also runs in a browser bundle, where the global does not exist — and
- * `Buffer` is a `Uint8Array` subclass, so the check below already covers it.
- *
- * Anything else is refused with an actionable message. Until 2.12.0 the same
- * call died on Node with `ReferenceError: require is not defined`, thrown by a
- * `form-data` loader before any request was made (#519): it named neither the
- * cause nor the fix.
- */
-function toScanFilePart(file: ProbeScanFileInput, mimeType?: string): Blob {
-  if (file instanceof Blob) return file;
-  if (file instanceof Uint8Array) return new Blob([new Uint8Array(file)], { type: mimeType ?? '' });
-
-  const isStream = typeof (file as { pipe?: unknown } | null | undefined)?.pipe === 'function';
-  throw new TypeError(
-    `A probe scan file must be a Blob (a browser File, or fs.openAsBlob(path) on Node), ` +
-      `a Buffer or a Uint8Array — received ${isStream ? 'a stream' : typeof file}. ` +
-      `On Node, pass \`await fs.openAsBlob(path)\`: a file-backed Blob is streamed from ` +
-      `disk, so the file is never buffered in memory.`,
-  );
-}
-
-/**
- * Exported (not just this file's own `scan` internals) so
- * probe-scan.application.api.ts reuses this EXACT multipart-building logic
- * 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).
- *
- * Returns the form alone: axios sets the multipart content type, boundary
- * included, so there is no header for the caller to merge in.
- */
-export function buildScanForm(file: ProbeScanFileInput, options: IScanOptions): FormData {
-  const form = new FormData();
-  form.append('file', toScanFilePart(file, options.mimeType), options.filename ?? 'file');
-  if (options.context) form.append('context', JSON.stringify(options.context));
-  if (options.callbackUrl) form.append('callbackUrl', options.callbackUrl);
-  return form;
-}
-
-/**
- * `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 = buildScanForm(file, options);
-  return (
-    await AbyssProbeCore.axios.post<IScanResponse>('scan', form, {
-      params: serializeProbeQuery({ mode: options.mode, organizationId: options.organizationId }),
-      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 AbyssProbeCore.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 AbyssProbeCore.axios.get<IPaginateScanResponse>('scan', {
-      params: serializeProbeQuery(query),
-      headers: authHeader(apiKey),
-    })
-  ).data;
+// ──────────────────────────────────────────────
+// 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.
+//
+// Multipart bodies are built with the global `FormData` + `Blob` — the same
+// code in a browser and on Node, mirroring this package's own
+// extraction.api.ts. axios serializes a spec-compliant FormData on both and
+// sets the multipart boundary itself, so no content-type header is ever set by
+// hand. AbyssProbe is called from the abyss-main UI (a browser) as well as
+// from Node services (abyss-storage, external integrators).
+//
+// A Node caller holding a file ON DISK passes `await fs.openAsBlob(path)`,
+// which requires Node >= 19.8 — hence `engines.node` in package.json.
+// `FormData` and `Blob` alone would only need Node 18, but openAsBlob is this
+// client's documented way to send a file, and promising 18.x only to fail at
+// runtime is worse than refusing the install. A caller that already holds its
+// bytes passes a `Buffer`/`Uint8Array` and has no such constraint (see
+// {@link ProbeScanFileInput}).
+//
+// `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 { AbyssProbeCore } 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.
+ *
+ * `Blob` covers the browser's `File` (a `Blob` subclass) and, on Node, a
+ * FILE-BACKED blob from `await fs.openAsBlob(path)` (Node >= 19.8): its bytes
+ * are read from disk as the request body is written, so scanning a file at the
+ * 2 GiB ceiling never holds the file in memory. `Uint8Array` (and therefore
+ * `Buffer`) is for a caller that already holds the bytes.
+ *
+ * A Node `Readable` is NOT accepted. The body is a spec `FormData`, whose
+ * parts must have a known length, so a stream could only be honoured by
+ * buffering it whole — precisely what a 2 GiB scan must not do. A caller
+ * holding a path passes `await fs.openAsBlob(path)` instead.
+ */
+export type ProbeScanFileInput = Blob | Uint8Array;
+
+/**
+ * The file as one multipart part.
+ *
+ * A `Blob` is used as-is, keeping whatever streaming its implementation gives
+ * (a file-backed `openAsBlob` reads from disk lazily); raw bytes are wrapped
+ * in a `Blob` carrying `mimeType`. `Buffer` is never named here — this code
+ * also runs in a browser bundle, where the global does not exist — and
+ * `Buffer` is a `Uint8Array` subclass, so the check below already covers it.
+ *
+ * Anything else is refused with an actionable message. Until 2.12.0 the same
+ * call died on Node with `ReferenceError: require is not defined`, thrown by a
+ * `form-data` loader before any request was made (#519): it named neither the
+ * cause nor the fix.
+ */
+function toScanFilePart(file: ProbeScanFileInput, mimeType?: string): Blob {
+  if (file instanceof Blob) return file;
+  if (file instanceof Uint8Array) return new Blob([new Uint8Array(file)], { type: mimeType ?? '' });
+
+  const isStream = typeof (file as { pipe?: unknown } | null | undefined)?.pipe === 'function';
+  throw new TypeError(
+    `A probe scan file must be a Blob (a browser File, or fs.openAsBlob(path) on Node), ` +
+      `a Buffer or a Uint8Array — received ${isStream ? 'a stream' : typeof file}. ` +
+      `On Node, pass \`await fs.openAsBlob(path)\`: a file-backed Blob is streamed from ` +
+      `disk, so the file is never buffered in memory.`,
+  );
+}
+
+/**
+ * Exported (not just this file's own `scan` internals) so
+ * probe-scan.application.api.ts reuses this EXACT multipart-building logic
+ * 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).
+ *
+ * Returns the form alone: axios sets the multipart content type, boundary
+ * included, so there is no header for the caller to merge in.
+ */
+export function buildScanForm(file: ProbeScanFileInput, options: IScanOptions): FormData {
+  const form = new FormData();
+  form.append('file', toScanFilePart(file, options.mimeType), options.filename ?? 'file');
+  if (options.context) form.append('context', JSON.stringify(options.context));
+  if (options.callbackUrl) form.append('callbackUrl', options.callbackUrl);
+  return form;
+}
+
+/**
+ * `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 = buildScanForm(file, options);
+  return (
+    await AbyssProbeCore.axios.post<IScanResponse>('scan', form, {
+      params: serializeProbeQuery({ mode: options.mode, organizationId: options.organizationId }),
+      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 AbyssProbeCore.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 AbyssProbeCore.axios.get<IPaginateScanResponse>('scan', {
+      params: serializeProbeQuery(query),
+      headers: authHeader(apiKey),
+    })
+  ).data;

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

@@ -1,35 +1,35 @@
-// 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_probe_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;
-
-// The application client takes the SAME file input as the personal one (it
-// reuses buildScanForm verbatim) — abyss-storage, its main caller, hands over
-// `await fs.openAsBlob(path)`. A stream is refused at compile time (#519); see
-// probe-scan.api.test.ts for the full input matrix.
-declare const blob: Blob;
-declare const stream: NodeJS.ReadableStream;
-
-const _fromBlob: Parameters<typeof api.scanSyncApplication>[1] = blob;
-// @ts-expect-error a Readable stream is not an accepted scan input since 2.12.0
-const _fromStream: Parameters<typeof api.scanSyncApplication>[1] = stream;
-
-void _fromBlob;
-void _fromStream;
-
-export {};
+// 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_probe_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;
+
+// The application client takes the SAME file input as the personal one (it
+// reuses buildScanForm verbatim) — abyss-storage, its main caller, hands over
+// `await fs.openAsBlob(path)`. A stream is refused at compile time (#519); see
+// probe-scan.api.test.ts for the full input matrix.
+declare const blob: Blob;
+declare const stream: NodeJS.ReadableStream;
+
+const _fromBlob: Parameters<typeof api.scanSyncApplication>[1] = blob;
+// @ts-expect-error a Readable stream is not an accepted scan input since 2.12.0
+const _fromStream: Parameters<typeof api.scanSyncApplication>[1] = stream;
+
+void _fromBlob;
+void _fromStream;
+
+export {};