0pt/src/adapters/document-intelligence-adapter.ts

/**
 * src/adapters/document-intelligence-adapter.ts
 * ================================================
 * Tenant-agnostic Azure AI Document Intelligence client.
 *
 * Generalized from v0-datahub/lib/invoice-inbox/doc-intelligence.ts, which
 * hardcoded the `prebuilt-invoice` model and a fixed invoice-shaped return
 * type (amount_gross, vendor, vat, ...). Here `modelId` is a CALLER-SUPPLIED
 * parameter — "prebuilt-invoice", "prebuilt-receipt", "prebuilt-layout",
 * "prebuilt-read", or any custom-trained model id — and the adapter returns
 * a generic field map instead of assuming any particular document shape.
 *
 * Evidence discipline (correctness-critical, not a style choice): a field is
 * only ever populated with the value + confidence Document Intelligence
 * actually reported. If DI did not return a value, the field comes back as
 * { value: null, confidence: <DI's confidence if any, else null>, found: false }.
 * Nothing here ever defaults, guesses, or backfills a value.
 */

export interface DocumentIntelligenceConfig {
  endpoint: string;
  apiKey: string;
  /** Default: "2024-11-30" — the API version the production invoice pipeline used. */
  apiVersion?: string;
  /** Delay between result-polling attempts, ms. Default 2000. (Tests override to run fast.) */
  pollIntervalMs?: number;
  /** Delay before retrying after a 429, ms. Default 6000. (Tests override to run fast.) */
  rateLimitRetryMs?: number;
  /** Max result-polling attempts before timing out. Default 40. */
  maxPollAttempts?: number;
  /** Max analyze-request attempts (each 429 counts as one). Default 4. */
  maxAnalyzeAttempts?: number;
}

export interface ExtractedField {
  value: string | number | boolean | null;
  confidence: number | null;
  found: boolean;
}

export interface DocumentIntelligenceResult {
  modelId: string;
  apiVersion: string;
  /** Full extracted text, when the API returns one (present across prebuilt models). */
  content: string | null;
  /** Top-level structured fields (documents[0].fields), normalized. Empty for pure layout/read. */
  fields: Record<string, ExtractedField>;
  /** Array-of-object fields (e.g. invoice/receipt line items), each item pre-normalized. */
  arrayFields: Record<string, Array<Record<string, ExtractedField>>>;
  /** documents[0].confidence, when the model reports a whole-document confidence. */
  documentConfidence: number | null;
  pageCount: number | null;
}

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

/** Normalize one Document Intelligence field object into an evidence-based ExtractedField. */
function normalizeField(raw: unknown): ExtractedField {
  const f = raw as Record<string, unknown> | null | undefined;
  if (!f) return { value: null, confidence: null, found: false };
  let value: string | number | boolean | null = null;
  switch (f.type) {
    case "string":
      value = (f.valueString as string | undefined) ?? (f.content as string | undefined) ?? null;
      break;
    case "number":
      value = (f.valueNumber as number | undefined) ?? null;
      break;
    case "integer":
      value = (f.valueInteger as number | undefined) ?? null;
      break;
    case "date":
      value = (f.valueDate as string | undefined) ?? null;
      break;
    case "time":
      value = (f.valueTime as string | undefined) ?? null;
      break;
    case "phoneNumber":
      value = (f.valuePhoneNumber as string | undefined) ?? null;
      break;
    case "countryRegion":
      value = (f.valueCountryRegion as string | undefined) ?? null;
      break;
    case "selectionMark":
      value = (f.valueSelectionMark as string | undefined) ?? null;
      break;
    case "currency": {
      const cur = f.valueCurrency as Record<string, unknown> | undefined;
      value = typeof cur?.amount === "number" ? (cur.amount as number) : null;
      break;
    }
    case "boolean":
      value = typeof f.valueBoolean === "boolean" ? (f.valueBoolean as boolean) : null;
      break;
    default:
      value = (f.valueString as string | undefined) ?? (f.content as string | undefined) ?? null;
  }
  const found = value !== null && value !== undefined && value !== "";
  const confidence = typeof f.confidence === "number" ? (f.confidence as number) : null;
  return { value: found ? value : null, confidence, found };
}

function normalizeObjectFields(obj: Record<string, unknown> | null | undefined): Record<string, ExtractedField> {
  const out: Record<string, ExtractedField> = {};
  for (const [key, raw] of Object.entries(obj ?? {})) {
    out[key] = normalizeField(raw);
  }
  return out;
}

