okrapdf 0.12.1 → 0.14.0

package/README.md

@@ -28,6 +28,17 @@ https://api.okrapdf.com/v1/documents/doc-441a8a0be0e94914b982
 
 This is a full OpenAI-compatible base URL. Plug it into any client.
 
+## Choose Your Entry Point
+
+| I want to... | Start here |
+|---|---|
+| **Use TypeScript/JS** | `okra.sessions.create()` + `session.prompt()` — [SDK Methods](#sdk-methods) |
+| **Use the CLI** | `okra auth login` + `okra upload` — [CLI](#cli) |
+| **Use Claude Code or AI agents** | MCP server — [Setup guide](https://docs.okrapdf.com/integrations/mcp-server) |
+| **Use any LLM client** | OpenAI-compatible endpoint — [OpenAI SDK](#use-with-openai-sdk) |
+| **Build a React app** | `okrapdf/react` hooks — [Sub-path exports](#sub-path-exports) |
+| **Query across documents** | Collections fan-out — [Collections](#collections--fan-out-query-to-csv) |
+
 ## What You Get
 
 Upload a PDF and OkraPDF gives you predictable URLs for everything:
@@ -228,7 +239,7 @@ doc_id,file_name,answer,cost_usd
 "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:
+Experimental: structured collection fan-out is still available via a schema, but it is not part of the stable v0.14 surface:
 
 ```ts
 const FinancialReport = z.object({
@@ -273,11 +284,25 @@ for await (const event of stream) {
 ## CLI
 
 ```bash
-npx okrapdf upload ./invoice.pdf
-npx okrapdf pages doc-abc123
-npx okrapdf chat doc-abc123 "What is the total?"
+npm install -g okrapdf
+okra auth login
+
+okra upload ./invoice.pdf
+okra chat "What is the total?" --doc doc-abc123
+okra extract ./invoice.pdf --schema ./invoice.schema.json
+okra collection query earnings "What changed quarter over quarter?" -o earnings.csv
 ```
 
+Use `npx okrapdf ...` for one-off runs if you do not want a global install.
+
+The default CLI help intentionally focuses on the promoted workflows: auth,
+upload, extract, chat, document read/list/delete, and collection query.
+Advanced inspection and local-only commands still exist, but they are
+intentionally hidden from default help during the clean-house release candidate.
+Experimental structured collection extraction still exists via
+`okra collection extract ...` and `okra collection query ... --schema ...`,
+but it is intentionally not part of the stable v0.14 surface.
+
 ## License
 
 MIT

package/dist/browser.d.ts

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

package/dist/browser.js

@@ -1,6 +1,6 @@
 import {
   doc
-} from "./chunk-QKII53VN.js";
+} from "./chunk-HPTXRSWK.js";
 
 // src/browser.ts
 var runtimeGlobal = globalThis;

package/dist/{chunk-YVUL6ZLA.js → chunk-7BAEYVWG.js}

@@ -1,6 +1,6 @@
 import {
   OkraClient
-} from "./chunk-2HJPTW6S.js";
+} from "./chunk-YGIBZV5J.js";
 
 // src/workflows.ts
 var DEFAULT_WORKFLOW_CAPABILITIES = {
@@ -152,4 +152,4 @@ export {
   withQualityScore,
   withSecret
 };
-//# sourceMappingURL=chunk-YVUL6ZLA.js.map
+//# sourceMappingURL=chunk-7BAEYVWG.js.map

package/dist/{chunk-XOHPZW3V.js → chunk-ETARIBOV.js}

@@ -1,3 +1,12 @@
+import {
+  doctorLocalHarness,
+  findLocalTables,
+  getLocalDocumentStatus,
+  ingestLocalDocument,
+  readLocalPage,
+  searchLocalDocument,
+  summarizeLocalDocument
+} from "./chunk-MSZQPLMQ.js";
 import {
   OkraRuntimeError
 } from "./chunk-NIZM2ETT.js";
@@ -718,6 +727,17 @@ function getApiKeySource() {
 
 // src/cli/commands/auth.ts
 import * as readline from "readline";
+var API_KEY_URL = "https://app.okrapdf.com/settings";
+var DEFAULT_BASE_URL = "https://api.okrapdf.com";
+function writeStdout(message) {
+  process.stdout.write(message + "\n");
+}
+function writeStderr(message) {
+  process.stderr.write(message + "\n");
+}
+function normalizeBaseUrl(baseUrl) {
+  return baseUrl.replace(/\/+$/, "");
+}
 function isLikelyApiKey(value) {
   return value.startsWith("okra_");
 }
@@ -730,6 +750,67 @@ function persistApiKey(apiKey) {
   config.apiKey = apiKey;
   writeGlobalConfig(config);
 }
+function extractErrorMessage(payload) {
+  if (typeof payload === "string" && payload.trim() !== "") return payload;
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return void 0;
+  const record = payload;
+  if (typeof record.error === "string" && record.error.trim() !== "") return record.error;
+  if (typeof record.message === "string" && record.message.trim() !== "") return record.message;
+  return void 0;
+}
+async function parseJsonSafely(response) {
+  const text = await response.text();
+  if (!text.trim()) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+async function verifyApiKey(apiKey) {
+  const baseUrl = normalizeBaseUrl(getBaseUrl() || DEFAULT_BASE_URL);
+  const verifyUrl = `${baseUrl}/auth/verify`;
+  let response;
+  try {
+    response = await fetch(verifyUrl, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${apiKey}` }
+    });
+  } catch (error) {
+    throw new OkraRuntimeError(
+      "HTTP_ERROR",
+      `Could not reach ${verifyUrl} to verify the API key`,
+      503,
+      error
+    );
+  }
+  const payload = await parseJsonSafely(response);
+  if (response.status === 401) {
+    throw new OkraRuntimeError(
+      "UNAUTHORIZED",
+      extractErrorMessage(payload) || "Invalid API key",
+      401,
+      payload
+    );
+  }
+  if (!response.ok) {
+    throw new OkraRuntimeError(
+      "HTTP_ERROR",
+      extractErrorMessage(payload) || `API key verification failed (${response.status})`,
+      response.status || 500,
+      payload
+    );
+  }
+  if (!payload || typeof payload !== "object" || payload.authenticated !== true) {
+    throw new OkraRuntimeError(
+      "INVALID_RESPONSE",
+      "API key verification returned an unexpected response",
+      502,
+      payload
+    );
+  }
+  return payload;
+}
 function prompt(question) {
   const rl = readline.createInterface({
     input: process.stdin,
@@ -742,66 +823,146 @@ function prompt(question) {
     });
   });
 }
