@startsimpli/integrations 0.2.35 → 0.2.37

package/src/comms/hooks/index.ts

@@ -0,0 +1,253 @@
+/**
+ * React Query hooks over a CommsApi (one per round-trip the page makes).
+ *
+ * Every hook takes the bound `api` rather than reading a module singleton, so
+ * two foundries on one screen never share a cache entry: keys start with
+ * ['startsimpli', 'comms', api.slug].
+ *
+ * Mutations invalidate what they change: program -> programs, settings/domain
+ * -> settings, send-now / draft approve / discard / edit -> drafts.
+ * Nothing here writes on mount; previews fetch only once `enabled`.
+ */
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type UseMutationResult,
+  type UseQueryResult,
+} from '@tanstack/react-query';
+
+import type { CommsApi } from '../api/comms';
+import type {
+  CommsMetrics,
+  CommsProgram,
+  CommsSettings,
+  CommsSettingsPatch,
+  Draft,
+  DraftPatch,
+  DraftsQuery,
+  MetricsQuery,
+  Paginated,
+  ProgramPatch,
+  ProgramUpdateResult,
+  RenderedEmail,
+  SendNowResult,
+  SendRow,
+  SendsQuery,
+  StepGeneration,
+  TestSendInput,
+  TestSendResult,
+} from '../types/index';
+
+export const commsKeys = {
+  all: (slug: string) => ['startsimpli', 'comms', slug] as const,
+  settings: (slug: string) => ['startsimpli', 'comms', slug, 'settings'] as const,
+  programs: (slug: string) => ['startsimpli', 'comms', slug, 'programs'] as const,
+  generation: (slug: string, key: string, step: number) =>
+    ['startsimpli', 'comms', slug, 'generation', key, step] as const,
+  preview: (slug: string, key: string, step: number) =>
+    ['startsimpli', 'comms', slug, 'preview', key, step] as const,
+  draftsAll: (slug: string) => ['startsimpli', 'comms', slug, 'drafts'] as const,
+  drafts: (slug: string, q: DraftsQuery = {}) => ['startsimpli', 'comms', slug, 'drafts', q] as const,
+  draft: (slug: string, id: string) => ['startsimpli', 'comms', slug, 'drafts', 'one', id] as const,
+  draftPreview: (slug: string, id: string) => ['startsimpli', 'comms', slug, 'draft-preview', id] as const,
+  sends: (slug: string, q: SendsQuery = {}) => ['startsimpli', 'comms', slug, 'sends', q] as const,
+  metrics: (slug: string, q: MetricsQuery = {}) => ['startsimpli', 'comms', slug, 'metrics', q] as const,
+};
+
+/** How often the page re-asks about background work (generation). */
+export const DEFAULT_POLL_MS = 2000;
+
+// settings ---------------------------------------------------------------
+
+export function useCommsSettings(api: CommsApi): UseQueryResult<CommsSettings> {
+  return useQuery({ queryKey: commsKeys.settings(api.slug), queryFn: () => api.getSettings() });
+}
+
+function useSettingsWrite<V>(api: CommsApi, fn: (v: V) => Promise<CommsSettings>) {
+  const qc = useQueryClient();
+  return useMutation<CommsSettings, Error, V>({
+    mutationFn: fn,
+    onSuccess: (data) => {
+      qc.setQueryData(commsKeys.settings(api.slug), data);
+      return qc.invalidateQueries({ queryKey: commsKeys.settings(api.slug) });
+    },
+  });
+}
+
+/** Invalidates settings. `voice` is replaced whole server-side: send all of it. */
+export function useUpdateCommsSettings(api: CommsApi): UseMutationResult<CommsSettings, Error, CommsSettingsPatch> {
+  return useSettingsWrite(api, (patch: CommsSettingsPatch) => api.updateSettings(patch));
+}
+
+export function useConnectDomain(api: CommsApi): UseMutationResult<CommsSettings, Error, string> {
+  return useSettingsWrite(api, (domain: string) => api.connectDomain(domain));
+}
+
+export function useCheckDomain(api: CommsApi): UseMutationResult<CommsSettings, Error, void> {
+  return useSettingsWrite(api, () => api.checkDomain());
+}
+
+// programs ---------------------------------------------------------------
+
+export function usePrograms(api: CommsApi): UseQueryResult<CommsProgram[]> {
+  return useQuery({ queryKey: commsKeys.programs(api.slug), queryFn: () => api.listPrograms() });
+}
+
+function useProgramsWrite<R extends CommsProgram, V>(api: CommsApi, fn: (v: V) => Promise<R>) {
+  const qc = useQueryClient();
+  return useMutation<R, Error, V>({
+    mutationFn: fn,
+    onSuccess: (program) => {
+      qc.setQueryData<CommsProgram[]>(commsKeys.programs(api.slug), (old) => {
+        if (!old) return old;
+        // The PATCH response may carry `cancelled`; it is not part of the program.
+        const { cancelled: _c, ...clean } = program as ProgramUpdateResult;
+        return old.map((p) => (p.key === program.key ? (clean as CommsProgram) : p));
+      });
+      return qc.invalidateQueries({ queryKey: commsKeys.programs(api.slug) });
+    },
+  });
+}
+
+/** Invalidates programs; on enabled:false the server cancels pending steps (A8). */
+export function useUpdateProgram(
+  api: CommsApi,
+): UseMutationResult<ProgramUpdateResult, Error, { key: string; patch: ProgramPatch }> {
+  return useProgramsWrite(api, ({ key, patch }: { key: string; patch: ProgramPatch }) =>
+    api.updateProgram(key, patch));
+}
+
+/** Queues generation (202). Follow it with useStepGeneration. */
+export function useGenerateStep(
+  api: CommsApi,
+): UseMutationResult<StepGeneration, Error, { key: string; step: number; instructions?: string }> {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: ({ key, step, instructions }) =>
+      api.generateStep(key, step, instructions ? { instructions } : {}),
+    onSuccess: (status, { key, step }) => {
+      qc.setQueryData(commsKeys.generation(api.slug, key, step), status);
+    },
+  });
+}
+
+/**
+ * Polls the generation status while `enabled` and it is still pending. When it
+ * settles on done, the programs list is refetched so the step shows its draft.
+ */
+export function useStepGeneration(
+  api: CommsApi,
+  key: string,
+  step: number,
+  enabled: boolean,
+  pollMs: number = DEFAULT_POLL_MS,
+): UseQueryResult<StepGeneration> {
+  const qc = useQueryClient();
+  return useQuery({
+    queryKey: commsKeys.generation(api.slug, key, step),
+    queryFn: async () => {
+      const status = await api.getStepGeneration(key, step);
+      if (status.status === 'done') await qc.invalidateQueries({ queryKey: commsKeys.programs(api.slug) });
+      return status;
+    },
+    enabled,
+    refetchInterval: (q) => (q.state.data?.status === 'pending' ? pollMs : false),
+  });
+}
+
+export function useApproveStep(api: CommsApi): UseMutationResult<CommsProgram, Error, { key: string; step: number }> {
+  return useProgramsWrite(api, ({ key, step }: { key: string; step: number }) => api.approveStep(key, step));
+}
+
+/** Fetches only while `enabled` (i.e. after the admin asks for the preview). */
+export function useStepPreview(api: CommsApi, key: string, step: number, enabled: boolean): UseQueryResult<RenderedEmail> {
+  return useQuery({
+    queryKey: commsKeys.preview(api.slug, key, step),
+    queryFn: () => api.previewStep(key, step),
+    enabled,
+    staleTime: 0,
+  });
+}
+
+export function useSendTest(api: CommsApi): UseMutationResult<TestSendResult, Error, TestSendInput> {
+  return useMutation({ mutationFn: (input: TestSendInput) => api.sendTest(input) });
+}
+
+// product updates ----------------------------------------------------------
+
+/** Re-polls while any listed draft is still being written. */
+export function useDrafts(api: CommsApi, q: DraftsQuery, pollMs: number = DEFAULT_POLL_MS): UseQueryResult<Paginated<Draft>> {
+  return useQuery({
+    queryKey: commsKeys.drafts(api.slug, q),
+    queryFn: () => api.listDrafts(q),
+    refetchInterval: (query) =>
+      query.state.data?.results.some((d) => d.generating) ? pollMs : false,
+  });
+}
+
+/** One draft, polled while `generating` (send-now hands back a placeholder). */
+export function useDraft(api: CommsApi, id: string | null, pollMs: number = DEFAULT_POLL_MS): UseQueryResult<Draft> {
+  return useQuery({
+    queryKey: commsKeys.draft(api.slug, id ?? ''),
+    queryFn: () => api.getDraft(id as string),
+    enabled: !!id,
+    refetchInterval: (query) => (query.state.data && !query.state.data.generating ? false : pollMs),
+  });
+}
+
+export function useDraftPreview(api: CommsApi, id: string, enabled: boolean): UseQueryResult<RenderedEmail> {
+  return useQuery({
+    queryKey: commsKeys.draftPreview(api.slug, id),
+    queryFn: () => api.previewDraft(id),
+    enabled,
+    staleTime: 0,
+  });
+}
+
+function useDraftsWrite<R, V>(api: CommsApi, fn: (v: V) => Promise<R>) {
+  const qc = useQueryClient();
+  return useMutation<R, Error, V>({
+    mutationFn: fn,
+    onSuccess: () => qc.invalidateQueries({ queryKey: commsKeys.draftsAll(api.slug) }),
+  });
+}
+
+export function useUpdateDraft(api: CommsApi): UseMutationResult<Draft, Error, { id: string; patch: DraftPatch }> {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: ({ id, patch }) => api.updateDraft(id, patch),
+    onSuccess: (_d, { id }) => Promise.all([
+      qc.invalidateQueries({ queryKey: commsKeys.draftsAll(api.slug) }),
+      qc.invalidateQueries({ queryKey: commsKeys.draftPreview(api.slug, id) }),
+    ]),
+  });
+}
+
+export function useApproveDraft(api: CommsApi): UseMutationResult<Draft, Error, string> {
+  return useDraftsWrite(api, (id: string) => api.approveDraft(id));
+}
+
+export function useDiscardDraft(api: CommsApi): UseMutationResult<Draft, Error, string> {
+  return useDraftsWrite(api, (id: string) => api.discardDraft(id));
+}
+
+/** Invalidates drafts. A 202 result's draft is still generating: follow it with useDraft. */
+export function useSendUpdateNow(api: CommsApi): UseMutationResult<SendNowResult, Error, { notes?: string }> {
+  return useDraftsWrite(api, (input: { notes?: string }) => api.sendUpdateNow(input));
+}
+
+// results ------------------------------------------------------------------
+
+/** Server-side pagination: page/page_size go to the server, never sliced here. */
+export function useSends(api: CommsApi, q: SendsQuery): UseQueryResult<Paginated<SendRow>> {
+  return useQuery({
+    queryKey: commsKeys.sends(api.slug, q),
+    queryFn: () => api.listSends(q),
+    placeholderData: (prev) => prev,
+  });
+}
+
+export function useCommsMetrics(api: CommsApi, q: MetricsQuery): UseQueryResult<CommsMetrics> {
+  return useQuery({ queryKey: commsKeys.metrics(api.slug, q), queryFn: () => api.getMetrics(q) });
+}

