@meistrari/tela-sdk-js 1.0.2 → 2.0.0

package/README.md

@@ -7,12 +7,14 @@ The Tela SDK for JavaScript provides a simple and powerful way to interact with
 - [Installation](#installation)
 - [Usage](#usage)
 - [Examples](#examples)
-  - [Simple Completion](#simple-completion)
-  - [Chat Completion](#chat-completion)
-  - [Webhook Completion](#webhook-completion)
-  - [Streaming Completion](#streaming-completion)
-- [API Reference](#api-reference)
-- [Contributing](#contributing)
+  - [Canvas API](#canvas-api)
+    - [Synchronous Execution](#synchronous-execution)
+    - [Asynchronous Execution with Polling](#asynchronous-execution-with-polling)
+    - [Streaming Execution](#streaming-execution)
+    - [Schema Validation](#schema-validation)
+    - [Multiple Files](#multiple-files)
+    - [Webhook Notifications](#webhook-notifications)
+  - [File Handling](#file-handling)
 - [License](#license)
 
 ## Installation
@@ -30,130 +32,252 @@ pnpm add @meistrari/tela-sdk-js
 First, you need to import the SDK and initialize it with your API key:
 
 ```typescript
-import { createTelaClient } from '@meistrari/tela-sdk-js'
+import { TelaSDK } from '@meistrari/tela-sdk-js'
 
-const tela = createTelaClient({ apiKey: 'your-api-key' })
+const tela = new TelaSDK({ apiKey: 'your-api-key' })
 ```
 
 ## Examples
 
-### Simple Completion
+### Canvas API
 
-This example demonstrates how to create a simple completion using a PDF document:
+The Canvas API provides a type-safe way to execute prompts with schema validation and multiple execution modes.
+
+#### Synchronous Execution
+
+Execute a canvas and wait for the complete result:
 
 ```typescript
-import { createTelaClient } from '@meistrari/tela-sdk-js'
-import type { TelaFile } from '@meistrari/tela-sdk-js'
+import { TelaSDK } from '@meistrari/tela-sdk-js'
 
-const tela = createTelaClient({
-    apiKey: process.env.TELA_API_KEY,
+const tela = new TelaSDK({
+    apiKey: 'your-api-key'
 })
 
-async function run() {
-    const completion = await tela.completions.create<{ document: TelaFile }, { fileSummary: string }>({
-        canvasId: process.env.TELA_CANVAS_ID,
-        variables: {
-            document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
-        },
-        stream: false,
-    })
-    console.log(JSON.stringify(completion, null, 2))
-}
-run().catch(console.error)
+// Get canvas with input/output schemas
+const canvas = await tela.canvas.get({
+    id: 'canvas-id',
+    input: schema => schema.object({
+        query: schema.string()
+    }),
+    output: schema => schema.object({
+        result: schema.string()
+    }),
+})
+
+// Execute synchronously - direct result access
+const result = await canvas.execute({ query: 'What is the capital of France?' }).result
+
+console.log(result) // { result: "Paris" }
+
+// Alternative: get execution object for more control
+const execution = await canvas.execute({ query: 'What is the capital of France?' })
+const result2 = await execution.result
 ```
 
-### Chat Completion
+#### Asynchronous Execution with Polling
 
-This example shows how to create a chat completion with a simple message:
+For long-running operations, use async mode with automatic polling:
 
 ```typescript
-import { createTelaClient } from '@meistrari/tela-sdk-js'
-const tela = createTelaClient({
-    apiKey: process.env.TELA_API_KEY,
+const canvas = await tela.canvas.get({
+    id: 'canvas-id',
+    input: schema => schema.object({
+        document: schema.file(),
+        query: schema.string()
+    }),
+    output: schema => schema.object({
+        summary: schema.string()
+    }),
 })
-async function run() {
-    const completion = await tela.completions.create({
-        canvasId: process.env.TELA_CANVAS_ID,
-        messages: [{ role: 'user', content: 'Hello!' }],
-    })
-    console.log(JSON.stringify(completion, null, 2))
-}
-run().catch(console.error)
+
+// Execute asynchronously with polling - direct result access
+const result = await canvas.execute(
+    {
+        document: TelaFile.create(documentBlob, { name: 'report.pdf' }),
+        query: 'Summarize this document'
+    },
+    {
+        async: true,
+        pollingInterval: 1000, // Poll every 1 second
+        pollingTimeout: 60000, // Timeout after 60 seconds
+    }
+).result
+
+console.log(result.summary)
 ```
 
-### Webhook Completion
+#### Streaming Execution
 
-This example demonstrates how to create a completion that sends the result to a webhook URL:
+Stream results as they're generated:
 
 ```typescript
-import { createTelaClient } from '@meistrari/tela-sdk-js'
-
-const tela = createTelaClient({
-    apiKey: process.env.TELA_API_KEY,
+const canvas = await tela.canvas.get({
+    id: 'canvas-id',
+    input: schema => schema.object({
+        prompt: schema.string()
+    }),
+    output: schema => schema.object({
+        response: schema.string()
+    }),
 })
 
-async function run() {
-    const webhook = await tela.completions.create({
-        canvasId: process.env.TELA_CANVAS_ID,
-        variables: {
-            document: tela.createFile('https://www.wmaccess.com/downloads/sample-invoice.pdf'),
-        },
-        webhookUrl: 'https://webhook.site/4294967295',
-        stream: false,
-    })
-    console.log(JSON.stringify(webhook, null, 2))
+// Execute with streaming - direct iteration
+for await (const chunk of canvas.execute(
+    { prompt: 'Write a story about a robot' },
+    { stream: true }
+).result) {
+    process.stdout.write(chunk.response || '')
 }
-run().catch(console.error)
 ```
 
-### Streaming Completion
+#### Schema Validation
 
-This example shows how to handle streaming responses:
+The Canvas API validates your inputs and outputs against the server schema:
 
 ```typescript
-import fs from 'node:fs'
-import { createTelaClient } from '@meistrari/tela-sdk-js'
-import type { TelaFile } from '@meistrari/tela-sdk-js'
-
-const tela = createTelaClient({
-    apiKey: process.env.TELA_API_KEY,
+const canvas = await tela.canvas.get({
+    id: 'canvas-id',
+    input: schema => schema.object({
+        text: schema.string(),
+        file: schema.file(), // TelaFile validator
+        settings: schema.object({
+            temperature: schema.number(),
+            maxTokens: schema.number(),
+        }),
+    }),
+    output: schema => schema.object({
+        analysis: schema.string(),
+        confidence: schema.number(),
+    }),
+    skipSchemaValidation: false, // Enable schema validation warnings during canvas retrieval (default)
 })
 
-const PATH = 'examples/stream/sample-invoice.pdf'
-const fileStream = fs.createReadStream(PATH)
-
-async function run() {
-    const completion = await tela.completions.create<{ document: TelaFile }, { summary: string }>({
-        canvasId: process.env.TELA_CANVAS_ID,
-        variables: {
-            document: tela.createFile(fileStream),
-        },
-        stream: true,
-    })
-    for await (const chunk of completion) {
-        console.log(JSON.stringify(chunk))
+// TypeScript will ensure you provide the correct types
+const result = await canvas.execute({
+    text: 'Analyze this document',
+    file: TelaFile.create(blob, { name: 'data.pdf' }),
+    settings: {
+        temperature: 0.7,
+        maxTokens: 1000,
     }
-}
-run().catch(console.error)
+}).result
+
+// Skip result validation to trust API response without Zod validation
+const resultWithoutValidation = await canvas.execute(
+    {
+        text: 'Analyze this document',
+        file: TelaFile.create(blob, { name: 'data.pdf' }),
+        settings: {
+            temperature: 0.7,
+            maxTokens: 1000,
+        }
+    },
+    {
+        skipResultValidation: true // Skip Zod validation on results, just typecast
+    }
+).result
+```
+
+#### Multiple Files
+
+Process multiple files in a single canvas execution:
+
+```typescript
+const canvas = await tela.canvas.get({
+    id: 'canvas-id',
+    input: schema => schema.object({
+        documents: schema.array(schema.file()),
+        instructions: schema.string()
+    }),
+    output: schema => schema.object({
+        comparison: schema.string()
+    }),
+})
+
+const result = await canvas.execute({
+    documents: [
+        TelaFile.create('https://example.com/doc1.pdf', { range: [0, 5] }),
+        TelaFile.create('https://example.com/doc2.pdf', { range: [0, 5] }),
+        TelaFile.create(localFileBlob, { name: 'doc3.pdf' })
+    ],
+    instructions: 'Compare these documents and identify key differences'
+}).result
+
+console.log(result.comparison)
 ```
 
-## API Reference
+#### Webhook Notifications
 
-### `createTelaClient`
+Receive completion notifications via webhook for async executions:
 
-#### `createTelaClient(options: TelaSDKOptions)`
+```typescript
+const canvas = await tela.canvas.get({
+    id: 'canvas-id',
+    input: schema => schema.object({
+        document: schema.file(),
+        query: schema.string()
+    }),
+    output: schema => schema.object({
+        analysis: schema.string()
+    }),
+})
 
-Creates a new instance of the TelaSDK.
+// Execute with webhook notification - you can still poll if needed
+const result = await canvas.execute(
+    {
+        document: TelaFile.create('https://example.com/large-report.pdf'),
+        query: 'Analyze this report'
+    },
+    {
+        async: true,
+        webhookUrl: 'https://your-server.com/webhook',
+        pollingTimeout: 300000, // 5 minutes
+    }
+).result
+// OR wait for the webhook notification on your server instead of polling
+```
+
+### File Handling
 
-- `options` (TelaSDKOptions): Configuration options for the SDK.
+The `TelaFile` API provides flexible file handling with support for various input types:
+
+```typescript
+import { TelaFile } from '@meistrari/tela-sdk-js'
 
-#### `completions.create<CanvasVariables, CanvasStructuredOutput>(params: CompletionCreateParams<CanvasVariables>, opts?: RequestOptions): Promise<CompletionCreateResponse<CanvasStructuredOutput>>`
+// From a Blob or File
+const fileFromBlob = TelaFile.create(blob, { name: 'custom.pdf' })
 
-Creates a chat completion with various input options and response formats.
+// From a URL
+const fileFromUrl = TelaFile.create('https://example.com/document.pdf')
 
-- `params` (CompletionCreateParams<CanvasVariables>): The parameters for creating a chat completion.
-- `opts` (RequestOptions): Additional request options.
+// From bytes with explicit MIME type
+const fileFromBytes = TelaFile.create(
+    new Uint8Array(['...']),
+    {
+        mimeType: 'application/pdf',
+        name: 'document.pdf'
+    }
+)
+
+// From a ReadableStream with explicit MIME type
+const fileFromStream = TelaFile.create(
+    readableStream,
+    {
+        mimeType: 'image/jpeg',
+        name: 'photo.jpg'
+    }
+)
 
-## Contributing
+// Vault reference (for files already uploaded)
+const vaultFile = TelaFile.create('vault://file-id')
 
-We welcome contributions to the Tela SDK! Please see our [contributing guide](CONTRIBUTING.md) for more information.
+// With page range for PDFs
+const fileWithRange = TelaFile.create(
+    'https://example.com/document.pdf',
+    {
+        range: [0, 5], // Pages 0-5
+        parserType: 'pdf'
+    }
+)
+```