+function promptSecret(question) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY || typeof process.stdin.setRawMode !== "function") {
+    return prompt(question);
+  }
+  return new Promise((resolve, reject) => {
+    const stdin = process.stdin;
+    const stdout = process.stdout;
+    const chars = [];
+    const wasRaw = stdin.isRaw === true;
+    const cleanup = () => {
+      stdin.removeListener("data", onData);
+      stdin.setRawMode?.(wasRaw);
+      stdin.pause();
+    };
+    const finish = () => {
+      cleanup();
+      stdout.write("\n");
+      resolve(chars.join("").trim());
+    };
+    const cancel = () => {
+      cleanup();
+      stdout.write("\n");
+      reject(new OkraRuntimeError("INVALID_REQUEST", "Authentication cancelled", 400));
+    };
+    const onData = (chunk) => {
+      const input = typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      for (const char of input) {
+        if (char === "") {
+          cancel();
+          return;
+        }
+        if (char === "\r" || char === "\n") {
+          finish();
+          return;
+        }
+        if (char === "\x7F" || char === "\b") {
+          if (chars.length > 0) chars.pop();
+          continue;
+        }
+        chars.push(char);
+      }
+    };
+    stdout.write(question);
+    stdin.setEncoding("utf8");
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on("data", onData);
+  });
+}
 async function authLogin(providedApiKey) {
   if (providedApiKey) {
     await authSetKey(providedApiKey);
     return;
   }
-  console.log("okra CLI Authentication");
-  console.log("");
-  console.log("Get your API key from: https://app.okrapdf.com/settings");
-  console.log("");
-  const apiKey = await prompt("Enter your API key: ");
+  writeStdout("Okra CLI authentication");
+  writeStdout("");
+  writeStdout("Get your API key at:");
+  writeStdout(`  ${API_KEY_URL}`);
+  writeStdout("");
+  const apiKey = await promptSecret("Enter your API key: ");
   if (!apiKey) {
-    console.error("Error: API key cannot be empty");
+    writeStderr("Error: API key cannot be empty");
     process.exit(1);
   }
   if (!isLikelyApiKey(apiKey)) {
-    console.warn('Warning: API key should start with "okra_"');
+    writeStderr('Warning: API key should start with "okra_"');
   }
+  const verified = await verifyApiKey(apiKey);
   persistApiKey(apiKey);
-  console.log("");
-  console.log(`\u2713 API key saved to ${getGlobalConfigPath()}`);
-  console.log("");
-  console.log("You can now use okra commands without setting OKRA_API_KEY");
+  writeStdout("");
+  writeStdout(`Verified API key for ${verified.user_id}${verified.key_name ? ` (${verified.key_name})` : ""}`);
+  writeStdout(`Saved API key to ${getGlobalConfigPath()}`);
+  writeStdout("");
+  writeStdout("Next:");
+  writeStdout("  okra upload ./report.pdf");
 }
 async function authSetKey(apiKey) {
   const trimmed = apiKey.trim();
   if (!trimmed) {
-    console.error("Error: API key cannot be empty");
+    writeStderr("Error: API key cannot be empty");
     process.exit(1);
   }
   if (!isLikelyApiKey(trimmed)) {
-    console.warn('Warning: API key should start with "okra_"');
+    writeStderr('Warning: API key should start with "okra_"');
   }
+  const verified = await verifyApiKey(trimmed);
   persistApiKey(trimmed);
-  console.log(`\u2713 API key saved to ${getGlobalConfigPath()}`);
+  writeStdout(`Verified API key for ${verified.user_id}${verified.key_name ? ` (${verified.key_name})` : ""}`);
+  writeStdout(`Saved API key to ${getGlobalConfigPath()}`);
 }
 async function authStatus() {
   const apiKey = getApiKey();
   const source = getApiKeySource();
-  console.log("okra CLI Authentication Status");
-  console.log("");
+  writeStdout("Okra CLI authentication status");
+  writeStdout("");
   if (apiKey) {
-    const maskedKey = maskApiKey(apiKey);
-    console.log(`\u2713 Authenticated: ${maskedKey}`);
-    console.log(`  Source: ${source}`);
+    try {
+      const verified = await verifyApiKey(apiKey);
+      const maskedKey = maskApiKey(apiKey);
+      writeStdout(`Authenticated: ${maskedKey}`);
+      writeStdout(`Source: ${source}`);
+      writeStdout(`User: ${verified.user_id}`);
+      if (verified.key_name || verified.key_type) {
+        const name = verified.key_name || "API key";
+        const type = verified.key_type ? ` (${verified.key_type})` : "";
+        writeStdout(`Key: ${name}${type}`);
+      }
+      if (verified.scope) {
+        writeStdout(`Scope: ${verified.scope}`);
+      }
+    } catch (error) {
+      if (error instanceof OkraRuntimeError && error.status === 401) {
+        throw new OkraRuntimeError(
+          "UNAUTHORIZED",
+          `Configured API key is invalid (${maskApiKey(apiKey)} from ${source}). Replace it with \`okra auth login\` or update OKRA_API_KEY.`,
+          401,
+          error
+        );
+      }
+      throw error;
+    }
   } else {
-    console.log("\u2717 Not authenticated");
-    console.log("");
-    console.log("Set API key via:");
-    console.log("  okra auth login");
-    console.log('  export OKRA_API_KEY="okra_xxx"');
-  }
-  console.log("");
+    writeStdout("Not authenticated");
+    writeStdout("");
+    writeStdout("Set an API key with:");
+    writeStdout("  okra auth login");
+    writeStdout('  export OKRA_API_KEY="okra_xxx"');
+    writeStdout("");
+    writeStdout("Get a key at:");
+    writeStdout(`  ${API_KEY_URL}`);
+  }
+  writeStdout("");
 }
 async function authToken() {
   const apiKey = getApiKey();
   if (!apiKey) {
-    console.error("Error: No API key configured");
+    writeStderr("Error: No API key configured");
     process.exit(1);
   }
-  console.log(apiKey);
+  writeStdout(apiKey);
 }
 async function authWhoAmI() {
   await authStatus();
@@ -809,14 +970,14 @@ async function authWhoAmI() {
 async function authLogout() {
   const config = readGlobalConfig();
   if (!config || !config.apiKey) {
-    console.log("No API key found in global config");
+    writeStdout("No API key found in global config");
     return;
   }
   delete config.apiKey;
   writeGlobalConfig(config);
-  console.log(`\u2713 API key removed from ${getGlobalConfigPath()}`);
-  console.log("");
-  console.log("Note: Environment variables and project configs are not affected");
+  writeStdout(`Removed API key from ${getGlobalConfigPath()}`);
+  writeStdout("");
+  writeStdout("Environment variables and project configs are unchanged.");
 }
 
 // src/cli/output.ts
@@ -855,7 +1016,9 @@ function handleError(error, json) {
 // src/cli/commands/upload.ts
 async function upload(client, source, opts) {
   progress(`Uploading ${source}\u2026`, opts.quiet);
-  const session = await client.upload(source);
+  const session = await client.upload(source, {
+    ...opts.vendorOptions ? { vendorOptions: opts.vendorOptions } : {}
+  });
   const docId = session.id;
   progress(`Document ID: ${docId}`, opts.quiet);
   if (opts.noWait) {
@@ -870,7 +1033,7 @@ async function upload(client, source, opts) {
     full_md: `${base}/full.md`,
     page_png: `${base}/d_shimmer/pg_{N}.png`,
     page_md: `${base}/pg_{N}.md`,
-    completion: `https://api.okrapdf.com/document/${docId}/completion`,
+    completion: `https://api.okrapdf.com/v1/documents/${docId}/completion`,
     original: `${base}/original.pdf`
   };
   return {
@@ -881,6 +1044,44 @@ async function upload(client, source, opts) {
   };
 }
 
+// src/cli/commands/list.ts
+async function listDocuments(client, _opts) {
+  const documents = await client.listDocuments();
+  return { documents };
+}
+function formatDocumentList(documents, json) {
+  if (json) {
+    return JSON.stringify(documents);
+  }
+  if (documents.length === 0) {
+    return "No documents found.";
+  }
+  const lines = [];
+  const header = ["ID", "File", "Phase", "Pages", "Created"];
+  lines.push(header.join("	"));
+  lines.push(header.map((h) => "-".repeat(h.length)).join("	"));
+  for (const doc of documents) {
+    lines.push([
+      doc.id,
+      doc.file_name ?? "\u2014",
+      doc.phase,
+      doc.pages_total != null ? String(doc.pages_total) : "\u2014",
+      doc.created_at ? new Date(doc.created_at).toLocaleDateString() : "\u2014"
+    ].join("	"));
+  }
+  return lines.join("\n");
+}
+
+// src/cli/commands/delete.ts
+async function deleteDocument(client, documentId, _opts) {
+  return client.deleteDocument(documentId);
+}
+
+// src/cli/commands/read.ts
+async function readDocument(client, documentId, opts) {
+  return client.read(documentId, { pages: opts.pages });
+}
+
 // src/cli/commands/collection.ts
 async function collectionList(client, _opts) {
   return client.collections.list();
@@ -894,6 +1095,65 @@ function formatCollectionList(rows, json) {
   );
   return [header, ...lines].join("\n");
 }
+async function collectionCreate(client, name, opts) {
+  const body = { name };
+  if (opts.description) body.description = opts.description;
+  if (opts.docs) body.document_ids = opts.docs.split(",").map((s) => s.trim());
+  return client.request("/v1/collections", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body)
+  });
+}
+async function collectionShow(client, nameOrId) {
+  return client.request(
+    `/v1/collections/${encodeURIComponent(nameOrId)}`
+  );
+}
+function formatCollectionDetail(detail, json) {
+  if (json) return JSON.stringify(detail);
+  const lines = [
+    `ID:          ${detail.id}`,
+    `Name:        ${detail.name}`,
+    `Description: ${detail.description || "(none)"}`,
+    `Visibility:  ${detail.visibility || "private"}`,
+    `Documents:   ${detail.document_count}`
+  ];
+  if (detail.documents?.length) {
+    lines.push("");
+    lines.push("DOC_ID	FILE	STATUS");
+    for (const d of detail.documents) {
+      lines.push(`${d.id}	${d.file_name || ""}	${d.status || ""}`);
+    }
+  }
+  return lines.join("\n");
+}
+async function collectionDelete(client, nameOrId) {
+  return client.request(
+    `/v1/collections/${encodeURIComponent(nameOrId)}`,
+    { method: "DELETE" }
+  );
+}
+async function collectionAddDocs(client, nameOrId, documentIds) {
+  return client.request(
+    `/v1/collections/${encodeURIComponent(nameOrId)}/documents`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ document_ids: documentIds })
+    }
+  );
+}
+async function collectionRemoveDocs(client, nameOrId, documentIds) {
+  return client.request(
+    `/v1/collections/${encodeURIComponent(nameOrId)}/documents`,
+    {
+      method: "DELETE",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ document_ids: documentIds })
+    }
+  );
+}
 async function collectionSetVisibility(client, nameOrId, visibility) {
   return client.request(
     `/v1/collections/${encodeURIComponent(nameOrId)}`,
@@ -908,8 +1168,13 @@ async function collectionQueryRaw(client, nameOrId, question, opts) {
   progress(`Querying collection "${nameOrId}"\u2026`, opts.quiet);
   let schema;
   if (opts.schema) {
-    const { readFileSync: readFileSync2 } = await import("fs");
-    schema = JSON.parse(readFileSync2(opts.schema, "utf8"));
+    if (typeof opts.schema === "object") {
+      schema = opts.schema;
+    } else {
+      const { readFileSync: readFileSync2 } = await import("fs");
+      const filePath = opts.schema;
+      schema = JSON.parse(readFileSync2(filePath, "utf8"));
+    }
   }
   const stream = client.collections.query(nameOrId, question, {
     ...schema ? { schema } : {}
@@ -925,7 +1190,8 @@ async function collectionQueryRaw(client, nameOrId, question, opts) {
         answer: event.answer ?? "",
         cost_usd: event.usage?.cost_usd ?? 0,
         duration_ms: event.duration_ms ?? 0,
-        error: event.error
+        error: event.error,
+        data: event.data
       });
       progress(
         `  ${event.status === "fulfilled" ? "+" : "!"} ${event.doc_id} (${event.duration_ms}ms)`,
@@ -973,6 +1239,63 @@ function formatCollectionTable(results) {
 function formatQueryJsonl(results) {
   return results.map((r) => JSON.stringify(r)).join("\n");
 }
+function collectDataKeys(results) {
+  const seen = /* @__PURE__ */ new Set();
+  const keys = [];
+  for (const r of results) {
+    if (!r.data) continue;
+    for (const k of Object.keys(r.data)) {
+      if (!seen.has(k)) {
+        seen.add(k);
+        keys.push(k);
+      }
+    }
+  }
+  return keys;
+}
+function formatExtractCsv(results) {
+  const dataKeys = collectDataKeys(results);
+  const header = ["doc_id", ...dataKeys, "cost_usd", "duration_ms"].join(",");
+  const rows = results.filter((r) => r.status === "fulfilled").map((r) => {
+    const dataCols = dataKeys.map((k) => {
+      const v = r.data?.[k];
+      if (v == null) return "";
+      if (typeof v === "string") return csvEscape(v);
+      return String(v);
+    });
+    return [r.doc_id, ...dataCols, r.cost_usd, r.duration_ms].join(",");
+  });
+  return [header, ...rows].join("\n");
+}
+function formatExtractTable(results) {
+  const fulfilled = results.filter((r) => r.status === "fulfilled" && r.data);
+  if (fulfilled.length === 0) return "No results with structured data.";
+  const dataKeys = collectDataKeys(fulfilled);
+  const colHeaders = dataKeys.map((k) => k.toUpperCase());
+  const colWidths = colHeaders.map((h, i) => {
+    const key = dataKeys[i];
+    const maxData = fulfilled.reduce((max, r) => {
+      const v = r.data?.[key];
+      const len = v == null ? 0 : String(v).length;
+      return Math.max(max, len);
+    }, 0);
+    return Math.max(h.length, Math.min(maxData, 40));
+  });
+  const pad = (s, w) => s.length > w ? s.slice(0, w - 1) + "\u2026" : s.padEnd(w);
+  const headerLine = colHeaders.map((h, i) => pad(h, colWidths[i])).join("  ");
+  const rows = fulfilled.map(
+    (r) => dataKeys.map((k, i) => {
+      const v = r.data?.[k];
+      const s = v == null ? "" : String(v);
+      return pad(s, colWidths[i]);
+    }).join("  ")
+  );
+  return [headerLine, ...rows].join("\n");
+}
+function formatExtractJson(results) {
+  const items = results.filter((r) => r.status === "fulfilled").map((r) => ({ doc_id: r.doc_id, data: r.data ?? {} }));
+  return JSON.stringify(items, null, 2);
+}
 async function collectionExport(client, nameOrId, opts) {
   if (opts.zip) {
     progress(`Exporting markdown zip from "${nameOrId}"\u2026`, opts.quiet);
@@ -1003,6 +1326,29 @@ function formatCollectionExportFlat(result) {
   return parts.join("\n");
 }
 
+// src/cli/commands/local.ts
+function localIngest(source, options = {}) {
+  return ingestLocalDocument(source, options.dataDir);
+}
+function localStatus(documentId, options = {}) {
+  return getLocalDocumentStatus(documentId, options.dataDir);
+}
+function localSummary(documentId, options = {}) {
+  return summarizeLocalDocument(documentId, options.dataDir);
+}
+function localSearch(documentId, query, options = {}) {
+  return searchLocalDocument(documentId, query, options.dataDir);
+}
+function localPage(documentId, pageNumber, options = {}) {
+  return readLocalPage(documentId, pageNumber, options.dataDir);
+}
+function localTables(documentId, query, options = {}) {
+  return findLocalTables(documentId, query, options.dataDir);
+}
+function localDoctor(options = {}) {
+  return doctorLocalHarness(options.dataDir);
+}
+
 export {
   tree,
   formatTreeOutput,
@@ -1045,14 +1391,34 @@ export {
   progress,
   handleError,
   upload,
+  listDocuments,
+  formatDocumentList,
+  deleteDocument,
+  readDocument,
   collectionList,
   formatCollectionList,
+  collectionCreate,
+  collectionShow,
+  formatCollectionDetail,
+  collectionDelete,
+  collectionAddDocs,
+  collectionRemoveDocs,
   collectionSetVisibility,
   collectionQueryRaw,
   formatCollectionCsv,
   formatCollectionTable,
   formatQueryJsonl,
+  formatExtractCsv,
+  formatExtractTable,
+  formatExtractJson,
   collectionExport,
-  formatCollectionExportFlat
+  formatCollectionExportFlat,
+  localIngest,
+  localStatus,
+  localSummary,
+  localSearch,
+  localPage,
+  localTables,
+  localDoctor
 };
-//# sourceMappingURL=chunk-XOHPZW3V.js.map
+//# sourceMappingURL=chunk-ETARIBOV.js.map