package/src/comms/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @startsimpli/integrations/comms: customer email for a foundry (epic startsim-uwiw6,
+ * lane startsim-r7hws). Typed client over the central comms admin API,
+ * React Query hooks, and the Customer emails page composer that
+ * apps/foundry mounts per foundry.
+ *
+ * Subpath only: NOT re-exported from the package root, so a root import never
+ * pulls in @startsimpli/ui, and comms' setApiBase/setAuthTokenProvider never
+ * collide with the root's.
+ */
+export * from './types/index';
+export * from './api/index';
+export * from './hooks/index';
+export * from './components/index';

package/src/comms/types/index.ts

@@ -0,0 +1,308 @@
+/**
+ * Wire types for the foundry comms admin API (bd startsim-bzcrj ADR, section 2).
+ *
+ * SNAKE_CASE ON PURPOSE. These mirror the DRF serializers field for field, and
+ * this package talks to Django through its own `request()` (api/_fetch.ts), which
+ * does no key transform. `@startsimpli/api`'s client camelCases responses, which
+ * is why the composer is not driven by it: every field here would come back
+ * renamed and read as undefined.
+ *
+ * Routes live under /api/v1/foundry/tenants/{slug}/comms/.
+ */
+
+// ---- settings -------------------------------------------------------------
+
+export type ApprovalMode = 'auto' | 'approve';
+export type DomainStatus = 'none' | 'pending' | 'verified' | 'failed';
+
+export interface CommsVoice {
+  product: string;
+  tone: string;
+  audience: string;
+  cta_url: string;
+  avoid_words: string[];
+}
+
+export type DomainRecordPurpose = 'spf' | 'dkim' | 'dmarc';
+
+export interface DomainRecord {
+  /** e.g. "TXT" / "CNAME". */
+  type: string;
+  host: string;
+  value: string;
+  ok: boolean;
+  /** Which check this record satisfies (UI gap G7). */
+  purpose?: DomainRecordPurpose;
+}
+
+export interface SourceRepo {
+  provider: 'github';
+  owner: string;
+  name: string;
+}
+
+export interface CommsSettings {
+  approval_mode: ApprovalMode;
+  voice: CommsVoice;
+  sender_name: string;
+  reply_to: string;
+  postal_address: string;
+  sending_domain: string;
+  domain_status: DomainStatus;
+  domain_records: DomainRecord[];
+  domain_checked_at: string | null;
+  paused: boolean;
+  source_repos: SourceRepo[];
+  /**
+   * The From address comms mail actually goes out with (UI gap G3): the
+   * foundry's own domain once verified, else the StartSimpli marketing stream.
+   * null when the stream has no fallback domain configured. Read-only.
+   */
+  from_address: string | null;
+}
+
+/**
+ * PATCH body. Domain fields and from_address are read-only server-side.
+ * `voice` is a JSON field the server REPLACES, so send the whole object.
+ */
+export type CommsSettingsPatch = Partial<
+  Omit<CommsSettings, 'sending_domain' | 'domain_status' | 'domain_records' | 'domain_checked_at' | 'from_address'>
+>;
+
+// ---- programs -------------------------------------------------------------
+
+export type ProgramKind = 'sequence' | 'broadcast';
+export type ProgramCategory = 'lifecycle' | 'product_updates';
+export type ContentStatus = 'empty' | 'draft' | 'approved';
+
+export interface EmailContent {
+  subject: string;
+  preheader: string;
+  html: string;
+  text: string;
+}
+
+export interface SequenceStep {
+  offset_days: number;
+  intent: string;
+  content: EmailContent | null;
+  content_status: ContentStatus;
+  generated_at: string | null;
+}
+
+export type SequenceTrigger =
+  | { type: 'inactive'; days: number }
+  | { type: 'joined' }
+  | { type: 'event'; name: string };
+
+export interface SequenceConfig {
+  trigger: SequenceTrigger;
+  steps: SequenceStep[];
+  exit: string[];
+  cooldown_days: number;
+}
+
+export type BroadcastCadence = 'on_deploy' | 'weekly' | 'monthly' | 'manual';
+export type BroadcastAudience = 'all' | 'active' | 'inactive';
+
+export interface BroadcastConfig {
+  cadence: BroadcastCadence;
+  audience: BroadcastAudience;
+  active_days: number;
+}
+
+interface ProgramBase {
+  key: string;
+  category: ProgramCategory;
+  enabled: boolean;
+  version: number;
+}
+
+export interface SequenceProgram extends ProgramBase {
+  kind: 'sequence';
+  config: SequenceConfig;
+}
+
+export interface BroadcastProgram extends ProgramBase {
+  kind: 'broadcast';
+  config: BroadcastConfig;
+}
+
+export type CommsProgram = SequenceProgram | BroadcastProgram;
+
+/**
+ * PATCH body. `config` REPLACES the stored config (a sequence config is
+ * validated whole: trigger + steps are required), so send the full object.
+ */
+export interface ProgramPatch {
+  enabled?: boolean;
+  config?: SequenceConfig | BroadcastConfig;
+}
+
+/** PATCH response: on enabled:false the server reports how many pending
+ * enrollments it cancelled (UI gap G5). */
+export type ProgramUpdateResult = CommsProgram & { cancelled?: number };
+
+/** Background step generation (POST 202 / GET poll on steps/{i}/generate/). */
+export type GenerationState = 'idle' | 'pending' | 'done' | 'failed';
+
+export interface StepGeneration {
+  step_index: number;
+  status: GenerationState;
+  error: string;
+  requested_at: string | null;
+  finished_at: string | null;
+  step: SequenceStep | null;
+}
+
+/** The two switches persona A sees (A1). Presets are data server-side. */
+export const COMEBACK_PROGRAM_KEY = 'comeback';
+export const PRODUCT_UPDATE_PROGRAM_KEY = 'product_update';
+
+// ---- preview / test send ----------------------------------------------------
+
+/** Server-rendered for the requesting admin as the sample recipient. */
+export type RenderedEmail = EmailContent;
+
+export type TestSendInput =
+  | { program_key: string; step_index: number }
+  | { draft_id: string };
+
+export interface TestSendResult {
+  sent: boolean;
+  reason?: string;
+}
+
+// ---- changes / drafts ------------------------------------------------------
+
+export interface ChangeItem {
+  key: string;
+  kind: 'pr' | 'deploy' | 'note';
+  title: string;
+  body: string;
+  url: string;
+  merged_at: string | null;
+  audience: 'customer' | 'internal';
+  feature_group: string;
+}
+
+export interface ChangesResponse {
+  items: ChangeItem[];
+  window: [string, string];
+  /** Keys still waiting on a background classification; re-fetch later. */
+  unclassified: string[];
+}
+
+export type DraftApproval = 'pending' | 'approved' | 'discarded';
+
+export interface Draft {
+  id: string;
+  program_key: string;
+  subject: string;
+  preheader: string;
+  html: string;
+  text: string;
+  approval: DraftApproval;
+  item_keys: string[];
+  window: [string, string];
+  created_at: string;
+  /** Set when generation failed (or "nothing_customer_facing" on a discarded draft). */
+  error: string | null;
+  /** True while a worker is still writing the content: poll getDraft(id). */
+  generating: boolean;
+}
+
+export type DraftPatch = Partial<Pick<Draft, 'subject' | 'preheader' | 'html' | 'text'>>;
+
+export const NOTHING_CUSTOMER_FACING = 'nothing_customer_facing';
+export const DRAFT_PENDING = 'draft_pending';
+
+/**
+ * 202 {draft (generating), reason: null}: poll getDraft(draft.id).
+ * 200 {draft: null, reason: nothing_customer_facing}.
+ * 200 {draft: <the pending one>, reason: draft_pending}.
+ */
+export interface SendNowResult {
+  draft: Draft | null;
+  reason?: typeof NOTHING_CUSTOMER_FACING | typeof DRAFT_PENDING | string | null;
+}
+
+// ---- sends / metrics -------------------------------------------------------
+
+/** DRF PageNumberPagination envelope ({count, next, previous, results}). */
+export interface Paginated<T> {
+  count: number;
+  next: string | null;
+  previous: string | null;
+  results: T[];
+}
+
+export interface PageParams {
+  page?: number;
+  page_size?: number;
+}
+
+export type SendStatus =
+  | 'pending' | 'sent' | 'delivered' | 'opened' | 'clicked'
+  | 'bounced' | 'failed' | 'suppressed' | 'complained';
+
+export interface SendRow {
+  id: string;
+  email: string;
+  program_key: string;
+  step_index: number | null;
+  subject: string;
+  status: SendStatus | string;
+  sent_at: string | null;
+  opened_at: string | null;
+  clicked_at: string | null;
+  error: string | null;
+}
+
+export interface SendsQuery extends PageParams {
+  program?: string;
+  status?: string;
+  /** One product-update campaign (a draft id). */
+  campaign?: string;
+}
+
+export interface DraftsQuery extends PageParams {
+  status?: DraftApproval;
+}
+
+export interface CommsMetrics {
+  sent: number;
+  delivered: number;
+  opened: number;
+  clicked: number;
+  bounced: number;
+  complained: number;
+  unsubscribed: number;
+  came_back: number;
+}
+
+export interface MetricsQuery {
+  program?: string;
+  campaign?: string;
+  from?: string;
+  to?: string;
+}
+
+// ---- errors ----------------------------------------------------------------
+
+export interface CommsErrorPayload {
+  error?: string;
+  detail?: string;
+  [k: string]: unknown;
+}
+
+export class CommsApiError extends Error {
+  status: number;
+  payload: CommsErrorPayload;
+  constructor(message: string, status: number, payload: CommsErrorPayload = {}) {
+    super(message);
+    this.name = 'CommsApiError';
+    this.status = status;
+    this.payload = payload;
+  }
+}

