@okrapdf/runtime

Small session-first SDK on top of the OkraPDF HTTP API.

Install

npm install @okrapdf/runtime

SDK Surface

Only two runtime entry points:

• createOkra(...) for document sessions
• doc(...) for deterministic document URLs

Quick Start

import { createOkra } from '@okrapdf/runtime';

const okra = createOkra({ apiKey: process.env.OKRA_API_KEY });

const session = await okra.sessions.create('./report.pdf', {
  wait: true,
  model: 'kimi-k2p5',
});

const { answer } = await session.prompt('What is total revenue?');
console.log(answer);

const stream = session.stream('Summarize in 3 bullets');
for await (const event of stream) {
  if (event.type === 'text_delta') process.stdout.write(event.text);
}

Structured Output (Zod)

import { z } from 'zod';

const Invoice = z.object({
  vendor: z.string(),
  total: z.number(),
});

const result = await session.prompt('Extract invoice fields', {
  schema: Invoice,
});

console.log(result.data?.vendor, result.data?.total);

Share Links (Redacted Viewer vs Full Admin)

const viewer = await session.shareLink({
  role: 'viewer',
  expiresInMs: 24 * 60 * 60 * 1000,
});

const admin = await session.shareLink({
  role: 'admin',
  expiresInMs: 24 * 60 * 60 * 1000,
});

console.log(viewer.links.markdown, viewer.links.pdf);
console.log(admin.links.markdown, admin.links.pdf);

Deterministic URL Builder

import { doc } from '@okrapdf/runtime';

const d = doc(session.id, { fileName: 'report.pdf' });

console.log(d.thumbnail.url());
console.log(d.pages[1].image.url());
console.log(d.entities.tables[0].url({ format: 'csv' }));

curl Contract

The SDK maps directly to these endpoints.

1) Upload URL source

curl -X POST "https://api.okrapdf.com/document/ocr-demo/upload-url" \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/report.pdf",
    "visibility": "private",
    "redact": {
      "pii": {
        "preset": "hipaa",
        "patterns": ["SSN", "EMAIL", "PHONE_US"]
      }
    }
  }'

2) Wait for readiness

curl "https://api.okrapdf.com/document/ocr-demo/status" \
  -H "Authorization: Bearer $OKRA_API_KEY"

Poll until phase is complete (or awaiting_review).

3) Ask a question

curl -X POST "https://api.okrapdf.com/document/ocr-demo/completion" \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What is total revenue?",
    "model": "kimi-k2p5"
  }'

4) Stream tokens

curl -N -X POST "https://api.okrapdf.com/document/ocr-demo/completion" \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Summarize in 3 bullets",
    "stream": true,
    "model": "kimi-k2p5"
  }'

5) Create scoped share links

curl -X POST "https://api.okrapdf.com/document/ocr-demo/share-link" \
  -H "Authorization: Bearer $OKRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "viewer",
    "expiresInMs": 86400000
  }'

Use role: "admin" for full-access links.

Public API

createOkra({ apiKey, baseUrl?, sharedSecret?, fetch? }) => okra

okra.sessions.create(sourceOrDocId, { wait?, model?, upload?, waitOptions? }) => session
okra.sessions.from(docId, { model? }) => session

session.id
session.model
session.modelEndpoint
session.state()
session.setModel(model)
session.status()
session.wait()
session.pages()
session.page(n)
session.entities()
session.query(sql)
session.prompt(query)
session.prompt(query, { schema })
session.stream(query)
session.publish()
session.shareLink({ role, expiresInMs, maxViews, label })

License

MIT