@bluefields/extractor 0.2.0

package/dist/model-picker.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pick Haiku vs Sonnet based on JSON-Schema complexity.
+ *
+ * Why this exists: Haiku 4.5 costs ~3x less ($1/$5 per MTok vs $3/$15)
+ * and is more than adequate for shallow extractions ("price", "title",
+ * "in stock"). Sonnet is worth it for deep / nested schemas where the
+ * model has to reason about more than 1 level of structure.
+ *
+ * Heuristic (intentionally simple — tune from cost_records data later):
+ *   - No schema → no model picked (caller short-circuits to markdown-only).
+ *   - Schema is "flat": top-level object with primitive (string/number/
+ *     boolean) properties only, and no more than MAX_FLAT_PROPS keys.
+ *     Arrays of primitives count as flat. → Haiku.
+ *   - Anything else (nested objects, arrays of objects, deep schemas,
+ *     unbounded `additionalProperties: true` extracts) → Sonnet.
+ *
+ * The model name is part of `extractor_version`, which keys the cross-
+ * customer extraction cache (Review #6). Switching a schema from Sonnet
+ * to Haiku invalidates the cache for that schema — fine; cache misses
+ * just retry under the new model.
+ */
+export declare const HAIKU_MODEL = "claude-haiku-4-5-20251001";
+export declare const SONNET_MODEL_ID = "claude-sonnet-4-6";
+export type PickedModel = typeof HAIKU_MODEL | typeof SONNET_MODEL_ID;
+export interface ModelPickReason {
+    model: PickedModel;
+    reason: 'haiku_flat_schema' | 'sonnet_nested' | 'sonnet_too_many_props' | 'sonnet_array_of_objects' | 'sonnet_unbounded' | 'sonnet_non_object_top' | 'sonnet_default';
+}
+export declare function pickModel(schema: Record<string, unknown> | null): PickedModel;
+export declare function pickModelWithReason(schema: Record<string, unknown> | null): ModelPickReason;
+/**
+ * Cost per million input tokens, in dollars. Pricing as of late 2025.
+ * Haiku 4.5: $1 input / $5 output. Sonnet 4.6: $3 input / $15 output.
+ */
+export declare function costPerMtokInput(model: string): number;
+export declare function costPerMtokOutput(model: string): number;

package/dist/model-picker.js

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Pick Haiku vs Sonnet based on JSON-Schema complexity.
+ *
+ * Why this exists: Haiku 4.5 costs ~3x less ($1/$5 per MTok vs $3/$15)
+ * and is more than adequate for shallow extractions ("price", "title",
+ * "in stock"). Sonnet is worth it for deep / nested schemas where the
+ * model has to reason about more than 1 level of structure.
+ *
+ * Heuristic (intentionally simple — tune from cost_records data later):
+ *   - No schema → no model picked (caller short-circuits to markdown-only).
+ *   - Schema is "flat": top-level object with primitive (string/number/
+ *     boolean) properties only, and no more than MAX_FLAT_PROPS keys.
+ *     Arrays of primitives count as flat. → Haiku.
+ *   - Anything else (nested objects, arrays of objects, deep schemas,
+ *     unbounded `additionalProperties: true` extracts) → Sonnet.
+ *
+ * The model name is part of `extractor_version`, which keys the cross-
+ * customer extraction cache (Review #6). Switching a schema from Sonnet
+ * to Haiku invalidates the cache for that schema — fine; cache misses
+ * just retry under the new model.
+ */
+export const HAIKU_MODEL = 'claude-haiku-4-5-20251001';
+export const SONNET_MODEL_ID = 'claude-sonnet-4-6';
+/** Schemas with more top-level properties than this go to Sonnet. */
+const MAX_FLAT_PROPS = 8;
+export function pickModel(schema) {
+    return pickModelWithReason(schema).model;
+}
+export function pickModelWithReason(schema) {
+    if (!schema)
+        return { model: HAIKU_MODEL, reason: 'haiku_flat_schema' };
+    const topType = schema.type;
+    // We model the typical case: top-level `type: 'object'` with `properties`.
+    // Anything else (anyOf, oneOf, ref-only, array root, etc.) gets Sonnet.
+    if (topType !== 'object')
+        return { model: SONNET_MODEL_ID, reason: 'sonnet_non_object_top' };
+    const properties = schema.properties;
+    if (!properties || typeof properties !== 'object' || Array.isArray(properties)) {
+        // Object without a properties block (or with `additionalProperties: true`
+        // and no shape) → free-form extraction, Sonnet handles better.
+        return { model: SONNET_MODEL_ID, reason: 'sonnet_unbounded' };
+    }
+    const entries = Object.entries(properties);
+    if (entries.length === 0)
+        return { model: HAIKU_MODEL, reason: 'haiku_flat_schema' };
+    if (entries.length > MAX_FLAT_PROPS) {
+        return { model: SONNET_MODEL_ID, reason: 'sonnet_too_many_props' };
+    }
+    for (const [, propRaw] of entries) {
+        if (!propRaw || typeof propRaw !== 'object')
+            continue;
+        const prop = propRaw;
+        const t = prop.type;
+        if (t === 'string' || t === 'number' || t === 'integer' || t === 'boolean' || t === 'null') {
+            continue;
+        }
+        if (t === 'array') {
+            const items = prop.items;
+            if (!items || typeof items !== 'object')
+                continue;
+            const itemType = items.type;
+            // Array of primitives = still flat. Array of objects = not flat.
+            if (itemType === 'object') {
+                return { model: SONNET_MODEL_ID, reason: 'sonnet_array_of_objects' };
+            }
+            continue;
+        }
+        if (t === 'object') {
+            // Nested object → Sonnet.
+            return { model: SONNET_MODEL_ID, reason: 'sonnet_nested' };
+        }
+        // Unknown type, anyOf, oneOf, $ref, enum-only, etc. — bail to Sonnet.
+        return { model: SONNET_MODEL_ID, reason: 'sonnet_default' };
+    }
+    return { model: HAIKU_MODEL, reason: 'haiku_flat_schema' };
+}
+/**
+ * Cost per million input tokens, in dollars. Pricing as of late 2025.
+ * Haiku 4.5: $1 input / $5 output. Sonnet 4.6: $3 input / $15 output.
+ */
+export function costPerMtokInput(model) {
+    return model === HAIKU_MODEL ? 1 : 3;
+}
+export function costPerMtokOutput(model) {
+    return model === HAIKU_MODEL ? 5 : 15;
+}
+//# sourceMappingURL=model-picker.js.map

package/dist/model-picker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-picker.js","sourceRoot":"","sources":["../src/model-picker.ts"],"names":[],"mappings":"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"}

package/dist/pdf.d.ts

@@ -0,0 +1,42 @@
+/**
+ * PDF text extraction (Phase A.3).
+ *
+ * Pulls plain text out of a PDF buffer using pdfjs-dist. Returns a
+ * single string with one blank line between pages. Whitespace inside
+ * each page is preserved roughly as PDF-defined (pdfjs gives us text
+ * "items" with positions; we join with spaces + newlines on
+ * y-coordinate transitions).
+ *
+ * Output is markdown-ish (just text — no headings or tables detected).
+ * That's intentionally minimal — most customers using PDF input want
+ * the text content, not a faithful layout reconstruction.
+ *
+ * pdfjs-dist's ESM build runs in Node 18+; we use the legacy build
+ * which is the more reliable Node story for v5.x.
+ */
+export interface PdfExtractOptions {
+    /** Stop after this many pages. Default 1000. */
+    maxPages?: number;
+    /** Stop once accumulated text exceeds this many bytes. Default 10 MiB. */
+    maxTextBytes?: number;
+}
+export interface PdfExtractionResult {
+    /** Concatenated text content, one blank line per page boundary. */
+    text: string;
+    /** Pages in the document (may exceed the number actually extracted). */
+    numPages: number;
+    /** True when extraction stopped early at the page or byte cap. */
+    truncated?: boolean;
+}
+/**
+ * Extract text from a PDF buffer. Throws on malformed PDF. Bounded by
+ * `maxPages` + `maxTextBytes` so a pathologically large PDF degrades to a
+ * truncated result instead of exhausting worker memory.
+ */
+export declare function extractPdfText(buffer: Buffer | Uint8Array, options?: PdfExtractOptions): Promise<PdfExtractionResult>;
+/**
+ * Detect a PDF from URL extension or content-type. URL check is a
+ * cheap pre-filter; content-type is the source of truth post-fetch.
+ */
+export declare function looksLikePdfByUrl(url: string): boolean;
+export declare function isPdfContentType(contentType: string | undefined): boolean;

package/dist/pdf.js

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * PDF text extraction (Phase A.3).
+ *
+ * Pulls plain text out of a PDF buffer using pdfjs-dist. Returns a
+ * single string with one blank line between pages. Whitespace inside
+ * each page is preserved roughly as PDF-defined (pdfjs gives us text
+ * "items" with positions; we join with spaces + newlines on
+ * y-coordinate transitions).
+ *
+ * Output is markdown-ish (just text — no headings or tables detected).
+ * That's intentionally minimal — most customers using PDF input want
+ * the text content, not a faithful layout reconstruction.
+ *
+ * pdfjs-dist's ESM build runs in Node 18+; we use the legacy build
+ * which is the more reliable Node story for v5.x.
+ */
+// pdfjs-dist's Node usage requires the legacy build entrypoint. Dynamic
+// import so the heavyweight module isn't loaded at startup.
+let pdfjsModule = null;
+async function getPdfJs() {
+    if (!pdfjsModule) {
+        pdfjsModule = await import('pdfjs-dist/legacy/build/pdf.mjs');
+    }
+    return pdfjsModule;
+}
+/** Bounds so a huge / decompression-bomb PDF can't OOM or hang a worker. */
+const DEFAULT_MAX_PAGES = 1000;
+const DEFAULT_MAX_TEXT_BYTES = 10 * 1024 * 1024; // 10 MiB of extracted text
+/**
+ * Extract text from a PDF buffer. Throws on malformed PDF. Bounded by
+ * `maxPages` + `maxTextBytes` so a pathologically large PDF degrades to a
+ * truncated result instead of exhausting worker memory.
+ */
+export async function extractPdfText(buffer, options = {}) {
+    const maxPages = options.maxPages ?? DEFAULT_MAX_PAGES;
+    const maxTextBytes = options.maxTextBytes ?? DEFAULT_MAX_TEXT_BYTES;
+    const pdfjs = await getPdfJs();
+    const data = buffer instanceof Buffer ? new Uint8Array(buffer) : buffer;
+    const doc = await pdfjs.getDocument({ data, useSystemFonts: true }).promise;
+    const numPages = doc.numPages;
+    const pageLimit = Math.min(numPages, maxPages);
+    let truncated = numPages > maxPages;
+    let totalBytes = 0;
+    const pageTexts = [];
+    try {
+        for (let pageNum = 1; pageNum <= pageLimit; pageNum++) {
+            const page = await doc.getPage(pageNum);
+            const content = await page.getTextContent();
+            const pageText = joinTextItems(content.items);
+            pageTexts.push(pageText);
+            totalBytes += Buffer.byteLength(pageText, 'utf8');
+            if (totalBytes > maxTextBytes) {
+                truncated = true;
+                break;
+            }
+        }
+    }
+    finally {
+        await doc.destroy();
+    }
+    return {
+        text: pageTexts.join('\n\n'),
+        numPages,
+        ...(truncated ? { truncated: true } : {}),
+    };
+}
+/**
+ * Heuristic: walk items in document order, join with space; insert a
+ * newline when the next item's y-coordinate jumps by more than the
+ * current item's height (i.e. line break).
+ */
+function joinTextItems(items) {
+    let out = '';
+    let prevY = null;
+    for (const it of items) {
+        if (!it.str)
+            continue;
+        const y = it.transform?.[5];
+        if (prevY !== null && typeof y === 'number' && Math.abs(prevY - y) > it.height) {
+            out += '\n';
+        }
+        else if (out.length > 0 && !out.endsWith('\n')) {
+            out += ' ';
+        }
+        out += it.str;
+        if (typeof y === 'number')
+            prevY = y;
+    }
+    return out.trim();
+}
+/**
+ * Detect a PDF from URL extension or content-type. URL check is a
+ * cheap pre-filter; content-type is the source of truth post-fetch.
+ */
+export function looksLikePdfByUrl(url) {
+    try {
+        const path = new URL(url).pathname.toLowerCase();
+        return path.endsWith('.pdf');
+    }
+    catch {
+        return false;
+    }
+}
+export function isPdfContentType(contentType) {
+    if (!contentType)
+        return false;
+    return /^application\/pdf\b/i.test(contentType);
+}
+//# sourceMappingURL=pdf.js.map

package/dist/pdf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pdf.js","sourceRoot":"","sources":["../src/pdf.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C;;;;;;;;;;;;;;;GAeG;AAWH,wEAAwE;AACxE,4DAA4D;AAC5D,IAAI,WAAW,GAA4D,IAAI,CAAC;AAChF,KAAK,UAAU,QAAQ;IACrB,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,WAAW,GAAG,MAAM,MAAM,CAAC,iCAAiC,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,4EAA4E;AAC5E,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAC/B,MAAM,sBAAsB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,2BAA2B;AAkB5E;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAA2B,EAC3B,UAA6B,EAAE;IAE/B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,iBAAiB,CAAC;IACvD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,sBAAsB,CAAC;IACpE,MAAM,KAAK,GAAG,MAAM,QAAQ,EAAE,CAAC;IAC/B,MAAM,IAAI,GAAG,MAAM,YAAY,MAAM,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACxE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC;IAC5E,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;IAE9B,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/C,IAAI,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,IAAI,CAAC;QACH,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,SAAS,EAAE,OAAO,EAAE,EAAE,CAAC;YACtD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACxC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,cAAc,EAAE,CAAC;YAC5C,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,KAAmB,CAAC,CAAC;YAC5D,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,UAAU,IAAI,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;YAClD,IAAI,UAAU,GAAG,YAAY,EAAE,CAAC;gBAC9B,SAAS,GAAG,IAAI,CAAC;gBACjB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,GAAG,CAAC,OAAO,EAAE,CAAC;IACtB,CAAC;IAED,OAAO;QACL,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC;QAC5B,QAAQ;QACR,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,KAAiB;IACtC,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,IAAI,KAAK,GAAkB,IAAI,CAAC;IAChC,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,IAAI,CAAC,EAAE,CAAC,GAAG;YAAE,SAAS;QACtB,MAAM,CAAC,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5B,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC;YAC/E,GAAG,IAAI,IAAI,CAAC;QACd,CAAC;aAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACjD,GAAG,IAAI,GAAG,CAAC;QACb,CAAC;QACD,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC;QACd,IAAI,OAAO,CAAC,KAAK,QAAQ;YAAE,KAAK,GAAG,CAAC,CAAC;IACvC,CAAC;IACD,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,WAA+B;IAC9D,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAC/B,OAAO,sBAAsB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAClD,CAAC"}

package/dist/readability.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Mozilla Readability + Turndown pipeline (Review #6).
+ *
+ * Pulls the "main content" from an HTML page (sidebar/nav/ads stripped),
+ * then converts to GitHub-Flavored Markdown for downstream consumption.
+ *
+ * Readability is the same library Firefox Reader View uses — battle-tested
+ * across millions of articles. It's not perfect (especially on
+ * non-article pages like pricing tables or app dashboards), but it's the
+ * established baseline. Site-specific overrides land in host_extractors
+ * (chunk M14-17).
+ *
+ * Robustness contract (perf-extract): `extractMarkdown` NEVER throws and
+ * NEVER builds a DOM for input that could OOM or stack-overflow the
+ * process. Pathological inputs (oversized bodies, binary blobs, 2500+-deep
+ * nesting) degrade to a bounded tag-strip and report WHY via the
+ * `degraded` field — see guards.ts for the measured ceilings.
+ */
+import { type DegradeReason, type ExtractDegradeInfo } from './guards.js';
+export declare const READABILITY_VERSION: "readability-v3";
+export type { DegradeReason, ExtractDegradeInfo };
+export interface ExtractedMarkdown {
+    /** Page title from Readability (or null if not detected). */
+    title: string | null;
+    /** Markdown body — main content only, GFM-style. */
+    markdown: string;
+    /** Plain-text body (Readability's textContent), markdown-free. */
+    text: string | null;
+    /** Plain-text excerpt — useful for LLM context windows that prefer text. */
+    excerpt: string | null;
+    /** Detected byline / author if Readability found one. */
+    byline: string | null;
+    /** Detected publication site name. */
+    siteName: string | null;
+    /** Number of characters in `markdown` (post-conversion). */
+    length: number;
+    /**
+     * Present when the extractor degraded instead of running the full
+     * pipeline (or capped part of it). Absent on a clean extraction.
+     * Additive + optional: existing consumers destructure individual fields
+     * and are unaffected.
+     */
+    degraded?: ExtractDegradeInfo;
+}
+/**
+ * Extract main-content markdown from an HTML string.
+ *
+ * `url` is the source URL — used by Readability to resolve relative
+ * links + by Turndown for absolute-URL preservation. Pass the
+ * canonicalized URL (so the resolved hrefs in the markdown are stable
+ * across re-fetches).
+ *
+ * Never throws: binary input, oversized bodies (> MAX_EXTRACT_HTML_CHARS),
+ * pathologically deep markup, and any parse failure degrade to a bounded
+ * iterative plain-text strip instead of propagating — with the cause
+ * reported in `degraded`. The contract is "garbage in, best-effort text
+ * out" — callers can treat the result as always-present.
+ */
+export declare function extractMarkdown(html: string, url: string, opts?: {
+    recoverTables?: boolean;
+}): ExtractedMarkdown;