export class DocumentIntelligenceAdapter {
  constructor(private config: DocumentIntelligenceConfig) {}

  static isConfigured(config: Partial<DocumentIntelligenceConfig>): boolean {
    return !!(config.endpoint && config.apiKey);
  }

  /**
   * Analyze a document buffer with the given model. Throws on any failure —
   * callers must never interpret a caught error as "no fields found". A
   * genuinely empty field is represented by { found: false } *inside a
   * successful result*; a failed call must propagate as an error, not a
   * fabricated empty success.
   */
  async analyzeDocument(buf: Buffer, modelId: string): Promise<DocumentIntelligenceResult> {
    const apiVersion = this.config.apiVersion || "2024-11-30";
    const base = this.config.endpoint.replace(/\/$/, "");
    const analyzeUrl = `${base}/documentintelligence/documentModels/${encodeURIComponent(modelId)}:analyze?api-version=${apiVersion}`;

    const maxAnalyzeAttempts = this.config.maxAnalyzeAttempts ?? 4;
    const rateLimitRetryMs = this.config.rateLimitRetryMs ?? 6000;
    const pollIntervalMs = this.config.pollIntervalMs ?? 2000;
    const maxPollAttempts = this.config.maxPollAttempts ?? 40;

    let operationLocation = "";
    for (let attempt = 0; attempt < maxAnalyzeAttempts; attempt++) {
      const res = await fetch(analyzeUrl, {
        method: "POST",
        headers: { "Ocp-Apim-Subscription-Key": this.config.apiKey, "Content-Type": "application/json" },
        body: JSON.stringify({ base64Source: buf.toString("base64") }),
      });
      if (res.status === 429) {
        await sleep(rateLimitRetryMs);
        continue;
      }
      if (res.status !== 202) {
        const text = await res.text().catch(() => "");
        throw new Error(`Document Intelligence analyze request failed: ${res.status} ${text.slice(0, 300)}`);
      }
      operationLocation = res.headers.get("operation-location") || "";
      break;
    }
    if (!operationLocation) {
      throw new Error(
        "Document Intelligence analyze did not return an operation-location (rate-limited after retries, or misconfigured)",
      );
    }

    let payload: Record<string, unknown> | null = null;
    for (let i = 0; i < maxPollAttempts; i++) {
      await sleep(pollIntervalMs);
      const pollRes = await fetch(operationLocation, { headers: { "Ocp-Apim-Subscription-Key": this.config.apiKey } });
      if (!pollRes.ok) {
        const text = await pollRes.text().catch(() => "");
        throw new Error(`Document Intelligence poll request failed: ${pollRes.status} ${text.slice(0, 300)}`);
      }
      const json = (await pollRes.json()) as Record<string, unknown>;
      if (json.status === "succeeded") {
        payload = json;
        break;
      }
      if (json.status === "failed") {
        throw new Error(`Document Intelligence analyze failed: ${JSON.stringify(json.error ?? json).slice(0, 500)}`);
      }
    }
    if (!payload) {
      throw new Error("Document Intelligence analyze timed out waiting for a result");
    }

    const analyzeResult = (payload.analyzeResult as Record<string, unknown>) ?? {};
    const documents = analyzeResult.documents as Array<Record<string, unknown>> | undefined;
    const doc = documents?.[0];
    const rawFields = (doc?.fields as Record<string, unknown>) ?? {};

    const fields: Record<string, ExtractedField> = {};
    const arrayFields: Record<string, Array<Record<string, ExtractedField>>> = {};
    for (const [key, raw] of Object.entries(rawFields)) {
      const f = raw as Record<string, unknown>;
      if (f?.type === "array" && Array.isArray(f.valueArray)) {
        arrayFields[key] = (f.valueArray as Array<Record<string, unknown>>).map((item) =>
          normalizeObjectFields(item?.valueObject as Record<string, unknown> | undefined),
        );
      } else {
        fields[key] = normalizeField(f);
      }
    }

    const pages = analyzeResult.pages as unknown[] | undefined;

    return {
      modelId,
      apiVersion,
      content: typeof analyzeResult.content === "string" ? (analyzeResult.content as string) : null,
      fields,
      arrayFields,
      documentConfidence: typeof doc?.confidence === "number" ? (doc.confidence as number) : null,
      pageCount: Array.isArray(pages) ? pages.length : null,
    };
  }
}