@abyss-project/extract 0.0.0-stage → 1.0.0

package/src/api/extraction.api.ts

@@ -0,0 +1,1012 @@
+// ──────────────────────────────────────────────
+// Extraction — user-facing API.
+//
+// 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 { AbyssExtractCore } from '..';
+import {
+  IExtractBody,
+  IExtractBulkBody,
+  IDetectBulkBody,
+  IListFilesQuery,
+  IPatchFileBody,
+  IPatchExtractionBody,
+  ISearchExtractionRecordsQuery,
+  IExportExtractionQuery,
+  IAsyncExportExtractionBody,
+  IListUsageQuery,
+  ISummaryUsageQuery,
+  IUsageByConfigQuery,
+  IListWebhookDeliveriesQuery,
+  IReplayWebhookDeliveryBody,
+  IMintShareExtractionBody,
+  IToggleExtractionTrainingBody,
+} from '../types';
+import {
+  IExtractSyncResponse,
+  IExtractQueueResponse,
+  IExtractBulkResponse,
+  IDetectResponse,
+  IDetectBulkResponse,
+  IListFilesResponse,
+  IGetFileResponse,
+  IListFileExtractionsResponse,
+  IGetExtractionResponse,
+  ISearchExtractionRecordsResponse,
+  IDiffExtractionsResponse,
+  IAsyncExportResponse,
+  IGetExportJobResponse,
+  ICreateTemplateResponse,
+  IUpdateTemplateResponse,
+  IListTemplatesResponse,
+  IGetTemplateResponse,
+  IListTemplateVersionsResponse,
+  IGetTemplateWitnessUrlResponse,
+  IExtractionTemplateCollection,
+  IImportTemplateCollectionResponse,
+  IGetJobResponse,
+  ICreateFeedbackResponse,
+  IListFeedbackResponse,
+  IGetFeedbackResponse,
+  IHealthResponse,
+  IStatsResponse,
+  ISummaryUsageResponse,
+  IUsageByConfigResponse,
+  IListWebhookDeliveriesResponse,
+  IGetWebhookDeliveryResponse,
+  IGetSharedExtractionResponse,
+  IMintShareExtractionResponse,
+  IChangelogResponse,
+  IToggleExtractionTrainingResponse,
+} from '../types';
+import {
+  ICreateTemplateBody,
+  IUpdateTemplateBody,
+  IPatchTemplateMetaBody,
+  IListTemplatesQuery,
+  ISubmitFeedbackExtractionBody,
+  IPatchFeedbackBody,
+  IListFeedbackQuery,
+  IListSharedFilesQuery,
+  IPaginateExtractionWebhookQuery,
+  ICreateExtractionWebhookBody,
+  IUpdateExtractionWebhookBody,
+  IExtractionWebhookScopeQuery,
+  IExtractionContentScopeQuery,
+  IExtractionTemplateScopeQuery,
+} from '../types';
+import type {
+  IPaginateExtractionWebhookResponse,
+  IGetExtractionWebhookResponse,
+  ICreateExtractionWebhookResponse,
+  IUpdateExtractionWebhookResponse,
+  IDeleteExtractionWebhookResponse,
+  IResetSecretExtractionWebhookResponse,
+} from '../types';
+
+const DEFAULT_API_KEY_HEADER = 'abyss-api-key';
+
+function authHeader(apiKey?: string): Record<string, string> {
+  return apiKey ? { [DEFAULT_API_KEY_HEADER]: apiKey } : {};
+}
+
+/** 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> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(o as Record<string, unknown>)) {
+    if (v === undefined || v === null) continue;
+    out[k] = v instanceof Date ? v.toISOString() : v;
+  }
+  return out;
+}
+
+// ─── EXTRACT ─────────────────────────────────
+
+/**
+ * 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 | IExtractQueueResponse> => {
+  return postExtract({ ...body, processing: 'sync' }, scope, apiKey, opts) as Promise<
+    IExtractSyncResponse | IExtractQueueResponse
+  >;
+};
+
+export const extractQueue = async (
+  body: IExtractBody,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+  opts: ExtractCallOptions = {},
+): Promise<IExtractQueueResponse> => {
+  return postExtract(
+    { ...body, processing: 'queue' },
+    scope,
+    apiKey,
+    opts,
+  ) as Promise<IExtractQueueResponse>;
+};
+
+const postExtract = async (
+  body: IExtractBody,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+  opts: ExtractCallOptions = {},
+): Promise<unknown> => {
+  const extraHeaders: Record<string, string> = {};
+  if (opts.idempotencyKey) {
+    extraHeaders['Idempotency-Key'] = opts.idempotencyKey;
+  }
+  const params = serializeParams(scope);
+  if (body.pdf) {
+    const form = buildExtractMultipart(body);
+    return (
+      await AbyssExtractCore.axios.post(`extract/extract`, form, {
+        params,
+        headers: { ...authHeader(apiKey), ...extraHeaders },
+        maxBodyLength: Infinity,
+        maxContentLength: Infinity,
+      })
+    ).data;
+  }
+  // Strip `pdf` from the JSON body (only used for multipart upload above).
+  const jsonBody: Omit<IExtractBody, 'pdf'> = { ...body };
+  delete (jsonBody as { pdf?: unknown }).pdf;
+  return (
+    await AbyssExtractCore.axios.post(`extract/extract`, jsonBody, {
+      params,
+      headers: { ...authHeader(apiKey), ...extraHeaders },
+    })
+  ).data;
+};
+
+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 = {},
+  apiKey?: string,
+): Promise<IExtractBulkResponse> => {
+  return (
+    await AbyssExtractCore.axios.post<IExtractBulkResponse>(`extract/extract/bulk`, body, {
+      params: serializeParams(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+// ─── DETECT ──────────────────────────────────
+
+export const detect = async (
+  pdf: Buffer | Uint8Array,
+  pdfFilename = 'document.pdf',
+  apiKey?: string,
+): Promise<IDetectResponse> => {
+  const form = new FormData();
+  appendPdfPart(form, pdf, pdfFilename);
+  return (
+    await AbyssExtractCore.axios.post<IDetectResponse>(`extract/detect`, form, {
+      headers: authHeader(apiKey),
+      maxBodyLength: Infinity,
+      maxContentLength: Infinity,
+    })
+  ).data;
+};
+
+export const detectBulk = async (
+  body: IDetectBulkBody,
+  apiKey?: string,
+): Promise<IDetectBulkResponse> => {
+  return (
+    await AbyssExtractCore.axios.post<IDetectBulkResponse>(`extract/detect/bulk`, body, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+// ─── FILES ───────────────────────────────────
+
+export const listFiles = async (
+  query: IListFilesQuery = {},
+  apiKey?: string,
+): Promise<IListFilesResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IListFilesResponse>(`extract/files`, {
+      params: serializeParams(query),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const getFile = async (
+  fileId: string,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<IGetFileResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IGetFileResponse>(`extract/files/${fileId}`, {
+      params: serializeParams(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const listFileExtractions = async (
+  fileId: string,
+  query: { limit?: number; offset?: number } & IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<IListFileExtractionsResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IListFileExtractionsResponse>(
+      `extract/files/${fileId}/extractions`,
+      { params: serializeParams(query), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+export const patchFile = async (
+  fileId: string,
+  body: IPatchFileBody,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<IGetFileResponse> => {
+  return (
+    await AbyssExtractCore.axios.patch<IGetFileResponse>(`extract/files/${fileId}`, body, {
+      params: serializeParams(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const downloadFileBundle = async (
+  fileId: string,
+  query: { format?: 'csv' | 'json' } & IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<Buffer> => {
+  const res = await AbyssExtractCore.axios.get(`extract/files/${fileId}/bundle`, {
+    params: serializeParams(query),
+    responseType: 'arraybuffer',
+    headers: authHeader(apiKey),
+  });
+  return Buffer.from(res.data as ArrayBuffer);
+};
+
+/**
+ * Download the ORIGINAL source file (the uploaded document) behind an
+ * extraction_files row — proxy-streamed through the API, not a derived
+ * CSV/JSON export (see downloadFileBundle above). Mirrors its Buffer shape.
+ *
+ * AbyssProbe gate (storage-neutral, ADR-0038): 423 while the file's AV scan
+ * is still pending — retry once the scan settles; clean/infected/skipped/error
+ * all serve — an INFECTED verdict is NOT blocked here, the caller is expected
+ * to warn the end user instead (see IExtractionFile.scanStatus).
+ * GET /extract/files/:id/source
+ */
+export const downloadFileSource = async (
+  fileId: string,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<Buffer> => {
+  const res = await AbyssExtractCore.axios.get(`extract/files/${fileId}/source`, {
+    params: serializeParams(scope),
+    responseType: 'arraybuffer',
+    headers: authHeader(apiKey),
+  });
+  return Buffer.from(res.data as ArrayBuffer);
+};
+
+// ─── EXTRACTIONS ─────────────────────────────
+
+export const getExtraction = async (
+  extractionId: string,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<IGetExtractionResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IGetExtractionResponse>(
+      `extract/extractions/${extractionId}`,
+      {
+        params: serializeParams(scope),
+        headers: authHeader(apiKey),
+      },
+    )
+  ).data;
+};
+
+export const patchExtraction = async (
+  extractionId: string,
+  body: IPatchExtractionBody,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<IGetExtractionResponse> => {
+  return (
+    await AbyssExtractCore.axios.patch<IGetExtractionResponse>(
+      `extract/extractions/${extractionId}`,
+      body,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+export const searchExtractionRecords = async (
+  extractionId: string,
+  query: ISearchExtractionRecordsQuery & IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<ISearchExtractionRecordsResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<ISearchExtractionRecordsResponse>(
+      `extract/extractions/${extractionId}/records`,
+      { params: serializeParams(query), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+export const exportExtraction = async (
+  extractionId: string,
+  query: IExportExtractionQuery & IExtractionContentScopeQuery,
+  apiKey?: string,
+): Promise<{ body: string; contentType: string }> => {
+  const res = await AbyssExtractCore.axios.get(`extract/extractions/${extractionId}/export`, {
+    params: serializeParams(query),
+    responseType: 'text',
+    transformResponse: (d) => d,
+    headers: authHeader(apiKey),
+  });
+  return {
+    body: typeof res.data === 'string' ? res.data : String(res.data),
+    contentType: String(res.headers?.['content-type'] ?? 'application/octet-stream'),
+  };
+};
+
+export const asyncExportExtraction = async (
+  extractionId: string,
+  body: IAsyncExportExtractionBody,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<IAsyncExportResponse> => {
+  return (
+    await AbyssExtractCore.axios.post<IAsyncExportResponse>(
+      `extract/extractions/${extractionId}/export/async`,
+      body,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+export const getExportJob = async (
+  jobId: string,
+  apiKey?: string,
+): Promise<IGetExportJobResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IGetExportJobResponse>(`extract/exports/jobs/${jobId}`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const diffExtractions = async (
+  extractionId: string,
+  otherId: string,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<IDiffExtractionsResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IDiffExtractionsResponse>(
+      `extract/extractions/${extractionId}/diff/${otherId}`,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+/**
+ * Retroactive history toggle: opt a specific extraction in/out of the
+ * improvement-training dataset.
+ * PATCH /extract/extractions/:id/training
+ */
+export const toggleExtractionTraining = async (
+  extractionId: string,
+  body: IToggleExtractionTrainingBody,
+  apiKey?: string,
+): Promise<IToggleExtractionTrainingResponse> => {
+  return (
+    await AbyssExtractCore.axios.patch<IToggleExtractionTrainingResponse>(
+      `extract/extractions/${extractionId}/training`,
+      body,
+      { headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+// ─── TEMPLATES ───────────────────────────────
+
+export const listTemplates = async (
+  query: IListTemplatesQuery & IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<IListTemplatesResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IListTemplatesResponse>(`extract/templates`, {
+      params: serializeParams(query),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const createTemplate = async (
+  body: ICreateTemplateBody,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<ICreateTemplateResponse> => {
+  return (
+    await AbyssExtractCore.axios.post<ICreateTemplateResponse>(`extract/templates`, body, {
+      params: serializeParams(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const getTemplate = async (
+  templateId: string,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<IGetTemplateResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IGetTemplateResponse>(`extract/templates/${templateId}`, {
+      params: serializeParams(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const updateTemplate = async (
+  templateId: string,
+  body: IUpdateTemplateBody,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<IUpdateTemplateResponse> => {
+  return (
+    await AbyssExtractCore.axios.put<IUpdateTemplateResponse>(
+      `extract/templates/${templateId}`,
+      body,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+export const patchTemplateMeta = async (
+  templateId: string,
+  body: IPatchTemplateMetaBody,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<void> => {
+  await AbyssExtractCore.axios.patch(`extract/templates/${templateId}/meta`, body, {
+    params: serializeParams(scope),
+    headers: authHeader(apiKey),
+  });
+};
+
+export const deleteTemplate = async (
+  templateId: string,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<void> => {
+  await AbyssExtractCore.axios.delete(`extract/templates/${templateId}`, {
+    params: serializeParams(scope),
+    headers: authHeader(apiKey),
+  });
+};
+
+export const listTemplateVersions = async (
+  templateId: string,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<IListTemplateVersionsResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IListTemplateVersionsResponse>(
+      `extract/templates/${templateId}/versions`,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+/**
+ * Presigned download URL for a template version's witness PDF.
+ * 404 when the version has no witness.
+ * GET /extract/templates/:id/versions/:version/witness-url
+ */
+export const getTemplateWitnessUrl = async (
+  templateId: string,
+  version: number,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<IGetTemplateWitnessUrlResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IGetTemplateWitnessUrlResponse>(
+      `extract/templates/${templateId}/versions/${version}/witness-url`,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+/**
+ * Delete a template version's witness PDF (frees the billed storage).
+ * 404 when the version has no witness. Allowed on archived templates.
+ * DELETE /extract/templates/:id/versions/:version/witness
+ */
+export const deleteTemplateWitness = async (
+  templateId: string,
+  version: number,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<void> => {
+  await AbyssExtractCore.axios.delete(
+    `extract/templates/${templateId}/versions/${version}/witness`,
+    {
+      params: serializeParams(scope),
+      headers: authHeader(apiKey),
+    },
+  );
+};
+
+export const exportTemplateCollection = async (
+  ids: string[] | null,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<IExtractionTemplateCollection> => {
+  const res = await AbyssExtractCore.axios.get<IExtractionTemplateCollection>(
+    `extract/templates/export`,
+    {
+      params: {
+        ...(ids && ids.length ? { ids: ids.join(',') } : {}),
+        ...serializeParams(scope),
+      },
+      headers: authHeader(apiKey),
+      responseType: 'json',
+    },
+  );
+  return res.data;
+};
+
+export const importTemplateCollection = async (
+  doc: IExtractionTemplateCollection,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<IImportTemplateCollectionResponse> => {
+  return (
+    await AbyssExtractCore.axios.post<IImportTemplateCollectionResponse>(
+      `extract/templates/import`,
+      doc,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+// ─── JOBS ────────────────────────────────────
+
+export const getJob = async (jobId: string, apiKey?: string): Promise<IGetJobResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IGetJobResponse>(`extract/jobs/${jobId}`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const retryJob = async (jobId: string, apiKey?: string): Promise<void> => {
+  await AbyssExtractCore.axios.post(`extract/jobs/${jobId}/retry`, undefined, {
+    headers: authHeader(apiKey),
+  });
+};
+
+export const cancelJob = async (jobId: string, apiKey?: string): Promise<void> => {
+  await AbyssExtractCore.axios.delete(`extract/jobs/${jobId}`, { headers: authHeader(apiKey) });
+};
+
+// ─── FEEDBACK ────────────────────────────────
+
+/**
+ * Submit structured feedback on an extraction. The server ALWAYS mints a
+ * SupportTicket (category EXTRACTION) alongside the structured training row;
+ * the returned feedback DTO carries the resulting `supportTicketId`.
+ * POST /extract/feedback
+ */
+export const submitFeedback = async (
+  body: ISubmitFeedbackExtractionBody,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<ICreateFeedbackResponse> => {
+  return (
+    await AbyssExtractCore.axios.post<ICreateFeedbackResponse>(`extract/feedback`, body, {
+      params: serializeParams(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const listFeedback = async (
+  query: IListFeedbackQuery = {},
+  apiKey?: string,
+): Promise<IListFeedbackResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IListFeedbackResponse>(`extract/feedback`, {
+      params: serializeParams(query),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const getFeedback = async (
+  feedbackId: string,
+  apiKey?: string,
+): Promise<IGetFeedbackResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IGetFeedbackResponse>(`extract/feedback/${feedbackId}`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const patchFeedback = async (
+  feedbackId: string,
+  body: IPatchFeedbackBody,
+  apiKey?: string,
+): Promise<IGetFeedbackResponse> => {
+  return (
+    await AbyssExtractCore.axios.patch<IGetFeedbackResponse>(
+      `extract/feedback/${feedbackId}`,
+      body,
+      {
+        headers: authHeader(apiKey),
+      },
+    )
+  ).data;
+};
+
+// ─── HEALTH / STATS / USAGE ─────────────────
+
+export const health = async (apiKey?: string): Promise<IHealthResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IHealthResponse>(`extract/health`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const stats = async (apiKey?: string): Promise<IStatsResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IStatsResponse>(`extract/stats`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const listUsage = async (
+  query: IListUsageQuery = {},
+  apiKey?: string,
+): Promise<{ data: unknown[]; total?: number }> => {
+  return (
+    await AbyssExtractCore.axios.get<{ data: unknown[]; total?: number }>(`extract/usage`, {
+      params: serializeParams(query),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const summaryUsage = async (
+  query: ISummaryUsageQuery = {},
+  apiKey?: string,
+): Promise<ISummaryUsageResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<ISummaryUsageResponse>(`extract/usage/summary`, {
+      params: serializeParams(query),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+/** Per-config performance metrics (P2) — compare which config works best. */
+export const usageByConfig = async (
+  query: IUsageByConfigQuery = {},
+  apiKey?: string,
+): Promise<IUsageByConfigResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IUsageByConfigResponse>(`extract/usage/by-config`, {
+      params: serializeParams(query),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+/**
+ * Lazy fetch of ONE trace step's full IO payload (P3). Returns the raw text
+ * (gunzipped server-side). The skeleton + previews already ship on getExtraction;
+ * call this only when the user expands a step.
+ */
+export const getStepIo = async (
+  extractionId: string,
+  stepIndex: number,
+  slot: string,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<string> => {
+  return (
+    await AbyssExtractCore.axios.get<string>(
+      `extract/extractions/${extractionId}/steps/${stepIndex}/io/${slot}`,
+      { params: serializeParams(scope), headers: authHeader(apiKey), responseType: 'text' },
+    )
+  ).data;
+};
+
+// ─── SHARED FILES (content_share-backed) ────
+//
+// Types live in `../types/interface/api/requests/extraction.request.ts` so they
+// stay alongside every other extraction SDK contract.
+
+export const listSharedFiles = async (
+  query: IListSharedFilesQuery = {},
+  apiKey?: string,
+): Promise<IListFilesResponse> =>
+  (
+    await AbyssExtractCore.axios.get<IListFilesResponse>(`extract/files/shared`, {
+      params: serializeParams(query),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+
+// ─── WEBHOOK DELIVERIES ─────────────────────
+
+export const listWebhookDeliveries = async (
+  query: IListWebhookDeliveriesQuery = {},
+  apiKey?: string,
+): Promise<IListWebhookDeliveriesResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IListWebhookDeliveriesResponse>(
+      `extract/webhooks/deliveries`,
+      {
+        params: serializeParams(query),
+        headers: authHeader(apiKey),
+      },
+    )
+  ).data;
+};
+
+export const getWebhookDelivery = async (
+  deliveryId: string,
+  apiKey?: string,
+): Promise<IGetWebhookDeliveryResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IGetWebhookDeliveryResponse>(
+      `extract/webhooks/deliveries/${deliveryId}`,
+      { headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+export const replayWebhookDelivery = async (
+  deliveryId: string,
+  body: IReplayWebhookDeliveryBody = {},
+  apiKey?: string,
+): Promise<IGetWebhookDeliveryResponse> => {
+  return (
+    await AbyssExtractCore.axios.post<IGetWebhookDeliveryResponse>(
+      `extract/webhooks/deliveries/${deliveryId}/replay`,
+      body,
+      { headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+// ─── WEBHOOK SUBSCRIPTIONS (CRUD) ───────────
+//
+// Request / response types are defined alongside every other extraction SDK
+// contract — see ../types/interface/api/{requests,responses}/extraction.*.ts.
+
+export const paginateExtractionWebhook = async (
+  query: IPaginateExtractionWebhookQuery = {},
+  apiKey?: string,
+): Promise<IPaginateExtractionWebhookResponse> =>
+  (
+    await AbyssExtractCore.axios.get<IPaginateExtractionWebhookResponse>(`extract/webhook`, {
+      params: serializeParams(query),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+
+export const getExtractionWebhook = async (
+  webhookId: string,
+  scope: IExtractionWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<IGetExtractionWebhookResponse> =>
+  (
+    await AbyssExtractCore.axios.get<IGetExtractionWebhookResponse>(
+      `extract/webhook/${webhookId}`,
+      {
+        params: serializeParams(scope),
+        headers: authHeader(apiKey),
+      },
+    )
+  ).data;
+
+export const createExtractionWebhook = async (
+  body: ICreateExtractionWebhookBody,
+  scope: IExtractionWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<ICreateExtractionWebhookResponse> =>
+  (
+    await AbyssExtractCore.axios.post<ICreateExtractionWebhookResponse>(`extract/webhook`, body, {
+      params: serializeParams(scope),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+
+export const updateExtractionWebhook = async (
+  webhookId: string,
+  body: IUpdateExtractionWebhookBody,
+  scope: IExtractionWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<IUpdateExtractionWebhookResponse> =>
+  (
+    await AbyssExtractCore.axios.put<IUpdateExtractionWebhookResponse>(
+      `extract/webhook/${webhookId}`,
+      body,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+
+export const deleteExtractionWebhook = async (
+  webhookId: string,
+  scope: IExtractionWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<IDeleteExtractionWebhookResponse> =>
+  (
+    await AbyssExtractCore.axios.delete<IDeleteExtractionWebhookResponse>(
+      `extract/webhook/${webhookId}`,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+
+export const resetSecretExtractionWebhook = async (
+  webhookId: string,
+  scope: IExtractionWebhookScopeQuery = {},
+  apiKey?: string,
+): Promise<IResetSecretExtractionWebhookResponse> =>
+  (
+    await AbyssExtractCore.axios.post<IResetSecretExtractionWebhookResponse>(
+      `extract/webhook/${webhookId}/reset-secret`,
+      undefined,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+
+// ─── SHARE ───────────────────────────────────
+
+export const mintShareExtraction = async (
+  extractionId: string,
+  body: IMintShareExtractionBody = {},
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<IMintShareExtractionResponse> => {
+  return (
+    await AbyssExtractCore.axios.post<IMintShareExtractionResponse>(
+      `extract/share/owner/extractions/${extractionId}`,
+      body,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+export const revokeShareExtraction = async (
+  extractionId: string,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<void> => {
+  await AbyssExtractCore.axios.delete(`extract/share/owner/extractions/${extractionId}`, {
+    params: serializeParams(scope),
+    headers: authHeader(apiKey),
+  });
+};
+
+export const getSharedExtractionPublic = async (
+  token: string,
+): Promise<IGetSharedExtractionResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IGetSharedExtractionResponse>(
+      `extract/share/extractions/${token}`,
+    )
+  ).data;
+};
+
+// ─── CHANGELOG ──────────────────────────────
+
+export const changelog = async (apiKey?: string): Promise<IChangelogResponse> => {
+  return (
+    await AbyssExtractCore.axios.get<IChangelogResponse>(`extract/changelog`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};