@abyss-project/tools 1.0.5 → 1.2.0

package/src/api/extraction.api.ts

@@ -0,0 +1,899 @@
+// ──────────────────────────────────────────────
+// 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.
+// ──────────────────────────────────────────────
+
+import { AbyssToolsCore } from '..';
+import {
+  IExtractBody,
+  IExtractBulkBody,
+  IDetectBulkBody,
+  IListFilesQuery,
+  IPatchFileBody,
+  IPatchExtractionBody,
+  ISearchExtractionRecordsQuery,
+  IExportExtractionQuery,
+  IAsyncExportExtractionBody,
+  IListUsageQuery,
+  ISummaryUsageQuery,
+  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,
+  IExtractionTemplateCollection,
+  IImportTemplateCollectionResponse,
+  IGetJobResponse,
+  ICreateFeedbackResponse,
+  IListFeedbackResponse,
+  IGetFeedbackResponse,
+  IHealthResponse,
+  IStatsResponse,
+  ISummaryUsageResponse,
+  IListWebhookDeliveriesResponse,
+  IGetWebhookDeliveryResponse,
+  IGetSharedExtractionResponse,
+  IMintShareExtractionResponse,
+  IChangelogResponse,
+  IToggleExtractionTrainingResponse,
+} from '../types';
+import {
+  ICreateTemplateBody,
+  IUpdateTemplateBody,
+  IPatchTemplateMetaBody,
+  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 } : {};
+}
+
+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');
+}
+
+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.
+ */
+export interface ExtractCallOptions {
+  idempotencyKey?: string;
+}
+
+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>;
+};
+
+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 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);
+    return (
+      await AbyssToolsCore.axios.post(`extract/extract`, form, {
+        params,
+        headers: {
+          ...(typeof form.getHeaders === 'function' ? form.getHeaders() : {}),
+          ...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 AbyssToolsCore.axios.post(`extract/extract`, jsonBody, {
+      params,
+      headers: { ...authHeader(apiKey), ...extraHeaders },
+    })
+  ).data;
+};
+
+function appendIf(form: any, key: string, value: unknown): void {
+  if (value === undefined || value === null) return;
+  form.append(key, String(value));
+}
+
+export const extractBulk = async (
+  body: IExtractBulkBody,
+  scope: IExtractionContentScopeQuery = {},
+  apiKey?: string,
+): Promise<IExtractBulkResponse> => {
+  return (
+    await AbyssToolsCore.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 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' });
+  return (
+    await AbyssToolsCore.axios.post<IDetectResponse>(`extract/detect`, form, {
+      headers: {
+        ...(typeof form.getHeaders === 'function' ? form.getHeaders() : {}),
+        ...authHeader(apiKey),
+      },
+      maxBodyLength: Infinity,
+      maxContentLength: Infinity,
+    })
+  ).data;
+};
+
+export const detectBulk = async (
+  body: IDetectBulkBody,
+  apiKey?: string,
+): Promise<IDetectBulkResponse> => {
+  return (
+    await AbyssToolsCore.axios.post<IDetectBulkResponse>(`extract/detect/bulk`, body, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+// ─── FILES ───────────────────────────────────
+
+export const listFiles = async (
+  query: IListFilesQuery = {},
+  apiKey?: string,
+): Promise<IListFilesResponse> => {
+  return (
+    await AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.axios.get(`extract/files/${fileId}/bundle`, {
+    params: serializeParams(query),
+    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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.axios.patch<IToggleExtractionTrainingResponse>(
+      `extract/extractions/${extractionId}/training`,
+      body,
+      { headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+// ─── TEMPLATES ───────────────────────────────
+
+export const listTemplates = async (
+  query: { kind?: 'spatial' | 'dsl' } & IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<IListTemplatesResponse> => {
+  return (
+    await AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.axios.get<IListTemplateVersionsResponse>(
+      `extract/templates/${templateId}/versions`,
+      { params: serializeParams(scope), headers: authHeader(apiKey) },
+    )
+  ).data;
+};
+
+export const exportTemplateCollection = async (
+  ids: string[] | null,
+  scope: IExtractionTemplateScopeQuery = {},
+  apiKey?: string,
+): Promise<IExtractionTemplateCollection> => {
+  const res = await AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.axios.get<IGetJobResponse>(`extract/jobs/${jobId}`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const retryJob = async (jobId: string, apiKey?: string): Promise<void> => {
+  await AbyssToolsCore.axios.post(`extract/jobs/${jobId}/retry`, undefined, {
+    headers: authHeader(apiKey),
+  });
+};
+
+export const cancelJob = async (jobId: string, apiKey?: string): Promise<void> => {
+  await AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.axios.get<IListFeedbackResponse>(`extract/feedback`, {
+      params: serializeParams(query),
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const getFeedback = async (
+  feedbackId: string,
+  apiKey?: string,
+): Promise<IGetFeedbackResponse> => {
+  return (
+    await AbyssToolsCore.axios.get<IGetFeedbackResponse>(`extract/feedback/${feedbackId}`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const patchFeedback = async (
+  feedbackId: string,
+  body: IPatchFeedbackBody,
+  apiKey?: string,
+): Promise<IGetFeedbackResponse> => {
+  return (
+    await AbyssToolsCore.axios.patch<IGetFeedbackResponse>(`extract/feedback/${feedbackId}`, body, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+// ─── HEALTH / STATS / USAGE ─────────────────
+
+export const health = async (apiKey?: string): Promise<IHealthResponse> => {
+  return (
+    await AbyssToolsCore.axios.get<IHealthResponse>(`extract/health`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const stats = async (apiKey?: string): Promise<IStatsResponse> => {
+  return (
+    await AbyssToolsCore.axios.get<IStatsResponse>(`extract/stats`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};
+
+export const listUsage = async (
+  query: IListUsageQuery = {},
+  apiKey?: string,
+): Promise<{ data: unknown[]; total?: number }> => {
+  return (
+    await AbyssToolsCore.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 AbyssToolsCore.axios.get<ISummaryUsageResponse>(`extract/usage/summary`, {
+      params: serializeParams(query),
+      headers: authHeader(apiKey),
+    })
+  ).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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.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 AbyssToolsCore.axios.delete(`extract/share/owner/extractions/${extractionId}`, {
+    params: serializeParams(scope),
+    headers: authHeader(apiKey),
+  });
+};
+
+export const getSharedExtractionPublic = async (
+  token: string,
+): Promise<IGetSharedExtractionResponse> => {
+  return (
+    await AbyssToolsCore.axios.get<IGetSharedExtractionResponse>(
+      `extract/share/extractions/${token}`,
+    )
+  ).data;
+};
+
+// ─── CHANGELOG ──────────────────────────────
+
+export const changelog = async (apiKey?: string): Promise<IChangelogResponse> => {
+  return (
+    await AbyssToolsCore.axios.get<IChangelogResponse>(`extract/changelog`, {
+      headers: authHeader(apiKey),
+    })
+  ).data;
+};