@okrapdf/runtime 0.5.0 → 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 OkraPDF
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,9 @@
 # @okrapdf/runtime
 
-Upload a PDF, get an API. That URL has REST endpoints for pages, entities, search, AI completion, SQL queries, and analytics.
+Upload a PDF, get an API. Pages, entities, search, AI completion, structured output — all from one URL.
+
+[![npm](https://img.shields.io/npm/v/@okrapdf/runtime)](https://www.npmjs.com/package/@okrapdf/runtime)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
 ## Install
 
@@ -11,12 +14,11 @@ npm install @okrapdf/runtime
 ## Quick Start
 
 ```ts
-import { OkraPDF } from '@okrapdf/runtime';
-import { z } from 'zod';
+import { OkraClient } from '@okrapdf/runtime';
 
-const okra = new OkraPDF({ apiKey: process.env.OKRA_API_KEY });
+const okra = new OkraClient({ apiKey: process.env.OKRA_API_KEY });
 
-// Upload
+// Upload and wait
 const doc = await okra.upload('./report.pdf');
 await okra.wait(doc.id);
 
@@ -24,9 +26,16 @@ await okra.wait(doc.id);
 const pages = await okra.pages(doc.id);
 
 // Ask questions
-const answer = await okra.ask(doc.id, 'What was Q3 revenue?');
+const { answer } = await okra.generate(doc.id, 'What was Q3 revenue?');
+```
+
+## Structured Output
+
+Pass a Zod schema, get typed data back.
+
+```ts
+import { z } from 'zod';
 
-// Structured output — pass a Zod schema, get typed data
 const Invoice = z.object({
   vendor: z.string(),
   total: z.number(),
@@ -36,24 +45,144 @@ const Invoice = z.object({
   })),
 });
 
-const result = await okra.structuredOutput(doc.id, Invoice, {
-  query: 'Extract invoice fields',
+const result = await okra.generate(doc.id, 'Extract invoice fields', {
+  schema: Invoice,
 });
 console.log(result.data.vendor); // fully typed
 ```
 
+## OpenAI-Compatible Endpoint
+
+Every document becomes an OpenAI-compatible model. Works with any AI SDK.
+
+```ts
+import { createOpenAI } from '@ai-sdk/openai';
+import { generateText, generateObject } from 'ai';
+
+const provider = createOpenAI({
+  baseURL: okra.modelEndpoint(doc.id),
+  apiKey: 'okra_...',
+});
+
+// Vercel AI SDK
+const { text } = await generateText({
+  model: provider('default'),
+  prompt: 'What was revenue?',
+});
+
+// Structured output
+const { object } = await generateObject({
+  model: provider('default'),
+  schema: Invoice,
+  prompt: 'Extract invoice fields',
+});
+```
+
+Also works with OpenAI SDK directly:
+
+```ts
+import OpenAI from 'openai';
+
+const openai = new OpenAI({
+  baseURL: okra.modelEndpoint(doc.id),
+  apiKey: 'okra_...',
+});
+
+const chat = await openai.chat.completions.create({
+  model: 'default',
+  messages: [{ role: 'user', content: 'Summarize' }],
+});
+```
+
+## Streaming
+
+```ts
+for await (const event of okra.stream(doc.id, 'Summarize this document')) {
+  if (event.type === 'text_delta') process.stdout.write(event.text);
+  if (event.type === 'done') console.log('\nCost:', event.costUsd);
+}
+```
+
+## Multi-Document
+
+```ts
+// Fan-out query across multiple documents
+const result = await okra.generate(
+  ['doc_a', 'doc_b', 'doc_c'],
+  'Compare revenue across all filings',
+);
+```
+
 ## URL Builder
 
-Cloudinary for documents — every property is a CDN-cacheable URL.
+Cloudinary-style — every property is a URL.
 
 ```tsx
-import { okraPdf } from '@okrapdf/runtime';
+import { doc } from '@okrapdf/runtime';
+
+const d = doc('doc_7fK3x', { fileName: 'annual-report.pdf' });
+
+<Image src={d.thumbnail.url()} alt="Report cover" />
+<Image src={d.pages[3].image.url()} />
+<a href={d.entities.tables[0].url({ format: 'csv' })}>Download CSV</a>
+```
 
-const doc = okraPdf('doc_7fK3x');
+When `fileName` is provided, URLs become mime-explicit aliases:
+`/.../annual-report_ab12cd.json`, `.../annual-report_ab12cd.png`, `.../annual-report_ab12cd.md`.
 
-<Image src={doc.thumbnail.url()} alt="Report cover" />
-<Image src={doc.pages[3].image.url()} />
-<a href={doc.entities.tables[0].url({ format: 'csv' })}>Download CSV</a>
+### Browser Usage (No Node Imports)
+
+Use the URL-builder-only entrypoint in browser code:
+
+```ts
+import { doc } from '@okrapdf/runtime/doc';
+```
+
+Or use a CDN module/global:
+
+```html
+<script type="module">
+  import { doc } from 'https://cdn.jsdelivr.net/npm/@okrapdf/runtime/dist/browser.js';
+  const d = doc('ocr-7fK3x');
+  console.log(d.pages[1].markdown.url());
+</script>
+```
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@okrapdf/runtime/dist/browser.js"></script>
+<script>
+  const d = window.OkraRuntime.doc('ocr-7fK3x');
+  console.log(d.thumbnail.url());
+</script>
+```
+
+## Provider Transformations
+
+Same document, different extraction providers — visible in the URL. Like Cloudinary's `/w_300/image.jpg`, OkraPDF uses `/t_{provider}/` to select the extraction source.
+
+```ts
+import { doc } from '@okrapdf/runtime';
+
+const d = doc('doc_7fK3x', { provider: 'llamaparse' });
+
+d.pages[1].markdown.url()
+// → /v1/documents/doc_7fK3x/t_llamaparse/pages/1/markdown
+
+d.entities.tables.url({ format: 'csv' })
+// → /v1/documents/doc_7fK3x/t_llamaparse/entities/tables?format=csv
+```
+
+Compare providers side-by-side:
+
+```ts
+const d = doc('doc_7fK3x');
+
+// Same page, different providers, different output formats
+d.pages[1].url()                                          // default provider
+d.url({ provider: 'googleocr', format: 'json' })          // Google DocAI → JSON blocks
+d.url({ provider: 'llamaparse', format: 'markdown' })     // LlamaParse → markdown
+d.url({ provider: 'unstructured', format: 'html' })       // Unstructured → HTML (canonical)
+d.url({ provider: 'docling', format: 'markdown' })        // Docling → markdown
 ```
 
 ## Provider Abstraction
@@ -70,36 +199,59 @@ const okra = createOkra({
 });
 ```
 
-## Agent Sandbox
+## curl Equivalents
 
-Scope tool access to specific documents:
+```bash
+# Upload
+curl -X POST https://api.okrapdf.com/document/my-doc/upload \
+  -H "Authorization: Bearer okra_..." \
+  -H "Content-Type: application/pdf" \
+  --data-binary @report.pdf
 
-```ts
-const tools = okra.sandbox({
-  docs: [doc1.id, doc2.id],
-  capabilities: ['read', 'query'],
-});
+# Status
+curl https://api.okrapdf.com/document/my-doc/status \
+  -H "Authorization: Bearer okra_..."
+
+# Pages
+curl https://api.okrapdf.com/document/my-doc/pages \
+  -H "Authorization: Bearer okra_..."
 
-// MCP-compatible
-const mcpTools = tools.asMcp();
+# Completion
+curl -X POST https://api.okrapdf.com/document/my-doc/completion \
+  -H "Authorization: Bearer okra_..." \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "What was revenue?"}'
 ```
 
-## Streaming Completion
+## Full API
 
-```ts
-for await (const event of okra.complete(doc.id, 'Summarize this document')) {
-  if (event.type === 'text_delta') process.stdout.write(event.text);
-  if (event.type === 'done') console.log('\nCost:', event.costUsd);
-}
+```
+upload(path | url | buffer)     Upload a document
+wait(id)                        Poll until extraction complete
+status(id)                      Check processing status
+pages(id)                       Get all pages as markdown
+page(id, num)                   Get single page
+entities(id, { type })          Get extracted entities (tables, figures, etc.)
+query(id, sql)                  Run SQL against document SQLite
+generate(id, prompt)            AI Q&A (non-streaming)
+generate(id, prompt, { schema })  Structured output with Zod/JSON schema
+stream(id, prompt)              Streaming completion
+modelEndpoint(id)               OpenAI-compatible base URL
+publish(id)                     Make document publicly accessible
+shareLink(id, options)          Generate share link with permissions
+deploy(ids)                     Create multi-document agent
 ```
 
 ## Self-Host
 
 ```ts
-// worker.ts
 import { handleRequest } from '@okrapdf/runtime/worker';
 
 export default { fetch: handleRequest(env) };
 ```
 
 Same SDK, same code. Only `baseUrl` changes.
+
+## License
+
+MIT

package/dist/browser.d.ts

@@ -0,0 +1,7 @@
+import { doc } from './url.js';
+export { doc };
+declare const _default: {
+    doc: typeof doc;
+};
+export default _default;
+//# sourceMappingURL=browser.d.ts.map

package/dist/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAc/B,OAAO,EAAE,GAAG,EAAE,CAAC;;;;AACf,wBAAuB"}

package/dist/browser.js

@@ -0,0 +1,9 @@
+import { doc } from './url.js';
+const runtimeGlobal = globalThis;
+runtimeGlobal.OkraRuntime = {
+    ...(runtimeGlobal.OkraRuntime || {}),
+    doc,
+};
+export { doc };
+export default { doc };
+//# sourceMappingURL=browser.js.map

package/dist/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAQ/B,MAAM,aAAa,GAAG,UAAkC,CAAC;AACzD,aAAa,CAAC,WAAW,GAAG;IAC1B,GAAG,CAAC,aAAa,CAAC,WAAW,IAAI,EAAE,CAAC;IACpC,GAAG;CACJ,CAAC;AAEF,OAAO,EAAE,GAAG,EAAE,CAAC;AACf,eAAe,EAAE,GAAG,EAAE,CAAC"}

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AskResult, CompletionEvent, CompletionOptions, DocumentStatus, EntitiesResponse, OkraOptions, Page, PublishResult, QueryResult, Sandbox, ShareLinkOptions, ShareLinkResult, SandboxOptions, StructuredOutputOptions, StructuredOutputResult, StructuredSchema, UploadOptions, UploadResult, WaitOptions, AnalyticsResult } from './types.js';
+import type { CompletionEvent, CompletionOptions, DeployOptions, DeployResult, DocumentStatus, EntitiesResponse, GenerateOptions, GenerateResult, OkraOptions, Page, PublishResult, QueryResult, ShareLinkOptions, ShareLinkResult, StructuredSchema, UploadOptions, UploadResult, WaitOptions } from './types.js';
 export declare class OkraClient {
     private readonly baseUrl;
     private readonly apiKey?;
@@ -20,18 +20,18 @@ export declare class OkraClient {
         signal?: AbortSignal;
     }): Promise<EntitiesResponse>;
     query(documentId: string, sql: string, signal?: AbortSignal): Promise<QueryResult>;
