@covia/covia-sdk 1.1.0 → 1.2.0

package/README.md

@@ -4,96 +4,525 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-TypeScript SDK for [Covia.ai](https://covia.ai) - The Universal Grid for AI Orchestration & Multi-Agent Workflows.
+TypeScript SDK for [Covia.ai](https://covia.ai) — The Universal Grid for AI Orchestration & Multi-Agent Workflows.
 
 Covia.ai provides federated execution, cryptographic verification, and shared state management for AI agents across organizations, clouds, and platforms.
 
-## Features
-
-- 🔒 **Type-Safe API** - Full TypeScript support with complete type definitions
-- 🎯 **Asset Management** - Work with Operations and Data Assets through a unified interface
-- 🔄 **Streaming Support** - Built-in support for streaming content and responses
-- 💾 **Intelligent Caching** - Automatic caching for improved performance
-- 🛡️ **Error Handling** - Comprehensive error handling with typed exceptions
-- 🌐 **Federated Execution** - Connect to Covia venues for cross-organizational workflows
-- 📦 **Dual Module Support** - Works with both CommonJS and ES Modules
-
 ## Installation
 
 ```bash
 npm install @covia/covia-sdk
 ```
 
-Or with yarn:
+```bash
+pnpm add @covia/covia-sdk
+```
 
 ```bash
 yarn add @covia/covia-sdk
 ```
 
-Or with pnpm:
+## Quick Start
 
-```bash
-pnpm add @covia/covia-sdk
+```typescript
+import { Grid, KeyPairAuth } from "@covia/covia-sdk";
+
+// Connect to a venue (URL, DNS name, or DID)
+const venue = await Grid.connect("https://venue.covia.ai");
+
+// Or connect with keypair authentication
+const auth = KeyPairAuth.generate();
+const venue = await Grid.connect("did:web:venue.covia.ai", auth);
+
+// Run an operation and get the result
+const result = await venue.operations.run("test:echo", { message: "hello" });
+
+// Invoke an operation asynchronously and track the job
+const job = await venue.operations.invoke("test:echo", { message: "hello" });
+console.log(`Job ${job.id} status: ${job.metadata.status}`);
+const output = await job.result({ timeout: 30000 });
+
+// Work with assets
+const assets = await venue.listAssets();
+const operation = await venue.getAsset("my-operation-id");
+await operation.invoke({ param: "value" });
+
+// Upload data
+const dataAsset = await venue.getAsset("my-data-id");
+await dataAsset.putContent(new Blob(["Hello World"], { type: "text/plain" }));
+const stream = await dataAsset.getContent();
+
+// Clean up
+venue.close();
 ```
 
-## Quick Start
+## Connecting to a Venue
+
+The SDK supports three connection methods:
 
 ```typescript
-import { Grid } from '@covia/covia-sdk';
+import { Grid, Venue, KeyPairAuth, BearerAuth } from "@covia/covia-sdk";
+
+// Via Grid (cached — same ID returns the same Venue instance)
+const venue = await Grid.connect("https://venue.covia.ai");
+const venue = await Grid.connect("did:web:venue.covia.ai");
+const venue = await Grid.connect("venue.covia.ai"); // DNS name → https://
+
+// Via Venue directly (no caching)
+const venue = await Venue.connect("https://venue.covia.ai");
+```
 
-// Connect to a venue
-const venue = await Grid.connect("venue-did");
+### Authentication
 
-// Get assets (returns Operation or DataAsset based on metadata)
-const operation = await venue.getAsset('op-id');
-const dataAsset = await venue.getAsset('data-id');
+```typescript
+// No auth (default)
+const venue = await Grid.connect("https://venue.covia.ai");
+
+// Ed25519 keypair (self-issued JWT per request)
+const auth = KeyPairAuth.generate();
+console.log(auth.getDID()); // did:key:z6Mk...
+const venue = await Grid.connect("https://venue.covia.ai", auth);
 
-// Invoke an operation
-await operation.invoke({ param: 'value' });
+// From a saved private key
+const auth = KeyPairAuth.fromHex("abcdef1234...");
 
-// Upload data to a data asset
-await dataAsset.uploadContent(content);
+// Bearer token
+const auth = new BearerAuth("my-api-token");
+const venue = await Grid.connect("https://venue.covia.ai", auth);
 ```
 
-## Requirements
+## API Reference
 
-- Node.js >= 18.0.0
-- TypeScript >= 5.0.0 (for TypeScript users)
+### Venue
 
-## TypeScript Support
+The `Venue` is the primary entry point. All domain-specific functionality is accessed through manager objects.
 
-`@covia/covia-sdk` is written in TypeScript and ships with full type declarations. No `@types/` package is needed.
+```typescript
+venue.baseUrl;    // string — the venue's base URL
+venue.venueId;    // string — the venue's DID
+venue.metadata;   // { name, description }
+```
+
+| Method | Description |
+|---|---|
+| `venue.status()` | Get venue status (health, stats) |
+| `venue.getAsset(assetId)` | Get an asset by ID (returns `Operation` or `DataAsset`) |
+| `venue.listAssets(options?)` | List assets with pagination (`{ offset, limit }`) |
+| `venue.getJob(jobId)` | Get a job by ID |
+| `venue.listJobs()` | List all job IDs |
+| `venue.didDocument()` | Get the venue's DID document |
+| `venue.mcpDiscovery()` | Get MCP (Model Context Protocol) discovery info |
+| `venue.agentCard()` | Get A2A (Agent-to-Agent) agent card |
+| `venue.close()` | Release resources and clear caches |
+
+---
+
+### Operations — `venue.operations`
+
+Execute named operations or asset-based operations.
 
 ```typescript
-import { Venue, Operation, DataAsset, CoviaError, AssetMetadata } from '@covia/covia-sdk';
+// List available operations
+const ops = await venue.operations.list();
+ops.forEach((op) => console.log(`${op.name}: ${op.description}`));
+
+// Get operation details
+const info = await venue.operations.get("test:echo");
+
+// Run synchronously (invoke + wait for result)
+const result = await venue.operations.run("test:echo", { message: "hi" });
+
+// Invoke asynchronously (returns a Job)
+const job = await venue.operations.invoke("test:echo", { message: "hi" });
+const output = await job.result({ timeout: 10000 });
+
+// With UCAN capability tokens
+const job = await venue.operations.invoke("sensitive:op", input, {
+  ucans: ["eyJhbGc..."],
+});
 ```
 
-## Testing
+| Method | Returns | Description |
+|---|---|---|
+| `operations.list()` | `OperationInfo[]` | List all named operations |
+| `operations.get(name)` | `OperationInfo` | Get operation details |
+| `operations.run(id, input, options?)` | `any` | Execute and wait for result |
+| `operations.invoke(id, input, options?)` | `Job` | Execute and return a Job |
 
-```bash
-npm test
+---
+
+### Assets — `venue.assets`
+
+Manage data assets and operations registered on the venue.
+
+```typescript
+// List and retrieve assets
+const list = await venue.assets.list({ offset: 0, limit: 50 });
+const asset = await venue.assets.get("asset-id");
+
+// Register a new asset
+const newAsset = await venue.assets.register({
+  name: "My Dataset",
+  description: "Training data",
+  content: { contentType: "text/csv", sha256: "abc123..." },
+});
+
+// Upload and download content
+await venue.assets.putContent("asset-id", new Blob(["data"]));
+const stream = await venue.assets.getContent("asset-id");
+
+// Get metadata
+const meta = await venue.assets.getMetadata("asset-id");
 ```
 
-## Resources
+| Method | Returns | Description |
+|---|---|---|
+| `assets.get(assetId)` | `Asset` | Get asset by ID (`Operation` or `DataAsset`) |
+| `assets.list(options?)` | `AssetList` | List assets with pagination |
+| `assets.register(data)` | `Asset` | Register a new asset |
+| `assets.getMetadata(assetId)` | `AssetMetadata` | Get asset metadata |
+| `assets.putContent(assetId, content)` | `ContentHashResult` | Upload content |
+| `assets.getContent(assetId)` | `ReadableStream \| null` | Download content stream |
+| `assets.clearCache()` | `void` | Clear the asset cache |
 
-- [Covia.ai Platform](https://covia.ai)
-- [Official Documentation](https://docs.covia.ai/)
-- [GitHub Repository](https://github.com/covia-ai/covia-sdk)
-- [Issue Tracker](https://github.com/covia-ai/covia-sdk/issues)
-- [npm Package](https://www.npmjs.com/package/@covia/covia-sdk)
+---
 
-## License
+### Jobs — `venue.jobs`
+
+Manage job lifecycle. Jobs are also returned by `operations.invoke()` and `asset.invoke()`.
+
+```typescript
+// List and retrieve jobs
+const jobIds = await venue.jobs.list();
+const job = await venue.jobs.get(jobIds[0]);
+
+// Job lifecycle via manager
+await venue.jobs.pause(jobId);
+await venue.jobs.resume(jobId);
+await venue.jobs.cancel(jobId);
+await venue.jobs.delete(jobId);
+
+// Send a message to a running job
+await venue.jobs.sendMessage(jobId, { text: "user input" });
+
+// Stream server-sent events
+for await (const event of venue.jobs.stream(jobId)) {
+  console.log(event.event, event.json());
+}
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `jobs.list()` | `string[]` | List all job IDs |
+| `jobs.get(jobId)` | `Job` | Get a job by ID |
+| `jobs.cancel(jobId)` | `JobMetadata` | Cancel a job |
+| `jobs.delete(jobId)` | `void` | Delete a job |
+| `jobs.pause(jobId)` | `JobMetadata` | Pause a job |
+| `jobs.resume(jobId)` | `JobMetadata` | Resume a paused job |
+| `jobs.sendMessage(jobId, msg)` | `any` | Send a message to a job |
+| `jobs.stream(jobId)` | `AsyncGenerator<SSEEvent>` | Stream SSE events |
+
+---
+
+### Job Instance
+
+Once you have a `Job` object, you can interact with it directly.
+
+```typescript
+const job = await venue.operations.invoke("long:task", input);
+
+// Status helpers
+job.isFinished;  // true for COMPLETE, FAILED, CANCELLED, REJECTED, TIMEOUT
+job.isComplete;  // true only for COMPLETE
+job.isPaused;    // true for PAUSED, INPUT_REQUIRED, AUTH_REQUIRED
+job.needsInput;  // true for INPUT_REQUIRED
+job.needsAuth;   // true for AUTH_REQUIRED
+
+// Wait for completion
+await job.wait({ timeout: 60000 });
+const output = job.output; // throws JobFailedError if not COMPLETE
+
+// Or wait + get output in one call
+const result = await job.result({ timeout: 60000 });
+
+// Refresh status from server
+await job.refresh();
+
+// Lifecycle
+await job.cancel();
+await job.delete();
+await job.pause();
+await job.resume();
+
+// Interactive jobs
+if (job.needsInput) {
+  await job.sendMessage({ text: "user response" });
+}
+
+// Stream events
+for await (const event of job.stream()) {
+  console.log(event.event, event.json());
+}
+```
+
+| Property / Method | Type | Description |
+|---|---|---|
+| `job.id` | `string` | Job identifier |
+| `job.metadata` | `JobMetadata` | Status, input, output, timestamps |
+| `job.isFinished` | `boolean` | Terminal state reached |
+| `job.isComplete` | `boolean` | Completed successfully |
+| `job.isPaused` | `boolean` | Paused / awaiting input or auth |
+| `job.needsInput` | `boolean` | Requires user input |
+| `job.needsAuth` | `boolean` | Requires authentication |
+| `job.output` | `any` | Get output (throws if not complete) |
+| `job.refresh()` | `Promise<void>` | Poll latest status from server |
+| `job.wait(options?)` | `Promise<void>` | Wait until finished (exponential backoff) |
+| `job.result(options?)` | `Promise<any>` | Wait and return output |
+| `job.cancel()` | `Promise<JobMetadata>` | Cancel the job |
+| `job.delete()` | `Promise<void>` | Delete the job |
+| `job.pause()` | `Promise<JobMetadata>` | Pause the job |
+| `job.resume()` | `Promise<JobMetadata>` | Resume the job |
+| `job.sendMessage(msg)` | `Promise<any>` | Send a message to the job |
+| `job.stream()` | `AsyncGenerator<SSEEvent>` | Stream SSE events |
+
+---
+
+### Asset Instance
+
+Assets returned by `venue.getAsset()` or `venue.assets.get()` are either an `Operation` or a `DataAsset`.
 
-MIT © Covia AI
+```typescript
+const asset = await venue.getAsset("my-asset-id");
+
+// Metadata
+const meta = await asset.getMetadata();
 
-## Support
+// Content (DataAsset)
+await asset.putContent(new Blob(["data"], { type: "text/plain" }));
+const stream = await asset.getContent();
+const url = asset.getContentURL(); // direct download URL
 
-For questions, issues, or feature requests:
+// Execution (Operation)
+const result = await asset.run({ param: "value" });      // sync
+const job = await asset.invoke({ param: "value" });       // async → Job
+```
 
-- 📧 Email: info@covia.ai
-- 💬 GitHub Issues: [github.com/covia-ai/covia-sdk/issues](https://github.com/covia-ai/covia-sdk/issues)
-- 📚 Documentation: [docs.covia.ai](https://docs.covia.ai/)
+| Method | Returns | Description |
+|---|---|---|
+| `asset.id` | `string` | Asset identifier |
+| `asset.metadata` | `AssetMetadata` | Asset metadata |
+| `asset.getMetadata()` | `Promise<AssetMetadata>` | Fetch metadata (cached) |
+| `asset.putContent(content)` | `Promise<ContentHashResult>` | Upload content |
+| `asset.getContent()` | `Promise<ReadableStream \| null>` | Download content stream |
+| `asset.getContentURL()` | `string` | Direct content download URL |
+| `asset.run(input)` | `Promise<any>` | Execute and wait for result |
+| `asset.invoke(input)` | `Promise<Job>` | Execute and return a Job |
 
 ---
 
-Built with ❤️ by [Covia Labs](https://covia.ai) - Foundational infrastructure for the agent economy
+### Agents — `venue.agents`
+
+Create and manage persistent AI agents.
+
+```typescript
+// Create an agent
+const result = await venue.agents.create({
+  agentId: "my-agent",
+  config: { model: "gpt-4", instructions: "..." },
+});
+
+// Interact with an agent
+const response = await venue.agents.request("my-agent", { text: "hello" });
+await venue.agents.message("my-agent", { event: "update" });
+await venue.agents.trigger("my-agent");
+const state = await venue.agents.query("my-agent");
+
+// Lifecycle
+const agents = await venue.agents.list();
+await venue.agents.suspend("my-agent");
+await venue.agents.resume("my-agent");
+await venue.agents.update({ agentId: "my-agent", config: { ... } });
+await venue.agents.cancelTask("my-agent", "task-123");
+await venue.agents.delete("my-agent");
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `agents.create(input)` | `AgentCreateResult` | Create an agent |
+| `agents.request(id, input?, wait?)` | `AgentRequestResult` | Send request to agent |
+| `agents.message(id, message)` | `AgentMessageResult` | Send a message |
+| `agents.trigger(id)` | `AgentTriggerResult` | Trigger agent execution |
+| `agents.query(id)` | `AgentQueryResult` | Query agent state |
+| `agents.list(includeTerminated?)` | `AgentListResult` | List agents |
+| `agents.delete(id, remove?)` | `AgentDeleteResult` | Delete an agent |
+| `agents.suspend(id)` | `AgentSuspendResult` | Suspend an agent |
+| `agents.resume(id, autoWake?)` | `AgentSuspendResult` | Resume an agent |
+| `agents.update(input)` | `any` | Update agent config/state |
+| `agents.cancelTask(agentId, taskId)` | `any` | Cancel an agent task |
+
+---
+
+### Workspace — `venue.workspace`
+
+Read and write shared state in the venue's workspace.
+
+```typescript
+// CRUD
+await venue.workspace.write("w/my-app/config", { theme: "dark" });
+const data = await venue.workspace.read("w/my-app/config");
+await venue.workspace.append("w/my-app/log", "new entry");
+await venue.workspace.delete("w/my-app/config");
+
+// List and slice
+const entries = await venue.workspace.list("w/my-app/", 100, 0);
+const slice = await venue.workspace.slice("w/my-app/log", 0, 10);
+
+// Discovery
+const funcs = await venue.workspace.functions();
+const desc = await venue.workspace.describe("myFunction");
+const adapters = await venue.workspace.adapters();
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `workspace.read(path, maxSize?)` | `WorkspaceReadResult` | Read a value |
+| `workspace.write(path, value)` | `WorkspaceWriteResult` | Write a value |
+| `workspace.delete(path)` | `WorkspaceDeleteResult` | Delete an entry |
+| `workspace.append(path, value)` | `WorkspaceAppendResult` | Append to an entry |
+| `workspace.list(path?, limit?, offset?)` | `WorkspaceListResult` | List entries |
+| `workspace.slice(path, offset?, limit?)` | `WorkspaceSliceResult` | Slice an entry |
+| `workspace.functions()` | `FunctionsResult` | List available functions |
+| `workspace.describe(name)` | `any` | Describe a function |
+| `workspace.adapters()` | `AdaptersResult` | List adapters |
+
+---
+
+### Secrets — `venue.secrets`
+
+Manage secrets stored on the venue.
+
+```typescript
+// Store and retrieve
+await venue.secrets.put("API_KEY", "sk-...");
+await venue.secrets.set("API_KEY", "sk-..."); // via secret:set operation
+
+// List
+const names = await venue.secrets.list(); // ["API_KEY", "DB_PASS"]
+
+// Extract (requires UCAN capability)
+const secret = await venue.secrets.extract("API_KEY");
+
+// Delete
+await venue.secrets.delete("API_KEY");
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `secrets.list()` | `string[]` | List secret names |
+| `secrets.put(name, value)` | `void` | Store a secret via REST |
+| `secrets.set(name, value)` | `SecretSetResult` | Store via `secret:set` operation |
+| `secrets.extract(name)` | `SecretExtractResult` | Extract value (requires UCAN) |
+| `secrets.delete(name)` | `void` | Delete a secret |
+
+---
+
+### UCAN — `venue.ucan`
+
+Issue UCAN (User Controlled Authorization Network) capability tokens.
+
+```typescript
+const att = [{ with: "/w/my-app/", can: "crud/read" }];
+const exp = Math.floor(Date.now() / 1000) + 3600; // 1 hour
+
+const token = await venue.ucan.issue("did:key:z6MkBob", att, exp);
+```
+
+| Method | Returns | Description |
+|---|---|---|
+| `ucan.issue(aud, att, exp)` | `UCANIssueResult` | Issue a UCAN token |
+
+---
+
+## Error Handling
+
+The SDK provides a hierarchy of typed errors:
+
+```typescript
+import {
+  CoviaError,          // Base error
+  GridError,           // HTTP API errors (4xx/5xx)
+  NotFoundError,       // 404 responses
+  AssetNotFoundError,  // Asset not found
+  JobNotFoundError,    // Job not found
+  CoviaConnectionError,// Connection failures
+  CoviaTimeoutError,   // Timeout exceeded
+  JobFailedError,      // Job finished with non-COMPLETE status
+} from "@covia/covia-sdk";
+
+try {
+  const asset = await venue.getAsset("nonexistent");
+} catch (err) {
+  if (err instanceof AssetNotFoundError) {
+    console.log(`Asset ${err.assetId} not found`);
+  } else if (err instanceof GridError) {
+    console.log(`HTTP ${err.statusCode}: ${err.message}`);
+  }
+}
+
+try {
+  const result = await job.result({ timeout: 5000 });
+} catch (err) {
+  if (err instanceof CoviaTimeoutError) {
+    console.log("Job took too long");
+  } else if (err instanceof JobFailedError) {
+    console.log(`Job failed: ${err.jobData.status}`);
+  }
+}
+```
+
+## Job Status
+
+```typescript
+import { RunStatus } from "@covia/covia-sdk";
+
+RunStatus.PENDING;         // Queued, not yet started
+RunStatus.STARTED;         // Running
+RunStatus.COMPLETE;        // Finished successfully
+RunStatus.FAILED;          // Finished with error
+RunStatus.CANCELLED;       // Cancelled by user
+RunStatus.TIMEOUT;         // Timed out
+RunStatus.REJECTED;        // Rejected by venue
+RunStatus.PAUSED;          // Paused
+RunStatus.INPUT_REQUIRED;  // Waiting for user input
+RunStatus.AUTH_REQUIRED;   // Waiting for authentication
+```
+
+## Requirements
+
+- Node.js >= 18
+- TypeScript >= 5.3 (for TypeScript users)
+
+## TypeScript
+
+`@covia/covia-sdk` is written in TypeScript and ships with full type declarations. No `@types/` package is needed.
+
+```typescript
+import {
+  Venue, Grid, Job, Asset, Operation, DataAsset,
+  AssetManager, OperationManager, JobManager,
+  AgentManager, WorkspaceManager, SecretManager, UCANManager,
+  KeyPairAuth, BearerAuth,
+  RunStatus, CoviaError,
+} from "@covia/covia-sdk";
+```
+
+## Resources
+
+- [Covia.ai Platform](https://covia.ai)
+- [Documentation](https://docs.covia.ai/)
+- [GitHub Repository](https://github.com/covia-ai/covia-sdk)
+- [npm Package](https://www.npmjs.com/package/@covia/covia-sdk)
+
+## License
+
+MIT - [Covia AI](https://covia.ai)