okrapdf 0.11.0 → 0.12.1

package/README.md

@@ -0,0 +1,283 @@
+# okrapdf
+
+Upload a PDF, get an OpenAI-compatible endpoint.
+
+```
+npm install okrapdf
+```
+
+Get your API key at [app.okrapdf.com/settings](https://app.okrapdf.com/settings).
+
+## Quick Start
+
+```ts
+import { OkraClient } from 'okrapdf';
+
+const okra = new OkraClient({ apiKey: process.env.OKRA_API_KEY });
+const session = await okra.sessions.create('./invoice.pdf');
+
+// Every document gets its own chat/completions URL
+console.log(session.modelEndpoint);
+```
+
+That prints a URL like:
+
+```
+https://api.okrapdf.com/v1/documents/doc-441a8a0be0e94914b982
+```
+
+This is a full OpenAI-compatible base URL. Plug it into any client.
+
+## What You Get
+
+Upload a PDF and OkraPDF gives you predictable URLs for everything:
+
+```
+Document:   doc-441a8a0be0e94914b982
+
+Completion: https://api.okrapdf.com/document/doc-441a8a0be0e94914b982/chat/completions
+Status:     https://api.okrapdf.com/document/doc-441a8a0be0e94914b982/status
+Pages:      https://api.okrapdf.com/document/doc-441a8a0be0e94914b982/pages
+Entities:   https://api.okrapdf.com/document/doc-441a8a0be0e94914b982/nodes
+Download:   https://api.okrapdf.com/document/doc-441a8a0be0e94914b982/download
+
+Page images:
+  pg 1:     https://api.okrapdf.com/v1/documents/doc-441a8a0be0e94914b982/pg_1.png
+  resized:  https://api.okrapdf.com/v1/documents/doc-441a8a0be0e94914b982/w_200,h_300/pg_1.png
+  shimmer:  https://api.okrapdf.com/v1/documents/doc-441a8a0be0e94914b982/d_shimmer/pg_1.png
+```
+
+All URLs are deterministic. Build them from the document ID without calling the API first.
+
+## Use with OpenAI SDK
+
+```ts
+import OpenAI from 'openai';
+
+const openai = new OpenAI({
+  apiKey: process.env.OKRA_API_KEY,
+  baseURL: session.modelEndpoint,  // https://api.okrapdf.com/v1/documents/doc-...
+});
+
+const res = await openai.chat.completions.create({
+  model: 'okra',
+  messages: [{ role: 'user', content: 'What form is this?' }],
+});
+
+console.log(res.choices[0].message.content);
+// → "This is Form W-9 (Request for Taxpayer Identification Number and
+//    Certification), used by entities to collect a taxpayer's TIN..."
+```
+
+## Use with AI SDK
+
+```ts
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+import { generateText } from 'ai';
+
+const provider = createOpenAICompatible({
+  name: 'okra',
+  apiKey: process.env.OKRA_API_KEY,
+  baseURL: session.modelEndpoint,
+});
+
+const { text } = await generateText({
+  model: provider('okra'),
+  prompt: 'Summarize this document in 3 bullet points',
+});
+```
+
+## Use with curl
+
+```bash
+# Upload
+curl -X POST https://api.okrapdf.com/document/doc-my-w9/upload-url \
+  -H "Authorization: Bearer $OKRA_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://www.irs.gov/pub/irs-pdf/fw9.pdf"}'
+
+# Ask a question
+curl https://api.okrapdf.com/document/doc-my-w9/chat/completions \
+  -H "Authorization: Bearer $OKRA_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"messages": [{"role": "user", "content": "List all parts of this form."}]}'
+```
+
+Response:
+
+```json
+{
+  "id": "chatcmpl-18g5qhmmrm",
+  "object": "chat.completion",
+  "model": "accounts/fireworks/models/kimi-k2p5",
+  "choices": [{
+    "message": {
+      "role": "assistant",
+      "content": "Based on the Form W-9 document, there are two numbered parts:\n\n| Part | Title |\n|------|-------|\n| Part I | Taxpayer Identification Number (TIN) |\n| Part II | Certification |"
+    },
+    "finish_reason": "stop"
+  }],
+  "usage": { "prompt_tokens": 227, "completion_tokens": 404, "total_tokens": 631 }
+}
+```
+
+## SDK Methods
+
+The SDK wraps all of this so you don't need a separate client:
+
+```ts
+// Ask a question (non-streaming)
+const { answer } = await session.prompt('What is the total amount due?');
+
+// Stream
+for await (const event of session.stream('Summarize this document')) {
+  if (event.type === 'text_delta') process.stdout.write(event.text);
+}
+
+// Structured output with Zod
+import { z } from 'zod';
+
+const Invoice = z.object({
+  vendor: z.string(),
+  total: z.number(),
+  lineItems: z.array(z.object({
+    description: z.string(),
+    amount: z.number(),
+  })),
+});
+
+const { data } = await session.prompt('Extract the invoice', { schema: Invoice });
+// data: { vendor: "Acme Corp", total: 1250.00, lineItems: [...] }
+```
+
+## Pages & Entities
+
+```ts
+const pages = await session.pages();           // { pageCount: 6, pages: [...] }
+const { nodes } = await session.entities();    // extracted text, tables, etc.
+const { nodes } = await session.entities({ type: 'table' });
+```
+
+## Upload
+
+Accepts file paths, URLs, `Blob`, `ArrayBuffer`, or `Uint8Array`:
+
+```ts
+// URL
+const session = await okra.sessions.create('https://example.com/report.pdf');
+
+// Bytes
+const session = await okra.sessions.create(pdfBytes, {
+  upload: { fileName: 'report.pdf' },
+});
+
+// Attach to existing document (no upload, no wait)
+const session = okra.sessions.from('doc-441a8a0be0e94914b982');
+```
+
+## Deterministic URLs
+
+Build page image and export URLs from a document ID — no API call needed:
+
+```ts
+import { doc } from 'okrapdf/doc';
+
+const d = doc('doc-441a8a0be0e94914b982');
+
+d.pages(1).image();                    // .../pg_1.png
+d.pages(1).image({ w: 200, h: 300 }); // .../w_200,h_300/pg_1.png
+d.export('markdown');                  // .../export.md
+```
+
+## Collections — Fan-Out Query to CSV
+
+Ask the same question across every document in a collection. Each doc answers independently in parallel, results stream back as NDJSON.
+
+```ts
+import { OkraClient } from 'okrapdf';
+import { z } from 'zod';
+import { writeFileSync } from 'fs';
+
+const okra = new OkraClient({ apiKey: process.env.OKRA_API_KEY });
+
+// Fan-out: ask every doc in the collection the same question
+const stream = okra.collections.query(
+  'col-40da068481cf4f248853507cba6be611',
+  'Who are the top 3 people mentioned in this document?',
+);
+
+// Gather all results
+const result = await stream.gather();
+
+// Write CSV
+const header = 'doc_id,doc_name,answer,cost_usd';
+const rows = [...result.answers.values()].map(a =>
+  `"${a.docId}","${a.answer.slice(0, 200)}",${a.costUsd}`
+);
+writeFileSync('results.csv', [header, ...rows].join('\n'));
+
+console.log(`${result.completed} docs, $${result.totalCostUsd.toFixed(4)} total`);
+```
+
+Real output from a 10-K earnings collection:
+
+```csv
+doc_id,file_name,answer,cost_usd
+"doc-9a3f21...","NVDA-10K-2025.pdf","Revenue: $130.5B, Net Income: $72.9B, YoY Growth: 114%",0.0048
+"doc-b7e810...","AAPL-10K-2025.pdf","Revenue: $391.0B, Net Income: $101.2B, YoY Growth: 5%",0.0039
+"doc-c4d562...","MSFT-10K-2025.pdf","Revenue: $254.2B, Net Income: $97.1B, YoY Growth: 16%",0.0051
+```
+
+Works with structured output too — pass a Zod schema and each doc extracts typed data:
+
+```ts
+const FinancialReport = z.object({
+  company: z.string(),
+  revenue: z.number(),
+  netIncome: z.number(),
+  quarter: z.string(),
+});
+
+const stream = okra.collections.query(
+  'col-financials',
+  'Extract the financial summary',
+  { schema: FinancialReport },
+);
+
+const result = await stream.gather();
+for (const [docId, answer] of result.answers) {
+  console.log(answer.data); // { company: "NVIDIA", revenue: 35082, ... }
+}
+```
+
+Or stream per-doc events in real time:
+
+```ts
+for await (const event of stream) {
+  if (event.type === 'result') {
+    console.log(`${event.doc_id}: ${event.answer.slice(0, 80)}...`);
+  }
+}
+```
+
+## Sub-path Exports
+
+| Import | Use |
+|--------|-----|
+| `okrapdf` | `OkraClient`, types, errors |
+| `okrapdf/doc` | `doc()` URL builder |
+| `okrapdf/browser` | Browser-safe client (no Node.js deps) |
+| `okrapdf/worker` | Cloudflare Worker adapter |
+| `okrapdf/react` | React hooks (`useSession`, `usePages`) |
+
+## CLI
+
+```bash
+npx okrapdf upload ./invoice.pdf
+npx okrapdf pages doc-abc123
+npx okrapdf chat doc-abc123 "What is the total?"
+```
+
+## License
+
+MIT

package/dist/browser.d.ts

@@ -1,5 +1,5 @@
 import { doc } from './url.js';
-import './types-ZJxBNLTJ.js';
+import './types-DDm2eEL0.js';
 import 'zod';
 
 declare const _default: {

package/dist/{chunk-OVRTURGN.js → chunk-2HJPTW6S.js}

@@ -52,6 +52,18 @@ function inferBlobName(input, fallback) {
   }
   return fallback;
 }
+function toHeaderSafeFileName(fileName) {
+  const leaf = fileName.split(/[\\/]/).pop() || fileName;
+  const cleaned = leaf.replace(/[\r\n]/g, " ").trim();
+  if (/^[\x20-\x7E]+$/.test(cleaned)) {
+    return cleaned;
+  }
+  const extMatch = cleaned.match(/(\.[A-Za-z0-9]{1,10})$/);
+  const extension = extMatch?.[1].toLowerCase() ?? "";
+  const base = extension ? cleaned.slice(0, -extension.length) : cleaned;
+  const asciiBase = base.normalize("NFKD").replace(/[^\x20-\x7E]/g, "").replace(/[^A-Za-z0-9._ -]/g, "_").replace(/\s+/g, "_").replace(/_+/g, "_").replace(/^[._-]+|[._-]+$/g, "");
+  return `${asciiBase || "document"}${extension || ".pdf"}`;
+}
 async function readLocalFileFromNode(inputPath) {
   try {
     const [fsModule, pathModule] = await Promise.all([
@@ -64,9 +76,35 @@ async function readLocalFileFromNode(inputPath) {
       fileName: pathModule.basename(inputPath)
     };
   } catch (error) {
+    const code = typeof error === "object" && error && "code" in error ? String(error.code) : void 0;
+    const msg = error instanceof Error ? error.message : String(error);
+    if (code === "ENOENT") {
+      throw new OkraRuntimeError(
+        "INVALID_REQUEST",
+        `Local file not found: ${inputPath}`,
+        400,
+        error
+      );
+    }
+    if (code === "EACCES" || code === "EPERM") {
+      throw new OkraRuntimeError(
+        "INVALID_REQUEST",
+        `Cannot read local file (${code}): ${inputPath}`,
+        400,
+        error
+      );
+    }
+    if (code === "ERR_MODULE_NOT_FOUND" || code === "ERR_UNKNOWN_BUILTIN_MODULE") {
+      throw new OkraRuntimeError(
+        "INVALID_REQUEST",
+        "Local file path uploads are only supported in Node.js. In browser runtimes, pass File/Blob, ArrayBuffer, Uint8Array, or URL.",
+        400,
+        error
+      );
+    }
     throw new OkraRuntimeError(
       "INVALID_REQUEST",
-      "Local file path uploads are only supported in Node.js. In browser runtimes, pass File/Blob, ArrayBuffer, Uint8Array, or URL.",
+      `Failed to read local file "${inputPath}": ${msg}`,
       400,
       error
     );
@@ -187,7 +225,7 @@ var OkraClient = class {
     }
     if (typeof globalThis !== "undefined" && "window" in globalThis && this.apiKey && !this.apiKey.startsWith("okra_pk_")) {
       console.warn(
-        "[OkraPDF] Secret API key detected in browser. Use a publishable key (okra_pk_...) for client-side usage. See https://docs.okrapdf.dev/api-keys#publishable-keys"
+        "[OkraPDF] Secret API key detected in browser. Use a publishable key (okra_pk_...) for client-side usage. See https://docs.okrapdf.com/api-keys#publishable-keys"
       );
     }
     this.sessions = {
@@ -223,7 +261,9 @@ var OkraClient = class {
     };
     this.collections = {
       list: (signal) => this.collectionList(signal),
-      get: (collectionId, signal) => this.collectionGet(collectionId, signal)
+      get: (collectionId, signal) => this.collectionGet(collectionId, signal),
+      query: (collectionId, prompt, options2) => this.collectionQuery(collectionId, prompt, options2),
+      exportMarkdown: (collectionId, options2) => this.collectionExportMarkdown(collectionId, options2)
     };
   }
   // ─── Collections ────────────────────────────────────────────────────────
@@ -240,6 +280,235 @@ var OkraClient = class {
       { method: "GET", signal }
     );
   }
+  collectionQuery(collectionId, prompt, options) {
+    const ac = new AbortController();
+    if (options?.signal) {
+      options.signal.addEventListener("abort", () => ac.abort(), { once: true });
+    }
+    const body = { prompt, stream: true };
+    if (options?.schema) {
+      const normalized = normalizeSchema(options.schema);
+      body.response_format = {
+        type: "json_schema",
+        json_schema: { name: "result", schema: normalized.jsonSchema }
+      };
+    }
+    if (options?.docIds) {
+      body.doc_ids = options.docIds;
+    }
+    const responsePromise = this.rawRequest(
+      `/v1/collections/${encodeURIComponent(collectionId)}/query`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal: ac.signal
+      }
+    );
+    async function* iterateNdjson() {
+      const response = await responsePromise;
+      if (!response.ok) {
+        const text = await response.text();
+        throw new OkraRuntimeError("HTTP_ERROR", `Collection query failed: ${text}`, response.status);
+      }
+      if (!response.body) {
+        throw new OkraRuntimeError("INVALID_RESPONSE", "No response body for collection query", 500);
+      }
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const lines = buffer.split("\n");
+          buffer = lines.pop() || "";
+          for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+            try {
+              yield JSON.parse(trimmed);
+            } catch {
+            }
+          }
+        }
+        const remaining = buffer.trim();
+        if (remaining) {
+          try {
+            yield JSON.parse(remaining);
+          } catch {
+          }
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    }
+    let iteratorInstance = null;
+    function getIterator() {
+      if (!iteratorInstance) iteratorInstance = iterateNdjson();
+      return iteratorInstance;
+    }
+    const stream = {
+      [Symbol.asyncIterator]() {
+        return getIterator();
+      },
+      async gather() {
+        const startTime = Date.now();
+        const answers = /* @__PURE__ */ new Map();
+        let queryId = "";
+        let queryPrompt = prompt;
+        let totalCostUsd = 0;
+        let completed = 0;
+        let failed = 0;
+        for await (const event of getIterator()) {
+          if (event.type === "start") {
+            queryId = event.query_id;
+            queryPrompt = event.prompt;
+          } else if (event.type === "result") {
+            answers.set(event.doc_id, {
+              docId: event.doc_id,
+              status: event.status,
+              answer: event.answer,
+              data: event.data,
+              costUsd: event.usage?.cost_usd ?? 0,
+              durationMs: event.duration_ms,
+              error: event.error
+            });
+          } else if (event.type === "done") {
+            totalCostUsd = event.total_cost_usd;
+            completed = event.completed;
+            failed = event.failed;
+          } else if (event.type === "error") {
+            throw new OkraRuntimeError("HTTP_ERROR", event.error, 500);
+          }
+        }
+        return {
+          queryId,
+          prompt: queryPrompt,
+          answers,
+          totalCostUsd,
+          durationMs: Date.now() - startTime,
+          completed,
+          failed
+        };
+      },
+      abort() {
+        ac.abort();
+      },
+      toReadableStream() {
+        const encoder = new TextEncoder();
+        const iter = getIterator();
+        return new ReadableStream({
+          async pull(controller) {
+            const { done, value } = await iter.next();
+            if (done) {
+              controller.close();
+            } else {
+              controller.enqueue(encoder.encode(JSON.stringify(value) + "\n"));
+            }
+          },
+          cancel() {
+            ac.abort();
+          }
+        });
+      }
+    };
+    return stream;
+  }
+  // ─── Collection Export (markdown from R2) ────────────────────────────────
+  collectionExportPath(collectionId, format) {
+    return `/v1/collections/${encodeURIComponent(collectionId)}/export?format=${encodeURIComponent(format)}`;
+  }
+  async collectionExportMarkdown(collectionId, options) {
+    let format = "markdown";
+    let signal;
+    if (options && typeof options === "object" && "aborted" in options) {
+      signal = options;
+    } else if (options) {
+      format = options.format ?? "markdown";
+      signal = options.signal;
+    }
+    const response = await this.rawRequest(
+      this.collectionExportPath(collectionId, format),
+      { method: "GET", signal }
+    );
+    if (!response.ok) {
+      const text = await response.text();
+      throw new OkraRuntimeError("HTTP_ERROR", `Collection export failed: ${text}`, response.status);
+    }
+    if (format === "zip") {
+      const body = await response.arrayBuffer();
+      return new Uint8Array(body);
+    }
+    if (!response.body) {
+      throw new OkraRuntimeError("INVALID_RESPONSE", "No response body for collection export", 500);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const documents = [];
+    let totalPages = 0;
+    let collectionName = "";
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          try {
+            const event = JSON.parse(trimmed);
+            if (event.type === "result") {
+              documents.push({
+                docId: event.doc_id,
+                fileName: event.file_name,
+                pageCount: event.page_count,
+                pages: event.pages
+              });
+              totalPages += event.page_count;
+            }
+          } catch {
+          }
+        }
+      }
+      const remaining = buffer.trim();
+      if (remaining) {
+        try {
+          const event = JSON.parse(remaining);
+          if (event.type === "result") {
+            documents.push({
+              docId: event.doc_id,
+              fileName: event.file_name,
+              pageCount: event.page_count,
+              pages: event.pages
+            });
+            totalPages += event.page_count;
+          }
+        } catch {
+        }
+      }
+    } finally {
+      reader.releaseLock();
+    }
+    try {
+      const col = await this.collectionGet(collectionId);
+      collectionName = col.name;
+    } catch {
+      collectionName = collectionId;
+    }
+    return {
+      collectionId,
+      collectionName,
+      documents,
+      totalDocuments: documents.length,
+      totalPages,
+      exportedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
   // ─── Upload ──────────────────────────────────────────────────────────────
   async upload(input, options = {}) {
     const documentId = options.documentId || makeDocId();
@@ -278,7 +547,7 @@ var OkraClient = class {
     }
     const headers = {
       "Content-Type": "application/pdf",
-      "X-File-Name": fileName
+      "X-File-Name": toHeaderSafeFileName(fileName)
     };
     if (options.capabilities) {
       headers["X-Capabilities"] = JSON.stringify(options.capabilities);
@@ -299,6 +568,66 @@ var OkraClient = class {
     });
     return this.sessions.from(documentId);
   }
+  // ─── Workflow Config / Reparse ───────────────────────────────────────────
+  async updateConfig(documentId, update, signal) {
+    if (!documentId.trim()) {
+      throw new OkraRuntimeError("INVALID_REQUEST", "updateConfig requires a non-empty documentId", 400);
+    }
+    return this.requestJson(
+      `/v1/documents/${encodeURIComponent(documentId)}/config`,
+      {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(update),
+        signal
+      }
+    );
+  }
+  async reparse(documentId, options = {}) {
+    if (!documentId.trim()) {
+      throw new OkraRuntimeError("INVALID_REQUEST", "reparse requires a non-empty documentId", 400);
+    }
+    const strategy = options.strategy && options.strategy !== "auto" ? `?strategy=${encodeURIComponent(options.strategy)}` : "";
+    return this.requestJson(
+      `/v1/documents/${encodeURIComponent(documentId)}/reparse${strategy}`,
+      { method: "POST", signal: options.signal }
+    );
+  }
+  async applyWorkflow(documentId, options) {
+    if (!options?.capabilities) {
+      throw new OkraRuntimeError("INVALID_REQUEST", "applyWorkflow requires capabilities", 400);
+    }
+    const config = await this.updateConfig(
+      documentId,
+      { capabilities: options.capabilities },
+      options.signal
+    );
+    if (options.reparse === false) {
+      return { config };
+    }
+    const reparse = await this.reparse(documentId, {
+      strategy: options.strategy,
+      signal: options.signal
+    });
+    return { config, reparse };
+  }
+  async getKeyWorkflow(signal) {
+    return this.requestJson(
+      "/v1/key-workflow",
+      { method: "GET", signal }
+    );
+  }
+  async setKeyWorkflow(defaultCapabilities, signal) {
+    return this.requestJson(
+      "/v1/key-workflow",
+      {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ default_capabilities: defaultCapabilities }),
+        signal
+      }
+    );
+  }
   // ─── Status / Wait ───────────────────────────────────────────────────────
   async status(documentId, signal) {
     return this.requestJson(
@@ -613,4 +942,4 @@ var OkraClient = class {
 export {
   OkraClient
 };
-//# sourceMappingURL=chunk-OVRTURGN.js.map
+//# sourceMappingURL=chunk-2HJPTW6S.js.map