-    complete(documentId: string, query: string, options?: CompletionOptions): AsyncGenerator<CompletionEvent>;
-    ask(documentId: string | string[], query: string, signal?: AbortSignal): Promise<AskResult>;
-    structuredOutput<T>(documentId: string, schema: StructuredSchema<T>, options: StructuredOutputOptions): Promise<StructuredOutputResult<T>>;
-    structuredOutput<T>(documentId: string[], schema: StructuredSchema<T>, options: StructuredOutputOptions): Promise<Array<StructuredOutputResult<T>>>;
-    private structuredOutputSingle;
+    stream(documentId: string, query: string, options?: CompletionOptions): AsyncGenerator<CompletionEvent>;
+    generate(documentId: string | string[], query: string, options?: GenerateOptions & {
+        schema?: undefined;
+    }): Promise<GenerateResult>;
+    generate<T>(documentId: string | string[], query: string, options: GenerateOptions & {
+        schema: StructuredSchema<T>;
+    }): Promise<GenerateResult<T>>;
+    private generateStructured;
+    modelEndpoint(documentId: string): string;
     publish(documentId: string, signal?: AbortSignal): Promise<PublishResult>;
     shareLink(documentId: string, options?: ShareLinkOptions): Promise<ShareLinkResult>;
-    analytics(documentId: string, options?: {
-        period?: string;
-        signal?: AbortSignal;
-    }): Promise<AnalyticsResult>;
-    sandbox(options: SandboxOptions): Sandbox;
+    deploy(documentIds: string[], options?: DeployOptions): Promise<DeployResult>;
     private authHeaders;
     private rawRequest;
     private requestJson;

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -68,9 +68,13 @@ export class OkraClient {
         const path = `/document/${encodeURIComponent(documentId)}`;
         const visibility = options.visibility || 'private';
         if (typeof input === 'string' && isHttpUrl(input)) {
+            const urlHeaders = { 'Content-Type': 'application/json' };
+            if (options.vendorKeys) {
+                urlHeaders['X-Vendor-Keys'] = JSON.stringify(options.vendorKeys);
+            }
             const response = await this.requestJson(`${path}/upload-url`, {
                 method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
+                headers: urlHeaders,
                 body: JSON.stringify({
                     url: input,
                     capabilities: options.capabilities,
@@ -101,6 +105,9 @@ export class OkraClient {
         if (options.capabilities) {
             headers['X-Capabilities'] = JSON.stringify(options.capabilities);
         }
+        if (options.vendorKeys) {
+            headers['X-Vendor-Keys'] = JSON.stringify(options.vendorKeys);
+        }
         if (visibility === 'public') {
             headers['X-Visibility'] = 'public';
         }
@@ -130,9 +137,6 @@ export class OkraClient {
             }
             const current = await this.status(documentId, options.signal);
             if (COMPLETE_PHASES.has(current.phase)) {
-                if (options.autoPublish) {
-                    await this.publish(documentId, options.signal);
-                }
                 return current;
             }
             if (TERMINAL_ERROR_PHASES.has(current.phase)) {
@@ -183,8 +187,8 @@ export class OkraClient {
     async query(documentId, sql, signal) {
         return this.requestJson(`/document/${encodeURIComponent(documentId)}/query?select=${encodeURIComponent(sql)}`, { method: 'GET', signal });
     }
-    // ─── Completion (streaming) ──────────────────────────────────────────────
-    async *complete(documentId, query, options) {
+    // ─── Stream (streaming completion) ────────────────────────────────────────
+    async *stream(documentId, query, options) {
         const response = await this.rawRequest(`/document/${encodeURIComponent(documentId)}/completion`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
@@ -235,57 +239,66 @@ export class OkraClient {
             reader.releaseLock();
         }
     }
-    // ─── Ask (non-streaming convenience) ─────────────────────────────────────
-    async ask(documentId, query, signal) {
+    async generate(documentId, query, options) {
         if (Array.isArray(documentId)) {
             // Multi-doc: fan-out and synthesize
-            const results = await Promise.all(documentId.map((id) => this.ask(id, query, signal)));
+            const results = await Promise.all(documentId.map((id) => this.generate(id, query, options)));
             return {
                 answer: results.map((r) => r.answer).join('\n\n'),
                 costUsd: results.reduce((sum, r) => sum + (r.costUsd ?? 0), 0),
             };
         }
-        // Single doc: non-streaming completion
+        // Structured output path
+        if (options?.schema) {
+            return this.generateStructured(documentId, query, options);
+        }
+        // Plain Q&A: non-streaming completion
         const result = await this.requestJson(`/document/${encodeURIComponent(documentId)}/completion`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ prompt: query }),
-            signal,
+            signal: options?.signal,
         });
         return {
             answer: result.answer,
             costUsd: result.usage?.costUsd,
         };
     }
-    async structuredOutput(documentId, schema, options) {
-        if (Array.isArray(documentId)) {
-            return Promise.all(documentId.map((id) => this.structuredOutputSingle(id, schema, options)));
-        }
-        return this.structuredOutputSingle(documentId, schema, options);
-    }
-    async structuredOutputSingle(documentId, schema, options) {
-        if (!options?.query || options.query.trim() === '') {
-            throw new OkraRuntimeError('INVALID_REQUEST', 'structuredOutput requires a non-empty query', 400);
+    async generateStructured(documentId, query, options) {
+        if (!query || query.trim() === '') {
+            throw new OkraRuntimeError('INVALID_REQUEST', 'generate with schema requires a non-empty query', 400);
         }
-        const normalized = normalizeSchema(schema);
+        const normalized = normalizeSchema(options.schema);
         const body = await this.requestJson(`/document/${encodeURIComponent(documentId)}/structured-output`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
-                query: options.query,
+                query,
                 schema: normalized.jsonSchema,
                 ...(options.timeoutMs ? { timeoutMs: options.timeoutMs } : {}),
             }),
             signal: options.signal,
         });
+        let data;
         if (normalized.parser) {
             const parsed = normalized.parser.safeParse(body.data);
             if (!parsed.success) {
                 throw new StructuredOutputError('SCHEMA_VALIDATION_FAILED', 'Client-side schema validation failed for structured output response', 422, parsed.error.issues);
             }
-            return { data: parsed.data, meta: body.meta };
+            data = parsed.data;
         }
-        return body;
+        else {
+            data = body.data;
+        }
+        return {
+            answer: '',
+            data,
+            meta: body.meta,
+        };
+    }
+    // ─── Model Endpoint ──────────────────────────────────────────────────────
+    modelEndpoint(documentId) {
+        return `${this.baseUrl}/v1/documents/${encodeURIComponent(documentId)}`;
     }
     // ─── Publish / Share ────────────────────────────────────────────────────
     async publish(documentId, signal) {
@@ -300,6 +313,7 @@ export class OkraClient {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({
+                role: options?.role,
                 label: options?.label,
                 expiresInMs: options?.expiresInMs,
                 maxViews: options?.maxViews,
@@ -307,99 +321,18 @@ export class OkraClient {
             signal: options?.signal,
         });
     }
-    // ─── Analytics ───────────────────────────────────────────────────────────
-    async analytics(documentId, options) {
-        const params = options?.period ? `?period=${encodeURIComponent(options.period)}` : '';
-        return this.requestJson(`/document/${encodeURIComponent(documentId)}/analytics${params}`, { method: 'GET', signal: options?.signal });
-    }
-    // ─── Sandbox ─────────────────────────────────────────────────────────────
-    sandbox(options) {
-        const capabilities = options.capabilities || ['read', 'query'];
-        const tools = [];
-        if (capabilities.includes('read')) {
-            tools.push({
-                name: 'get_pages',
-                description: `Read page content from documents: ${options.docs.join(', ')}`,
-                parameters: {
-                    type: 'object',
-                    properties: {
-                        document_id: { type: 'string', enum: options.docs },
-                        page_number: { type: 'number' },
-                    },
-                    required: ['document_id'],
-                },
-                execute: async (args) => {
-                    const docId = args.document_id;
-                    if (!options.docs.includes(docId))
-                        throw new Error(`Document ${docId} not in sandbox scope`);
-                    if (args.page_number)
-                        return this.page(docId, args.page_number);
-                    return this.pages(docId);
-                },
-            });
-            tools.push({
-                name: 'get_entities',
-                description: `Get extracted entities (tables, figures, etc.) from documents: ${options.docs.join(', ')}`,
-                parameters: {
-                    type: 'object',
-                    properties: {
-                        document_id: { type: 'string', enum: options.docs },
-                        type: { type: 'string', enum: ['table', 'figure', 'footnote', 'summary', 'signature'] },
-                    },
-                    required: ['document_id'],
-                },
-                execute: async (args) => {
-                    const docId = args.document_id;
-                    if (!options.docs.includes(docId))
-                        throw new Error(`Document ${docId} not in sandbox scope`);
-                    return this.entities(docId, { type: args.type });
-                },
-            });
-        }
-        if (capabilities.includes('query')) {
-            tools.push({
-                name: 'query_sql',
-                description: `Run read-only SQL queries against document data: ${options.docs.join(', ')}`,
-                parameters: {
-                    type: 'object',
-                    properties: {
-                        document_id: { type: 'string', enum: options.docs },
-                        sql: { type: 'string' },
-                    },
-                    required: ['document_id', 'sql'],
-                },
-                execute: async (args) => {
-                    const docId = args.document_id;
-                    if (!options.docs.includes(docId))
-                        throw new Error(`Document ${docId} not in sandbox scope`);
-                    return this.query(docId, args.sql);
-                },
-            });
-        }
-        if (capabilities.includes('complete')) {
-            tools.push({
-                name: 'ask_document',
-                description: `Ask a natural-language question about documents: ${options.docs.join(', ')}`,
-                parameters: {
-                    type: 'object',
-                    properties: {
-                        document_id: { type: 'string', enum: options.docs },
-                        question: { type: 'string' },
-                    },
-                    required: ['document_id', 'question'],
-                },
-                execute: async (args) => {
-                    const docId = args.document_id;
-                    if (!options.docs.includes(docId))
-                        throw new Error(`Document ${docId} not in sandbox scope`);
-                    return this.ask(docId, args.question);
-                },
-            });
-        }
-        return {
-            tools,
-            asMcp: () => tools,
-        };
+    // ─── Deploy (Multi-Doc Agent) ─────────────────────────────────────────────
+    async deploy(documentIds, options) {
+        return this.requestJson('/api/agents/deploy', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                documentIds,
+                name: options?.name,
+                documents: options?.documents,
+            }),
+            signal: options?.signal,
+        });
     }
     // ─── Internal HTTP ───────────────────────────────────────────────────────
     authHeaders() {