@abyss-project/tools 3.0.0 → 3.1.0

package/src/api/board.api.ts

@@ -31,7 +31,8 @@ export const getBoard = async (params: IGetBoardParams): Promise<IGetBoardRespon
 export const getBySlugBoard = async (
   params: IGetBySlugBoardParams,
 ): Promise<IGetBySlugBoardResponse> => {
-  return (await AbyssToolsCore.axios.get<IGetBySlugBoardResponse>(`board/slug/${params.slug}`)).data;
+  return (await AbyssToolsCore.axios.get<IGetBySlugBoardResponse>(`board/slug/${params.slug}`))
+    .data;
 };
 
 export const deleteBoard = async (params: IDeleteBoardParams): Promise<IDeleteBoardResponse> => {
@@ -42,7 +43,8 @@ export const updateBoard = async (
   params: IUpdateBoardParams,
   body: IUpdateBoardBody,
 ): Promise<IUpdateBoardResponse> => {
-  return (await AbyssToolsCore.axios.put<IUpdateBoardResponse>(`board/${params.boardId}`, body)).data;
+  return (await AbyssToolsCore.axios.put<IUpdateBoardResponse>(`board/${params.boardId}`, body))
+    .data;
 };
 
 export const createBoard = async (body: ICreateBoardBody): Promise<ICreateBoardResponse> => {
@@ -54,12 +56,18 @@ export const createForOrganizationBoard = async (
   body: ICreateBoardBody,
 ): Promise<ICreateBoardResponse> => {
   return (
-    await AbyssToolsCore.axios.post<ICreateBoardResponse>(`board/organization/${params.organizationId}`, body)
+    await AbyssToolsCore.axios.post<ICreateBoardResponse>(
+      `board/organization/${params.organizationId}`,
+      body,
+    )
   ).data;
 };
 
-export const listBoard = async (query?: { sharedWithMe?: boolean }): Promise<IListBoardUserResponse> => {
-  return (await AbyssToolsCore.axios.get<IListBoardUserResponse>('board/list', { params: query })).data;
+export const listBoard = async (query?: {
+  sharedWithMe?: boolean;
+}): Promise<IListBoardUserResponse> => {
+  return (await AbyssToolsCore.axios.get<IListBoardUserResponse>('board/list', { params: query }))
+    .data;
 };
 
 export const listBoardProject = async (params: {
@@ -71,8 +79,9 @@ export const listBoardProject = async (params: {
 };
 
 export const getNextCardPreviewBoard = async (): Promise<IGetNextCardPreviewBoardResponse> => {
-  return (await AbyssToolsCore.axios.post<IGetNextCardPreviewBoardResponse>(`board/next-card-preview`))
-    .data;
+  return (
+    await AbyssToolsCore.axios.post<IGetNextCardPreviewBoardResponse>(`board/next-card-preview`)
+  ).data;
 };
 
 export const listBoardOrganization = async (
@@ -111,9 +120,9 @@ export const transferBoard = async (
   ).data;
 };
 
-export const countOrganizationBoard = async (
-  params: { organizationId: string },
-): Promise<ICountOrganizationResponse> => {
+export const countOrganizationBoard = async (params: {
+  organizationId: string;
+}): Promise<ICountOrganizationResponse> => {
   return (
     await AbyssToolsCore.axios.get<ICountOrganizationResponse>(
       `board/organization/${params.organizationId}/count`,

package/src/api/draw.api.ts

@@ -29,9 +29,12 @@ export const paginateProjectDraw = async (
   query: IPaginateDrawQuery,
 ): Promise<IPaginateDrawResponse> => {
   return (
-    await AbyssToolsCore.axios.get<IPaginateDrawResponse>(`project/${params.projectId}/draw/paginate`, {
-      params: query,
-    })
+    await AbyssToolsCore.axios.get<IPaginateDrawResponse>(
+      `project/${params.projectId}/draw/paginate`,
+      {
+        params: query,
+      },
+    )
   ).data;
 };
 
@@ -58,8 +61,12 @@ export const createForOrganizationDraw = async (
   params: ICreateForOrganizationDrawParams,
   body: ICreateDrawBody,
 ): Promise<ICreateDrawResponse> => {
-  return (await AbyssToolsCore.axios.post<ICreateDrawResponse>(`draw/organization/${params.organizationId}`, body))
-    .data;
+  return (
+    await AbyssToolsCore.axios.post<ICreateDrawResponse>(
+      `draw/organization/${params.organizationId}`,
+      body,
+    )
+  ).data;
 };
 
 export const paginateOrganizationDraw = async (
@@ -79,16 +86,13 @@ export const transferDraw = async (
   body: ITransferContentBody,
 ): Promise<ITransferDrawResponse> => {
   return (
-    await AbyssToolsCore.axios.post<ITransferDrawResponse>(
-      `draw/${params.drawId}/transfer`,
-      body,
-    )
+    await AbyssToolsCore.axios.post<ITransferDrawResponse>(`draw/${params.drawId}/transfer`, body)
   ).data;
 };
 
-export const countOrganizationDraw = async (
-  params: { organizationId: string },
-): Promise<ICountOrganizationResponse> => {
+export const countOrganizationDraw = async (params: {
+  organizationId: string;
+}): Promise<ICountOrganizationResponse> => {
   return (
     await AbyssToolsCore.axios.get<ICountOrganizationResponse>(
       `draw/organization/${params.organizationId}/count`,

package/src/api/draw.public.api.ts

@@ -15,7 +15,9 @@ export const getDrawPublic = async (
   params: IGetDrawPublicParams,
 ): Promise<IGetDrawPublicResponse> => {
   return (
-    await AbyssToolsCore.axios.get<IGetDrawPublicResponse>(`draw/public/${params.publicAccessToken}`)
+    await AbyssToolsCore.axios.get<IGetDrawPublicResponse>(
+      `draw/public/${params.publicAccessToken}`,
+    )
   ).data;
 };
 

package/src/api/extraction-plan-preset.api.ts

@@ -11,11 +11,7 @@
 // ──────────────────────────────────────────────
 
 import { AbyssToolsCore } from '..';
-import type {
-  ICreatePlanPresetBody,
-  IUpdatePlanPresetBody,
-  IListPlanPresetQuery,
-} from '../types';
+import type { ICreatePlanPresetBody, IUpdatePlanPresetBody, IListPlanPresetQuery } from '../types';
 import type {
   IListModesResponse,
   IListPlanPresetsResponse,
@@ -30,22 +26,72 @@ function authHeader(apiKey?: string): Record<string, string> {
 }
 
 export const listModes = async (apiKey?: string): Promise<IListModesResponse> =>
-  (await AbyssToolsCore.axios.get<IListModesResponse>(`extract/modes`, { headers: authHeader(apiKey) })).data;
+  (
+    await AbyssToolsCore.axios.get<IListModesResponse>(`extract/modes`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
 
-export const listExtractionPlanPresets = async (query: IListPlanPresetQuery = {}, apiKey?: string): Promise<IListPlanPresetsResponse> =>
-  (await AbyssToolsCore.axios.get<IListPlanPresetsResponse>(`extract/plans`, { params: query, headers: authHeader(apiKey) })).data;
+export const listExtractionPlanPresets = async (
+  query: IListPlanPresetQuery = {},
+  apiKey?: string,
+): Promise<IListPlanPresetsResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IListPlanPresetsResponse>(`extract/plans`, {
+      params: query,
+      headers: authHeader(apiKey),
+    })
+  ).data;
 
-export const getExtractionPlanPreset = async (id: string, apiKey?: string): Promise<IGetPlanPresetResponse> =>
-  (await AbyssToolsCore.axios.get<IGetPlanPresetResponse>(`extract/plans/${id}`, { headers: authHeader(apiKey) })).data;
+export const getExtractionPlanPreset = async (
+  id: string,
+  apiKey?: string,
+): Promise<IGetPlanPresetResponse> =>
+  (
+    await AbyssToolsCore.axios.get<IGetPlanPresetResponse>(`extract/plans/${id}`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
 
-export const createExtractionPlanPreset = async (body: ICreatePlanPresetBody, apiKey?: string): Promise<IGetPlanPresetResponse> =>
-  (await AbyssToolsCore.axios.post<IGetPlanPresetResponse>(`extract/plans`, body, { headers: authHeader(apiKey) })).data;
+export const createExtractionPlanPreset = async (
+  body: ICreatePlanPresetBody,
+  apiKey?: string,
+): Promise<IGetPlanPresetResponse> =>
+  (
+    await AbyssToolsCore.axios.post<IGetPlanPresetResponse>(`extract/plans`, body, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
 
-export const updateExtractionPlanPreset = async (id: string, body: IUpdatePlanPresetBody, apiKey?: string): Promise<IGetPlanPresetResponse> =>
-  (await AbyssToolsCore.axios.put<IGetPlanPresetResponse>(`extract/plans/${id}`, body, { headers: authHeader(apiKey) })).data;
+export const updateExtractionPlanPreset = async (
+  id: string,
+  body: IUpdatePlanPresetBody,
+  apiKey?: string,
+): Promise<IGetPlanPresetResponse> =>
+  (
+    await AbyssToolsCore.axios.put<IGetPlanPresetResponse>(`extract/plans/${id}`, body, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
 
-export const deleteExtractionPlanPreset = async (id: string, apiKey?: string): Promise<IDeletePlanPresetResponse> =>
-  (await AbyssToolsCore.axios.delete<IDeletePlanPresetResponse>(`extract/plans/${id}`, { headers: authHeader(apiKey) })).data;
+export const deleteExtractionPlanPreset = async (
+  id: string,
+  apiKey?: string,
+): Promise<IDeletePlanPresetResponse> =>
+  (
+    await AbyssToolsCore.axios.delete<IDeletePlanPresetResponse>(`extract/plans/${id}`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
 
-export const setDefaultExtractionPlanPreset = async (id: string, apiKey?: string): Promise<IGetPlanPresetResponse> =>
-  (await AbyssToolsCore.axios.post<IGetPlanPresetResponse>(`extract/plans/${id}/default`, {}, { headers: authHeader(apiKey) })).data;
+export const setDefaultExtractionPlanPreset = async (
+  id: string,
+  apiKey?: string,
+): Promise<IGetPlanPresetResponse> =>
+  (
+    await AbyssToolsCore.axios.post<IGetPlanPresetResponse>(
+      `extract/plans/${id}/default`,
+      {},
+      { headers: authHeader(apiKey) },
+    )
+  ).data;

package/src/api/extraction-settings.api.ts

@@ -9,14 +9,8 @@
 // ──────────────────────────────────────────────
 
 import { AbyssToolsCore } from '..';
-import type {
-  IGetExtractionSettingsQuery,
-  IUpsertExtractionSettingsBody,
-} from '../types';
-import type {
-  IGetExtractionSettingsResponse,
-  IUpsertExtractionSettingsResponse,
-} from '../types';
+import type { IGetExtractionSettingsQuery, IUpsertExtractionSettingsBody } from '../types';
+import type { IGetExtractionSettingsResponse, IUpsertExtractionSettingsResponse } from '../types';
 
 const DEFAULT_API_KEY_HEADER = 'abyss-api-key';
 

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([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 {};