okrapdf 0.13.0 → 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-D2JaySEg.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-KJMV6TN2.js → chunk-7BAEYVWG.js}

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

package/dist/{chunk-F3LECDPP.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"');
+    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}`);
   }
-  console.log("");
+  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 {
@@ -932,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)}`,
@@ -1104,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,
@@ -1152,6 +1397,12 @@ export {
   readDocument,
   collectionList,
   formatCollectionList,
+  collectionCreate,
+  collectionShow,
+  formatCollectionDetail,
+  collectionDelete,
+  collectionAddDocs,
+  collectionRemoveDocs,
   collectionSetVisibility,
   collectionQueryRaw,
   formatCollectionCsv,
@@ -1161,6 +1412,13 @@ export {
   formatExtractTable,
   formatExtractJson,
   collectionExport,
-  formatCollectionExportFlat
+  formatCollectionExportFlat,
+  localIngest,
+  localStatus,
+  localSummary,
+  localSearch,
+  localPage,
+  localTables,
+  localDoctor
 };
-//# sourceMappingURL=chunk-F3LECDPP.js.map
+//# sourceMappingURL=chunk-ETARIBOV.js.map