oceum 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # oceum
 
-Official SDK for [Oceum](https://oceum.ai) — the management platform for AI agents. Monitor, log, and orchestrate your agents from one dashboard.
+Official SDK for [Oceum](https://oceum.ai) — the command layer for AI agents. Monitor, log, track costs, and orchestrate your agents from one dashboard.
 
 Zero dependencies. Works with Node.js 18+, Deno, and Bun.
 
@@ -30,11 +30,56 @@ const result = await client.wrap('Process leads', async () => {
   return leads.length;
 });
 
+// Report LLM usage for cost tracking
+await client.reportUsage({
+  model: 'claude-sonnet',
+  tokensInput: 1200,
+  tokensOutput: 450,
+});
+
 // Clean up
 client.stopHeartbeat();
 await client.setStatus('idle');
 ```
 
+## No SDK? No Problem
+
+Oceum is just HTTP. Any language, any framework — POST JSON to the webhook endpoint:
+
+```bash
+# Heartbeat
+curl -X POST https://oceum.ai/api/webhook \
+  -H "Authorization: Bearer $OCEUM_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"event":"heartbeat","agentId":"agt_xxx"}'
+
+# Report a completed task
+curl -X POST https://oceum.ai/api/webhook \
+  -H "Authorization: Bearer $OCEUM_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"event":"task_complete","agentId":"agt_xxx","data":{"taskName":"sync-orders"}}'
+
+# Report LLM usage
+curl -X POST https://oceum.ai/api/webhook \
+  -H "Authorization: Bearer $OCEUM_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"event":"usage","agentId":"agt_xxx","data":{"model":"gpt-4o","tokensInput":500,"tokensOutput":200}}'
+```
+
+**Python:**
+
+```python
+import requests
+
+API_KEY = "oc_xxx"
+AGENT_ID = "agt_xxx"
+
+requests.post("https://oceum.ai/api/webhook",
+    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
+    json={"event": "heartbeat", "agentId": AGENT_ID}
+)
+```
+
 ## API
 
 | Method | Description |
@@ -48,6 +93,34 @@ await client.setStatus('idle');
 | `startHeartbeat(ms?)` | Auto-heartbeat every N ms (default: 60s) |
 | `stopHeartbeat()` | Stop auto-heartbeat |
 | `wrap(name, fn, meta?)` | Auto start/complete/error around async fn |
+| `reportUsage(opts?)` | Report LLM token usage for cost tracking |
+| `memory(content, opts?)` | Write shared memory visible to peer agents |
+| `readMemory(opts?)` | Read shared memory entries |
+| `vaultStore(data, opts?)` | Store sensitive data, returns vault token |
+| `vaultRetrieve(token)` | Retrieve data using vault token |
+| `vaultProxy(token, req)` | Zero-knowledge API call with vault credential |
+| `vaultRevoke(token)` | Permanently revoke a vault token |
+| `vaultList(opts?)` | List vault tokens (metadata only) |
+
+## Cost Tracking
+
+Report LLM token usage per call. Oceum calculates cost using configurable model pricing and enforces budget caps automatically.
+
+```javascript
+// After an LLM call
+await client.reportUsage({
+  model: 'claude-haiku',
+  tokensInput: 800,
+  tokensOutput: 200,
+});
+
+// Or include usage in task_complete meta for automatic tracking
+await client.taskComplete('generate-report', {
+  usage: { model: 'gpt-4o', tokensInput: 2000, tokensOutput: 1500 }
+});
+```
+
+Budget caps, alert thresholds, and per-model pricing are configured in the Oceum dashboard under Settings > Cost Controls.
 
 ## Error Handling
 
@@ -64,6 +137,14 @@ try {
 }
 ```
 
+## Webhook Verification
+
+Verify incoming webhook signatures with HMAC-SHA256:
+
+```javascript
+const valid = Oceum.verifyWebhookSignature(rawBody, signature, secret);
+```
+
 ## Docs
 
 Full documentation: [oceum.ai/docs](https://oceum.ai/docs.html)

package/index.d.ts

@@ -70,6 +70,9 @@ export class Oceum {
   /** Wrap an async function with automatic task_start, task_complete, and error reporting. */
   wrap<T>(taskName: string, fn: () => T | Promise<T>, meta?: Record<string, unknown>): Promise<T>;
 
+  /** Report LLM token usage for cost tracking and budget enforcement. */
+  reportUsage(options?: UsageReportOptions): Promise<UsageReportResponse>;
+
   /** Write a shared memory entry visible to peer agents. */
   memory(content: string, options?: MemoryWriteOptions): Promise<WebhookResponse>;
 
@@ -82,11 +85,23 @@ export class Oceum {
   /** Retrieve sensitive data from the Vault using a vault token. */
   vaultRetrieve(token: string): Promise<VaultRetrieveResponse>;
 
+  /**
+   * Zero-Knowledge Vault Proxy — make an API call with a vault-stored credential
+   * without ever seeing the raw secret.
+   */
+  vaultProxy(token: string, request: VaultProxyRequest): Promise<VaultProxyResponse>;
+
   /** Revoke a vault token permanently. */
   vaultRevoke(token: string): Promise<{ ok: boolean; token: string; revoked: boolean }>;
 
   /** List vault tokens (metadata only). */
   vaultList(options?: VaultListOptions): Promise<VaultListResponse>;
+
+  /**
+   * Verify a webhook signature using HMAC-SHA256 with timing-safe comparison.
+   * @returns true if the signature is valid
+   */
+  static verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
 }
 
 export interface MemoryWriteOptions {
@@ -130,6 +145,22 @@ export interface VaultStoreOptions {
   allowedAgents?: string;
   ttl?: '1h' | '6h' | '24h' | '7d' | '30d' | 'permanent';
   label?: string;
+  targetDomains?: string[];
+  injectionTemplate?: string;
+}
+
+export interface VaultProxyRequest {
+  method: string;
+  url: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+}
+
+export interface VaultProxyResponse {
+  ok: boolean;
+  status: number;
+  headers: Record<string, string>;
+  data: unknown;
 }
 
 export interface VaultStoreResponse {
@@ -171,3 +202,21 @@ export interface VaultListResponse {
   entries: VaultEntry[];
   count: number;
 }
+
+export interface UsageReportOptions {
+  /** Model name (e.g. 'claude-haiku', 'gpt-4o') */
+  model?: string;
+  /** Input/prompt tokens */
+  tokensInput?: number;
+  /** Output/completion tokens */
+  tokensOutput?: number;
+  /** Additional metadata */
+  meta?: Record<string, unknown>;
+}
+
+export interface UsageReportResponse {
+  ok: boolean;
+  event: string;
+  agentId: string;
+  costUsd: number;
+}

package/index.js

@@ -1,5 +1,10 @@
 'use strict';
 
+const crypto = require('crypto');
+
+const MAX_RETRIES = 3;
+const BACKOFF_BASE_MS = 1000;
+
 class OceumError extends Error {
   constructor(message, statusCode, body) {
     super(message);
@@ -31,33 +36,146 @@ class Oceum {
     this.#heartbeatTimer = null;
   }
 
+  // ── Helpers ─────────────────────────────────────────
+
+  #sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
   // ── Core transport ─────────────────────────────────
 
   async #send(event, data = {}) {
-    const res = await fetch(`${this.#baseUrl}/api/webhook`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'Authorization': `Bearer ${this.#apiKey}`,
-      },
-      body: JSON.stringify({
-        event,
-        agentId: this.#agentId,
-        data,
-      }),
-    });
+    let lastError;
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        const res = await fetch(`${this.#baseUrl}/api/webhook`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${this.#apiKey}`,
+          },
+          body: JSON.stringify({
+            event,
+            agentId: this.#agentId,
+            data,
+          }),
+        });
+
+        // 429 — respect Retry-After header
+        if (res.status === 429 && attempt < MAX_RETRIES) {
+          const retryAfter = parseInt(res.headers.get('Retry-After'), 10);
+          const waitMs = (retryAfter > 0 ? retryAfter : 1) * 1000;
+          await this.#sleep(waitMs);
+          continue;
+        }
+
+        // 5xx — exponential backoff
+        if (res.status >= 500 && attempt < MAX_RETRIES) {
+          await this.#sleep(BACKOFF_BASE_MS * Math.pow(2, attempt));
+          continue;
+        }
+
+        const body = await res.json().catch(() => ({}));
+
+        if (!res.ok) {
+          throw new OceumError(
+            body.error || `HTTP ${res.status}`,
+            res.status,
+            body
+          );
+        }
+
+        return body;
+      } catch (err) {
+        lastError = err;
+        // If it's already an OceumError (non-retryable status), rethrow immediately
+        if (err instanceof OceumError) throw err;
+        // Network error — retry with backoff
+        if (attempt < MAX_RETRIES) {
+          await this.#sleep(BACKOFF_BASE_MS * Math.pow(2, attempt));
+          continue;
+        }
+      }
+    }
 
-    const body = await res.json().catch(() => ({}));
+    throw lastError instanceof OceumError
+      ? lastError
+      : new OceumError(lastError?.message || 'Request failed after retries', 0, {});
+  }
 
-    if (!res.ok) {
-      throw new OceumError(
-        body.error || `HTTP ${res.status}`,
-        res.status,
-        body
-      );
+  async #get(url) {
+    let lastError;
+
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        const res = await fetch(url, {
+          headers: { 'Authorization': `Bearer ${this.#apiKey}` },
+        });
+
+        // 429 — respect Retry-After header
+        if (res.status === 429 && attempt < MAX_RETRIES) {
+          const retryAfter = parseInt(res.headers.get('Retry-After'), 10);
+          const waitMs = (retryAfter > 0 ? retryAfter : 1) * 1000;
+          await this.#sleep(waitMs);
+          continue;
+        }
+
+        // 5xx — exponential backoff
+        if (res.status >= 500 && attempt < MAX_RETRIES) {
+          await this.#sleep(BACKOFF_BASE_MS * Math.pow(2, attempt));
+          continue;
+        }
+
+        const body = await res.json().catch(() => ({}));
+
+        if (!res.ok) {
+          throw new OceumError(
+            body.error || `HTTP ${res.status}`,
+            res.status,
+            body
+          );
+        }
+
+        return body;
+      } catch (err) {
+        lastError = err;
+        if (err instanceof OceumError) throw err;
+        if (attempt < MAX_RETRIES) {
+          await this.#sleep(BACKOFF_BASE_MS * Math.pow(2, attempt));
+          continue;
+        }
+      }
     }
 
-    return body;
+    throw lastError instanceof OceumError
+      ? lastError
+      : new OceumError(lastError?.message || 'Request failed after retries', 0, {});
+  }
+
+  // ── Webhook signature verification ──────────────────
+
+  /**
+   * Verify a webhook signature using HMAC-SHA256 with timing-safe comparison.
+   * @param {string} payload - Raw request body string
+   * @param {string} signature - Signature from the X-Oceum-Signature header
+   * @param {string} secret - Your webhook signing secret
+   * @returns {boolean}
+   */
+  static verifyWebhookSignature(payload, signature, secret) {
+    const expected = crypto
+      .createHmac('sha256', secret)
+      .update(payload)
+      .digest('hex');
+    try {
+      return crypto.timingSafeEqual(
+        Buffer.from(expected, 'utf8'),
+        Buffer.from(signature, 'utf8')
+      );
+    } catch {
+      // Lengths differ — not equal
+      return false;
+    }
   }
 
   // ── Events ─────────────────────────────────────────