package/src/ingest/index.ts

@@ -0,0 +1,126 @@
+/**
+ * Document ingest helpers (crochet_patterns-llmj, design D1/PK2): turn a fetched
+ * web page or a stored PDF into plain text for a model.
+ *
+ * SERVER-ONLY. Exported from the `@startsimpli/integrations/ingest` subpath,
+ * never from the package root (linkedom and unpdf are node-side dependencies).
+ */
+import { Readability } from '@mozilla/readability';
+import { parseHTML } from 'linkedom';
+import { extractText, getDocumentProxy } from 'unpdf';
+
+// ---------------------------------------------------------------------------
+// HTML
+// ---------------------------------------------------------------------------
+
+const SKIP = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE', 'SVG', 'IFRAME', 'HEAD']);
+const BLOCK = new Set([
+  'ADDRESS', 'ARTICLE', 'ASIDE', 'BLOCKQUOTE', 'BODY', 'CAPTION', 'DD', 'DETAILS', 'DIV', 'DL', 'DT',
+  'FIELDSET', 'FIGCAPTION', 'FIGURE', 'FOOTER', 'FORM', 'H1', 'H2', 'H3', 'H4', 'H5', 'H6', 'HEADER',
+  'HR', 'LI', 'MAIN', 'NAV', 'OL', 'P', 'PRE', 'SECTION', 'SUMMARY', 'TABLE', 'TBODY', 'TD', 'TFOOT',
+  'TH', 'THEAD', 'TR', 'UL',
+]);
+
+interface DomNode {
+  nodeType: number;
+  nodeName: string;
+  textContent: string | null;
+  childNodes: ArrayLike<DomNode>;
+}
+
+/** Text of a DOM subtree with a line break around every block element and at `<br>`. */
+function blockText(root: DomNode): string {
+  let out = '';
+  const walk = (node: DomNode) => {
+    if (node.nodeType === 3) {
+      out += (node.textContent ?? '').replace(/\s+/g, ' ');
+      return;
+    }
+    if (node.nodeType !== 1 && node.nodeType !== 9 && node.nodeType !== 11) return;
+    const tag = node.nodeName.toUpperCase();
+    if (SKIP.has(tag)) return;
+    if (tag === 'BR') {
+      out += '\n';
+      return;
+    }
+    const block = BLOCK.has(tag);
+    if (block) out += '\n';
+    for (let i = 0; i < node.childNodes.length; i++) walk(node.childNodes[i]!);
+    if (block) out += '\n';
+  };
+  walk(root);
+  return out
+    .split('\n')
+    .map((line) => line.replace(/[ \t ]+/g, ' ').trim())
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/**
+ * The readable text of an HTML page: Readability's main article when it finds
+ * one, else the whole body (scripts and styles dropped). Each block element and
+ * `<br>` starts a new line, so "Rnd 1 … / Rnd 2 …" list items stay one per line.
+ * `baseUrl` lets Readability resolve relative links; it does not change the text.
+ */
+export function readableText(html: string, baseUrl?: string): { title?: string; text: string } {
+  // linkedom leaves a bare fragment out of <body>; give it a document to live in.
+  const whole = /<html[\s>]/i.test(html) ? html : `<!doctype html><html><head></head><body>${html}</body></html>`;
+  const { document } = parseHTML(whole);
+  if (baseUrl && !document.querySelector('base')) {
+    const base = document.createElement('base');
+    base.setAttribute('href', baseUrl);
+    document.head?.appendChild(base);
+  }
+  const docTitle = document.title?.trim() || undefined;
+
+  let text = '';
+  let title = docTitle;
+  try {
+    // Readability mutates the document it is given; parse a fresh copy.
+    const article = new Readability(parseHTML(document.toString()).document as unknown as Document).parse();
+    if (article?.content) {
+      text = blockText(parseHTML(`<html><body>${article.content}</body></html>`).document as unknown as DomNode);
+      title = article.title?.trim() || docTitle;
+    }
+  } catch {
+    // fall through to the whole body
+  }
+  if (!text) text = blockText((document.body ?? document) as unknown as DomNode);
+  return title ? { title, text } : { text };
+}
+
+// ---------------------------------------------------------------------------
+// PDF
+// ---------------------------------------------------------------------------
+
+export interface PdfText {
+  /** One entry per page, trimmed. */
+  pages: string[];
+  /** Characters across all pages (trimmed). */
+  totalChars: number;
+}
+
+/**
+ * Text layer of a PDF, one string per page (unpdf / pdf.js). Throws on bytes
+ * that are not a readable PDF. The input is copied first, so the caller's
+ * buffer (the stored original) is never detached.
+ */
+export async function extractPdfText(bytes: Uint8Array): Promise<PdfText> {
+  const pdf = await getDocumentProxy(new Uint8Array(bytes), { verbosity: 0 });
+  try {
+    const { text } = await extractText(pdf, { mergePages: false });
+    const pages = text.map((t) => t.trim());
+    return { pages, totalChars: pages.reduce((n, p) => n + p.length, 0) };
+  } finally {
+    await pdf.loadingTask.destroy().catch(() => undefined);
+  }
+}
+
+/** Average under this many characters per page = no usable text layer (design R6). */
+export const SCANNED_CHARS_PER_PAGE = 200;
+
+/** True when a PDF has no usable text layer and should go to the model as a document. */
+export function looksScanned(r: PdfText): boolean {
+  return r.pages.length === 0 || r.totalChars / r.pages.length < SCANNED_CHARS_PER_PAGE;
+}