@abyss-project/tools 3.0.0 → 3.2.0

package/src/api/extraction.api.ts

@@ -3,6 +3,11 @@
 //
 // Sync helper accepts an inline PDF buffer (multipart) or a storage_file_id.
 // Queue helper enqueues for async processing + webhook delivery.
+//
+// Multipart bodies are built with the global `FormData` + `Blob` — the same
+// code in a browser and on Node (>= 18, see package.json `engines`). axios
+// serializes a spec-compliant FormData on both and sets the multipart
+// boundary itself, so no content-type header is ever set by hand.
 // ──────────────────────────────────────────────
 
 import { AbyssToolsCore } from '..';
@@ -92,16 +97,9 @@ function authHeader(apiKey?: string): Record<string, string> {
   return apiKey ? { [DEFAULT_API_KEY_HEADER]: apiKey } : {};
 }
 
-async function loadFormData(): Promise<any> {
-  if (typeof FormData !== 'undefined' && typeof window !== 'undefined') {
-    return FormData;
-  }
-  // Use 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 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');
+/** The PDF bytes as a multipart file part: filename kept, `application/pdf` type. */
+function appendPdfPart(form: FormData, pdf: Buffer | Uint8Array, filename: string): void {
+  form.append('file', new Blob([new Uint8Array(pdf)], { type: 'application/pdf' }), filename);
 }
 
 function serializeParams<T extends object>(o: T): Record<string, unknown> {
@@ -119,23 +117,41 @@ function serializeParams<T extends object>(o: T): Record<string, unknown> {
  * Optional per-call extras for extract endpoints. `idempotencyKey` is a
  * Stripe-style replay key (24h window) sent as the `Idempotency-Key` header —
  * not part of the request body.
+ *
+ * The key identifies ONE request, not just the caller: the server records a
+ * fingerprint of the run it answered (route, principal, ownership scope, the
+ * document, `processing`, `mode`, plan/preset and the rest of the body).
+ *   - same key + identical request  → the recorded response is replayed;
+ *   - same key + different request  → HTTP 422 `IDEMPOTENCY_KEY_REUSED`, and
+ *     nothing is run.
+ *
+ * `extractSync` and `extractQueue` are the SAME endpoint, told apart only by
+ * `processing`, so a key used for one of them cannot be reused for the other:
+ * that is a different request and answers 422. Use one key per run.
+ *
+ * Responses cached before this behaviour shipped (API 1.10) carry no
+ * fingerprint and replay as they always did until their 24h TTL expires.
  */
 export interface ExtractCallOptions {
   idempotencyKey?: string;
 }
 
+/**
+ * `POST /extract/extract` with `processing: 'sync'`. The route still moves an
+ * async plan (an OCR pass, or more than one pass — inline or reached through
+ * `plan_preset_id`) onto the queue and answers 202 with the queue body, so the
+ * call resolves either the extraction (`extraction_id`) or the queued job
+ * (`job_id`); narrow on `'job_id' in response.data`.
+ */
 export const extractSync = async (
   body: IExtractBody,
   scope: IExtractionContentScopeQuery = {},
   apiKey?: string,
   opts: ExtractCallOptions = {},
-): Promise<IExtractSyncResponse> => {
-  return postExtract(
-    { ...body, processing: 'sync' },
-    scope,
-    apiKey,
-    opts,
-  ) as Promise<IExtractSyncResponse>;
+): Promise<IExtractSyncResponse | IExtractQueueResponse> => {
+  return postExtract({ ...body, processing: 'sync' }, scope, apiKey, opts) as Promise<
+    IExtractSyncResponse | IExtractQueueResponse
+  >;
 };
 
 export const extractQueue = async (
@@ -164,54 +180,11 @@ const postExtract = async (
   }
   const params = serializeParams(scope);
   if (body.pdf) {
-    const isBrowser = typeof window !== 'undefined' && typeof FormData !== 'undefined';
-    const filename = body.pdf_filename ?? 'document.pdf';
-    if (isBrowser) {
-      const form = new FormData();
-      const blob = new Blob([body.pdf as Uint8Array], { type: 'application/pdf' });
-      form.append('file', blob, filename);
-      appendIf(form, 'mode', body.mode);
-      if (body.hint) form.append('hint', JSON.stringify(body.hint));
-      appendIf(form, 'template_id', body.template_id);
-      if (body.template) form.append('template', JSON.stringify(body.template));
-      appendIf(form, 'user_external_id', body.user_external_id);
-      if (body.user_metadata) form.append('user_metadata', JSON.stringify(body.user_metadata));
-      if (typeof body.archive === 'boolean') form.append('archive', String(body.archive));
-      if (typeof body.force === 'boolean') form.append('force', String(body.force));
-      if (body.processing) form.append('processing', body.processing);
-      return (
-        await AbyssToolsCore.axios.post(`extract/extract`, form, {
-          params,
-          headers: { ...authHeader(apiKey), ...extraHeaders },
-          maxBodyLength: Infinity,
-          maxContentLength: Infinity,
-        })
-      ).data;
-    }
-    const FormDataCtor = await loadFormData();
-    const form = new FormDataCtor();
-    const buf = Buffer.isBuffer(body.pdf) ? body.pdf : Buffer.from(body.pdf);
-    form.append('file', buf, {
-      filename,
-      contentType: 'application/pdf',
-    });
-    appendIf(form, 'mode', body.mode);
-    if (body.hint) form.append('hint', JSON.stringify(body.hint));
-    appendIf(form, 'template_id', body.template_id);
-    if (body.template) form.append('template', JSON.stringify(body.template));
-    appendIf(form, 'user_external_id', body.user_external_id);
-    if (body.user_metadata) form.append('user_metadata', JSON.stringify(body.user_metadata));
-    if (typeof body.archive === 'boolean') form.append('archive', String(body.archive));
-    if (typeof body.force === 'boolean') form.append('force', String(body.force));
-    if (body.processing) form.append('processing', body.processing);
+    const form = buildExtractMultipart(body);
     return (
       await AbyssToolsCore.axios.post(`extract/extract`, form, {
         params,
-        headers: {
-          ...(typeof form.getHeaders === 'function' ? form.getHeaders() : {}),
-          ...authHeader(apiKey),
-          ...extraHeaders,
-        },
+        headers: { ...authHeader(apiKey), ...extraHeaders },
         maxBodyLength: Infinity,
         maxContentLength: Infinity,
       })
@@ -228,11 +201,54 @@ const postExtract = async (
   ).data;
 };
 
-function appendIf(form: any, key: string, value: unknown): void {
+function appendIf(form: FormData, key: string, value: unknown): void {
   if (value === undefined || value === null) return;
   form.append(key, String(value));
 }
 
+/** Append the shared extract text fields (all optional) onto a multipart form. */
+function appendExtractFields(form: FormData, body: IExtractBody): void {
+  appendIf(form, 'mode', body.mode);
+  if (body.hint) form.append('hint', JSON.stringify(body.hint));
+  appendIf(form, 'template_id', body.template_id);
+  if (body.template) form.append('template', JSON.stringify(body.template));
+  appendIf(form, 'user_external_id', body.user_external_id);
+  if (body.user_metadata) form.append('user_metadata', JSON.stringify(body.user_metadata));
+  if (typeof body.archive === 'boolean') form.append('archive', String(body.archive));
+  if (typeof body.force === 'boolean') form.append('force', String(body.force));
+  if (body.processing) form.append('processing', body.processing);
+  if (body.plan) form.append('plan', JSON.stringify(body.plan));
+  appendIf(form, 'plan_preset_id', body.plan_preset_id);
+  // Wire name read by the API's parseExtractRequest ('true' / 'false').
+  if (typeof body.improvementConsent === 'boolean') {
+    form.append('improvement_consent', String(body.improvementConsent));
+  }
+}
+
+/**
+ * Build the multipart form for an extract upload, shared by the personal and
+ * application extract clients: the PDF as the `file` part (filename from
+ * `body.pdf_filename`, default `document.pdf`) plus the extract text fields.
+ * Scope params + auth headers are added by the caller; axios sets the
+ * multipart content type. Requires `body.pdf` to be set.
+ */
+export function buildExtractMultipart(body: IExtractBody): FormData {
+  const pdf = body.pdf;
+  if (!pdf) {
+    // Precondition: only the multipart-upload path calls this. `postExtract`
+    // guards on `body.pdf` itself and falls back to a JSON body otherwise;
+    // the application client (extraction.application.api.ts) has no JSON
+    // fallback and relies entirely on this throw, since its narrower
+    // `IExtractApplicationBody` type requires `pdf` in the first place
+    // (#581). Enforced here so the helper is self-contained either way.
+    throw new Error('buildExtractMultipart requires body.pdf');
+  }
+  const form = new FormData();
+  appendPdfPart(form, pdf, body.pdf_filename ?? 'document.pdf');
+  appendExtractFields(form, body);
+  return form;
+}
+
 export const extractBulk = async (
   body: IExtractBulkBody,
   scope: IExtractionContentScopeQuery = {},
@@ -253,29 +269,11 @@ export const detect = async (
   pdfFilename = 'document.pdf',
   apiKey?: string,
 ): Promise<IDetectResponse> => {
-  const isBrowser = typeof window !== 'undefined' && typeof FormData !== 'undefined';
-  if (isBrowser) {
-    const form = new FormData();
-    const blob = new Blob([pdf as Uint8Array], { type: 'application/pdf' });
-    form.append('file', blob, pdfFilename);
-    return (
-      await AbyssToolsCore.axios.post<IDetectResponse>(`extract/detect`, form, {
-        headers: authHeader(apiKey),
-        maxBodyLength: Infinity,
-        maxContentLength: Infinity,
-      })
-    ).data;
-  }
-  const FormDataCtor = await loadFormData();
-  const form = new FormDataCtor();
-  const buf = Buffer.isBuffer(pdf) ? pdf : Buffer.from(pdf);
-  form.append('file', buf, { filename: pdfFilename, contentType: 'application/pdf' });
+  const form = new FormData();
+  appendPdfPart(form, pdf, pdfFilename);
   return (
     await AbyssToolsCore.axios.post<IDetectResponse>(`extract/detect`, form, {
-      headers: {
-        ...(typeof form.getHeaders === 'function' ? form.getHeaders() : {}),
-        ...authHeader(apiKey),
-      },
+      headers: authHeader(apiKey),
       maxBodyLength: Infinity,
       maxContentLength: Infinity,
     })

package/src/api/extraction.application.api.test.ts

@@ -0,0 +1,55 @@
+// Type-level compile test for the APPLICATION extract client (#581).
+// No jest runner in this SDK package; compile guard only (mirrors
+// probe-scan.application.api.test.ts). Run: npx tsc --noEmit, or `npm run build`.
+
+import * as api from './extraction.application.api';
+import type { IExtractApplicationBody } from '../types';
+
+const _run: typeof api.runExtractionApplication = api.runExtractionApplication;
+void _run;
+
+type Body = Parameters<typeof api.runExtractionApplication>[1];
+declare const pdf: Buffer;
+
+// What the route accepts: a PDF, mode auto|hint, and the optional fields.
+const _minimal: Body = { pdf, mode: 'auto' };
+const _full: Body = {
+  pdf,
+  mode: 'hint',
+  hint: { bank: 'bnp' },
+  pdf_filename: 'invoice.pdf',
+  user_external_id: 'u-1',
+  user_metadata: { a: 1 },
+  archive: true,
+  force: false,
+  improvementConsent: true,
+};
+const _named: IExtractApplicationBody = _minimal;
+void _minimal;
+void _full;
+void _named;
+
+// What the route refuses with a 4xx must not compile.
+// @ts-expect-error the route only accepts a multipart PDF
+const _noPdf: Body = { mode: 'auto' };
+// @ts-expect-error storage_file_id is refused by the application route
+const _storage: Body = { pdf, mode: 'auto', storage_file_id: 'f' };
+// @ts-expect-error template_id is refused by the application route
+const _templateId: Body = { pdf, mode: 'auto', template_id: 't' };
+// @ts-expect-error template is refused by the application route
+const _template: Body = { pdf, mode: 'auto', template: {} };
+// @ts-expect-error plan_preset_id is refused by the application route
+const _preset: Body = { pdf, mode: 'auto', plan_preset_id: 'p' };
+// @ts-expect-error mode template is refused by the application route
+const _modeTemplate: Body = { pdf, mode: 'template' };
+// @ts-expect-error the application route is synchronous only
+const _processing: Body = { pdf, mode: 'auto', processing: 'queue' };
+void _noPdf;
+void _storage;
+void _templateId;
+void _template;
+void _preset;
+void _modeTemplate;
+void _processing;
+
+export {};

package/src/api/extraction.application.api.ts

@@ -0,0 +1,73 @@
+// ──────────────────────────────────────────────
+// AbyssExtract APPLICATION extract API — POST
+// /extract/application/:applicationId/extract. Mirrors
+// apps/api/src/api/controllers/extraction-extract-application.controller.ts
+// EXACTLY — the application counterpart of extraction.api.ts's `extractSync`,
+// for inter-service callers (e.g. AbyssBanking) authenticating with a project
+// API key instead of a personal/org session.
+//
+// Reuses extraction.api.ts's `buildExtractMultipart` (the same global
+// `FormData` + `Blob` multipart body as the personal client) and the
+// response TYPE verbatim (`IExtractSyncResponse`) — never redefined here.
+// The request body is `IExtractApplicationBody`, a narrower type than the
+// personal client's `IExtractBody`: it types exactly what this route accepts
+// (#581) — see extraction.request.ts. There is NO scope query param: unlike
+// the personal/org route's `?organization_id=`, an application caller's scope
+// is entirely its `:applicationId` URL segment, resolved server-side by
+// ApplicationMiddleware (round-trips to abyss-main).
+//
+// `authHeaderApplication` is kept LOCAL and unexported, same convention as the
+// personal client's own `authHeader` — it sends `API_KEY_APPLICATION_HEADER`
+// (`abyss-api-key-application`) instead of the personal `abyss-api-key`.
+//
+// The endpoint is SYNCHRONOUS (the machine caller gets the extraction inline —
+// no queue), so the return is always the `IExtractSyncResponse` shape.
+// ──────────────────────────────────────────────
+
+import { AbyssToolsCore, API_KEY_APPLICATION_HEADER } from '..';
+import type { IExtractApplicationBody } from '../types';
+import type { IExtractSyncResponse } from '../types';
+import { buildExtractMultipart, ExtractCallOptions } from './extraction.api';
+
+function authHeaderApplication(applicationApiKey?: string): Record<string, string> {
+  return applicationApiKey ? { [API_KEY_APPLICATION_HEADER]: applicationApiKey } : {};
+}
+
+/**
+ * `POST /extract/application/:applicationId/extract` — run one synchronous
+ * extraction OWNED by `applicationId` and BILLED to its resolved owning
+ * organization. The route accepts only a multipart PDF upload: send
+ * `body.pdf`, with `body.mode` `auto` or `hint`; `body.plan` (inline, single
+ * pass, no OCR, no template pass) and `body.improvementConsent` travel as
+ * multipart fields. The route refuses `storage_file_id`, `plan_preset_id`,
+ * `template_id` and `template` with a 4xx. A body without `pdf` never reaches
+ * the route at all: `IExtractApplicationBody` requires it, and this client's
+ * `buildExtractMultipart` throws locally ("buildExtractMultipart requires
+ * body.pdf") before any request is sent (#581). The memory watchdog may still
+ * answer 503 on a well-formed call, before the route reads the body.
+ * `options` forwards a Stripe-style
+ * `Idempotency-Key` header (24h replay window) when set — replayed only for
+ * the IDENTICAL request; the same key sent with another document or another
+ * body answers 422 `IDEMPOTENCY_KEY_REUSED` (see `ExtractCallOptions`).
+ */
+export const runExtractionApplication = async (
+  applicationId: string,
+  body: IExtractApplicationBody,
+  options: ExtractCallOptions = {},
+  applicationApiKey?: string,
+): Promise<IExtractSyncResponse> => {
+  const extraHeaders: Record<string, string> = {};
+  if (options.idempotencyKey) {
+    extraHeaders['Idempotency-Key'] = options.idempotencyKey;
+  }
+  const url = `extract/application/${applicationId}/extract`;
+
+  const form = buildExtractMultipart(body);
+  return (
+    await AbyssToolsCore.axios.post<IExtractSyncResponse>(url, form, {
+      headers: { ...authHeaderApplication(applicationApiKey), ...extraHeaders },
+      maxBodyLength: Infinity,
+      maxContentLength: Infinity,
+    })
+  ).data;
+};

package/src/api/index.ts

@@ -46,6 +46,7 @@ export * from './tag.api';
 
 // Extraction
 export * from './extraction.api';
+export * from './extraction.application.api';
 export * from './extraction-settings.api';
 export * from './extraction-plan-preset.api';
 

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

@@ -18,4 +18,30 @@ void _scanAsync;
 void _getScan;
 void _listScans;
 
+// The accepted file inputs (#519). A Blob covers the browser's File and Node's
+// file-backed fs.openAsBlob(path); raw bytes are accepted as a Uint8Array (and
+// therefore a Buffer). A Node stream is refused AT COMPILE TIME: the body is a
+// spec FormData, whose parts need a known length, so honouring a stream would
+// mean buffering up to 2 GiB in memory.
+declare const blob: Blob;
+declare const bytes: Uint8Array;
+declare const buffer: Buffer;
+declare const stream: NodeJS.ReadableStream;
+
+const _fromBlob: api.ProbeScanFileInput = blob;
+const _fromBytes: api.ProbeScanFileInput = bytes;
+const _fromBuffer: api.ProbeScanFileInput = buffer;
+// @ts-expect-error a Readable stream is not an accepted scan input since 2.12.0
+const _fromStream: api.ProbeScanFileInput = stream;
+
+void _fromBlob;
+void _fromBytes;
+void _fromBuffer;
+void _fromStream;
+
+// buildScanForm returns the FormData alone — axios sets the multipart
+// content type and boundary, so there are no headers to merge in.
+const _form: FormData = api.buildScanForm(blob, { filename: 'f.bin' });
+void _form;
+
 export {};

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

@@ -6,13 +6,20 @@
 // 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.
+// 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
@@ -61,60 +68,65 @@ function serializeProbeQuery<T extends object>(query: T): Record<string, unknown
   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');
-}
+/**
+ * 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;
 
-export interface BuiltScanForm {
-  form: unknown;
-  headers: Record<string, string>;
+/**
+ * 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
- * (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).
+ * 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 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 });
+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);
-  const headers = typeof form.getHeaders === 'function' ? form.getHeaders() : {};
-  return { form, headers };
+  return form;
 }
 
 /**
@@ -134,11 +146,11 @@ export const scan = async (
   options: IScanOptions = {},
   apiKey?: string,
 ): Promise<IScanResponse> => {
-  const { form, headers } = await buildScanForm(file, options);
+  const form = buildScanForm(file, options);
   return (
     await AbyssToolsCore.axios.post<IScanResponse>('scan', form, {
       params: serializeProbeQuery({ mode: options.mode, organizationId: options.organizationId }),
-      headers: { ...headers, ...authHeader(apiKey) },
+      headers: authHeader(apiKey),
       maxBodyLength: Infinity,
       maxContentLength: Infinity,
     })

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

@@ -18,4 +18,18 @@ 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 {};

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

@@ -8,9 +8,9 @@
 // (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
+// Reuses probe-scan.api.ts's `buildScanForm` (the global `FormData` + `Blob`,
+// one code path for the browser and for Node — see that file's header for what
+// a Node caller passes) 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
@@ -79,11 +79,11 @@ export const scanApplication = async (
   options: Omit<IScanOptions, 'organizationId'> = {},
   applicationApiKey?: string,
 ): Promise<IScanResponse> => {
-  const { form, headers } = await buildScanForm(file, options);
+  const form = buildScanForm(file, options);
   return (
     await AbyssToolsCore.axios.post<IScanResponse>(`application/${applicationId}/scan`, form, {
       params: serializeProbeQuery({ mode: options.mode }),
-      headers: { ...headers, ...authHeaderApplication(applicationApiKey) },
+      headers: authHeaderApplication(applicationApiKey),
       maxBodyLength: Infinity,
       maxContentLength: Infinity,
     })

package/src/api/retrospective.api.ts

@@ -23,7 +23,9 @@ export const getRetrospective = async (
   params: IGetRetrospectiveParams,
 ): Promise<IGetRetrospectiveResponse> => {
   return (
-    await AbyssToolsCore.axios.get<IGetRetrospectiveResponse>(`retrospective/${params.retrospectiveId}`)
+    await AbyssToolsCore.axios.get<IGetRetrospectiveResponse>(
+      `retrospective/${params.retrospectiveId}`,
+    )
   ).data;
 };
 
@@ -52,7 +54,8 @@ export const paginateRetrospective = async (
 export const createRetrospective = async (
   body: ICreateRetrospectiveBody,
 ): Promise<ICreateRetrospectiveResponse> => {
-  return (await AbyssToolsCore.axios.post<ICreateRetrospectiveResponse>(`retrospective`, body)).data;
+  return (await AbyssToolsCore.axios.post<ICreateRetrospectiveResponse>(`retrospective`, body))
+    .data;
 };
 
 export const createForOrganizationRetrospective = async (
@@ -113,9 +116,9 @@ export const transferRetrospective = async (
   ).data;
 };
 
-export const countOrganizationRetrospective = async (
-  params: { organizationId: string },
-): Promise<ICountOrganizationResponse> => {
+export const countOrganizationRetrospective = async (params: {
+  organizationId: string;
+}): Promise<ICountOrganizationResponse> => {
   return (
     await AbyssToolsCore.axios.get<ICountOrganizationResponse>(
       `retrospective/organization/${params.organizationId}/count`,