@@ -187,6 +305,20 @@ class Oceum {
     }
   }
 
+  // ── Usage / Cost Tracking ──────────────────────────────
+
+  /**
+   * Report LLM token usage for cost tracking and budget enforcement.
+   * @param {Object} options
+   * @param {string} [options.model] - Model name (e.g. 'claude-haiku', 'gpt-4o')
+   * @param {number} [options.tokensInput=0] - Input/prompt tokens
+   * @param {number} [options.tokensOutput=0] - Output/completion tokens
+   * @param {Object} [options.meta] - Additional metadata
+   */
+  async reportUsage({ model, tokensInput = 0, tokensOutput = 0, meta } = {}) {
+    return this.#send('usage', { model, tokensInput, tokensOutput, meta });
+  }
+
   // ── Shared Memory ────────────────────────────────────
 
   /**
@@ -221,21 +353,7 @@ class Oceum {
     if (tag) params.set('tag', tag);
     params.set('limit', String(limit));
 
-    const res = await fetch(`${this.#baseUrl}/api/memory?${params}`, {
-      headers: { 'Authorization': `Bearer ${this.#apiKey}` },
-    });
-
-    const body = await res.json().catch(() => ({}));
-
-    if (!res.ok) {
-      throw new OceumError(
-        body.error || `HTTP ${res.status}`,
-        res.status,
-        body
-      );
-    }
-
-    return body;
+    return this.#get(`${this.#baseUrl}/api/memory?${params}`);
   }
 
   // ── Vault (Secure Data) ──────────────────────────
@@ -250,9 +368,11 @@ class Oceum {
    * @param {string} [options.allowedAgents] - Comma-separated agent IDs (for specified_agents)
    * @param {'1h'|'6h'|'24h'|'7d'|'30d'|'permanent'} [options.ttl='30d']
    * @param {string} [options.label] - Human-readable label
+   * @param {string} [options.targetDomains] - Comma-separated domain allowlist for vault proxy (e.g. 'api.stripe.com,api.openai.com')
+   * @param {string} [options.injectionTemplate] - How to inject the secret into proxied requests (default: 'header:Authorization:Bearer {{secret}}')
    */
-  async vaultStore(data, { category = 'custom', accessPolicy = 'source_agent', allowedAgents, ttl = '30d', label } = {}) {
-    return this.#send('vault_store', { data, category, accessPolicy, allowedAgents, ttl, label });
+  async vaultStore(data, { category = 'custom', accessPolicy = 'source_agent', allowedAgents, ttl = '30d', label, targetDomains, injectionTemplate } = {}) {
+    return this.#send('vault_store', { data, category, accessPolicy, allowedAgents, ttl, label, targetDomains, injectionTemplate });
   }
 
   /**
@@ -263,6 +383,23 @@ class Oceum {
     return this.#send('vault_retrieve', { token });
   }
 
+  /**
+   * Zero-Knowledge Vault Proxy — make an API call with a vault-stored credential
+   * without ever seeing the raw secret. The platform decrypts and injects the
+   * credential into the outgoing request, then returns only the API response.
+   *
+   * @param {string} token - Vault token (vtk_xxx) containing the credential
+   * @param {Object} request - The outgoing HTTP request specification
+   * @param {string} request.method - HTTP method (GET, POST, PUT, DELETE, PATCH)
+   * @param {string} request.url - Target API URL (must match token's target_domains allowlist)
+   * @param {Object} [request.headers] - Additional headers (credential injected separately via template)
+   * @param {*} [request.body] - Request body (object for JSON, string for raw)
+   * @returns {{ ok: boolean, status: number, headers: Object, data: * }}
+   */
+  async vaultProxy(token, { method, url, headers, body } = {}) {
+    return this.#send('vault_proxy', { token, method, url, headers, body });
+  }
+
   /**
    * Revoke a vault token, permanently preventing future retrievals.
    * @param {string} token - Vault token (vtk_xxx)
@@ -303,21 +440,7 @@ class Oceum {
     params.set('status', status);
     params.set('limit', String(limit));
 
-    const res = await fetch(`${this.#baseUrl}/api/vault?${params}`, {
-      headers: { 'Authorization': `Bearer ${this.#apiKey}` },
-    });
-
-    const body = await res.json().catch(() => ({}));
-
-    if (!res.ok) {
-      throw new OceumError(
-        body.error || `HTTP ${res.status}`,
-        res.status,
-        body
-      );
-    }
-
-    return body;
+    return this.#get(`${this.#baseUrl}/api/vault?${params}`);
   }
 
   // ── Getters ────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oceum",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Official SDK for Oceum — the management platform for AI agents. Monitor, log, and orchestrate your agents from one dashboard.",
   "main": "index.js",
   "types": "index.d.ts",