oceum 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Oceum
+
+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

@@ -0,0 +1,73 @@
+# oceum
+
+Connect your AI agents to [Oceum](https://oceum.ai) for monitoring, logging, and orchestration.
+
+Zero dependencies. Works with Node.js 18+, Deno, and Bun.
+
+## Install
+
+```bash
+npm install oceum
+```
+
+## Quick Start
+
+```javascript
+const { Oceum } = require('oceum');
+
+const client = new Oceum({
+  apiKey: process.env.OCEUM_API_KEY,  // oc_xxx
+  agentId: process.env.OCEUM_AGENT_ID, // agt_xxx
+});
+
+// Start auto-heartbeat (every 60s)
+client.startHeartbeat();
+
+// Wrap tasks with automatic logging
+const result = await client.wrap('Process leads', async () => {
+  const leads = await fetchLeads();
+  await processAll(leads);
+  return leads.length;
+});
+
+// Clean up
+client.stopHeartbeat();
+await client.setStatus('idle');
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `heartbeat()` | Send keep-alive, sets status to active |
+| `taskStart(name, meta?)` | Log task initiation |
+| `taskComplete(name, meta?)` | Log task completion, increments count |
+| `error(name, opts?)` | Log error, `{ fatal: true }` sets error status |
+| `warning(msg, meta?)` | Log non-critical warning |
+| `setStatus(status)` | Set status: active, idle, paused, offline, error |
+| `startHeartbeat(ms?)` | Auto-heartbeat every N ms (default: 60s) |
+| `stopHeartbeat()` | Stop auto-heartbeat |
+| `wrap(name, fn, meta?)` | Auto start/complete/error around async fn |
+
+## Error Handling
+
+```javascript
+const { Oceum, OceumError } = require('oceum');
+
+try {
+  await client.heartbeat();
+} catch (err) {
+  if (err instanceof OceumError) {
+    console.log(err.statusCode); // 401, 404, etc.
+    console.log(err.body);       // API response
+  }
+}
+```
+
+## Docs
+
+Full documentation: [oceum.ai/docs](https://oceum.ai/docs.html)
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,173 @@
+export interface OceumConfig {
+  /** Your organization API key (oc_xxx) */
+  apiKey: string;
+  /** Your agent ID (agt_xxx) */
+  agentId: string;
+  /** API base URL (default: 'https://oceum.ai') */
+  baseUrl?: string;
+}
+
+export interface WebhookResponse {
+  ok: boolean;
+  event: string;
+  agentId: string;
+  taskCount?: number;
+  errorCount?: number;
+  status?: string;
+}
+
+export interface ErrorOptions {
+  /** Error message (defaults to errorName) */
+  message?: string;
+  /** Stack trace */
+  stack?: string;
+  /** Whether this is a fatal error (default: false) */
+  fatal?: boolean;
+  /** Additional metadata */
+  [key: string]: unknown;
+}
+
+export class OceumError extends Error {
+  /** HTTP status code from the API */
+  statusCode: number;
+  /** Response body from the API */
+  body: Record<string, unknown>;
+  constructor(message: string, statusCode: number, body: Record<string, unknown>);
+}
+
+export class Oceum {
+  constructor(config: OceumConfig);
+
+  /** The agent ID this client reports as */
+  readonly agentId: string;
+  /** The API base URL */
+  readonly baseUrl: string;
+
+  /** Send a heartbeat. Updates agent status to 'active'. */
+  heartbeat(): Promise<WebhookResponse>;
+
+  /** Log a task starting. */
+  taskStart(taskName: string, meta?: Record<string, unknown>): Promise<WebhookResponse>;
+
+  /** Log a task completing. Increments the agent's task count. */
+  taskComplete(taskName: string, meta?: Record<string, unknown>): Promise<WebhookResponse>;
+
+  /** Log an error. Increments the agent's error count. If fatal, sets status to 'error'. */
+  error(errorName: string, options?: ErrorOptions): Promise<WebhookResponse>;
+
+  /** Log a non-critical warning. */
+  warning(message: string, meta?: Record<string, unknown>): Promise<WebhookResponse>;
+
+  /** Explicitly set the agent's status. */
+  setStatus(status: 'active' | 'idle' | 'paused' | 'offline' | 'error'): Promise<WebhookResponse>;
+
+  /** Start sending heartbeats at a regular interval. */
+  startHeartbeat(intervalMs?: number): void;
+
+  /** Stop the auto-heartbeat. */
+  stopHeartbeat(): void;
+
+  /** 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>;
+
+  /** Write a shared memory entry visible to peer agents. */
+  memory(content: string, options?: MemoryWriteOptions): Promise<WebhookResponse>;
+
+  /** Read shared memory entries from peer agents. */
+  readMemory(options?: MemoryReadOptions): Promise<MemoryReadResponse>;
+
+  /** Store sensitive data in the Secure Data Vault. Returns a vault token. */
+  vaultStore(data: string, options?: VaultStoreOptions): Promise<VaultStoreResponse>;
+
+  /** Retrieve sensitive data from the Vault using a vault token. */
+  vaultRetrieve(token: string): Promise<VaultRetrieveResponse>;
+
+  /** 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>;
+}
+
+export interface MemoryWriteOptions {
+  category?: 'insight' | 'error_pattern' | 'config' | 'dependency' | 'learning';
+  scope?: 'fleet' | 'targeted';
+  targetAgent?: string;
+  tags?: string;
+  ttl?: '1h' | '6h' | '24h' | '7d' | '30d' | 'permanent';
+}
+
+export interface MemoryReadOptions {
+  scope?: 'fleet' | 'targeted';
+  category?: 'insight' | 'error_pattern' | 'config' | 'dependency' | 'learning';
+  tag?: string;
+  limit?: number;
+}
+
+export interface MemoryEntry {
+  id: string;
+  name: string;
+  sourceAgent: string;
+  sourceAgentName: string;
+  scope: 'fleet' | 'targeted';
+  targetAgent: string;
+  category: string;
+  content: string;
+  tags: string;
+  timestamp: string;
+  ttl: string;
+}
+
+export interface MemoryReadResponse {
+  ok: boolean;
+  memories: MemoryEntry[];
+  count: number;
+}
+
+export interface VaultStoreOptions {
+  category?: 'financial' | 'medical' | 'credentials' | 'personal' | 'custom';
+  accessPolicy?: 'owner_only' | 'source_agent' | 'specified_agents' | 'all_agents';
+  allowedAgents?: string;
+  ttl?: '1h' | '6h' | '24h' | '7d' | '30d' | 'permanent';
+  label?: string;
+}
+
+export interface VaultStoreResponse {
+  ok: boolean;
+  event: string;
+  agentId: string;
+  token: string;
+}
+
+export interface VaultRetrieveResponse {
+  ok: boolean;
+  event: string;
+  agentId: string;
+  token: string;
+  data: string;
+}
+
+export interface VaultListOptions {
+  category?: 'financial' | 'medical' | 'credentials' | 'personal' | 'custom';
+  status?: 'active' | 'revoked';
+  limit?: number;
+}
+
+export interface VaultEntry {
+  token: string;
+  category: string;
+  sourceAgent: string;
+  sourceAgentName: string;
+  accessPolicy: string;
+  ttl: string;
+  status: string;
+  label: string;
+  createdAt: string;
+  accessCount: number;
+}
+
+export interface VaultListResponse {
+  ok: boolean;
+  entries: VaultEntry[];
+  count: number;
+}

package/index.js

@@ -0,0 +1,329 @@
+'use strict';
+
+class OceumError extends Error {
+  constructor(message, statusCode, body) {
+    super(message);
+    this.name = 'OceumError';
+    this.statusCode = statusCode;
+    this.body = body;
+  }
+}
+
+class Oceum {
+  #apiKey;
+  #agentId;
+  #baseUrl;
+  #heartbeatTimer;
+
+  /**
+   * Create an Oceum client.
+   * @param {Object} config
+   * @param {string} config.apiKey - Your organization API key (oc_xxx)
+   * @param {string} config.agentId - Your agent ID (agt_xxx)
+   * @param {string} [config.baseUrl='https://oceum.ai'] - API base URL
+   */
+  constructor({ apiKey, agentId, baseUrl = 'https://oceum.ai' } = {}) {
+    if (!apiKey) throw new Error('oceum: apiKey is required');
+    if (!agentId) throw new Error('oceum: agentId is required');
+    this.#apiKey = apiKey;
+    this.#agentId = agentId;
+    this.#baseUrl = baseUrl.replace(/\/$/, '');
+    this.#heartbeatTimer = null;
+  }
+
+  // ── 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,
+      }),
+    });
+
+    const body = await res.json().catch(() => ({}));
+
+    if (!res.ok) {
+      throw new OceumError(
+        body.error || `HTTP ${res.status}`,
+        res.status,
+        body
+      );
+    }
+
+    return body;
+  }
+
+  // ── Events ─────────────────────────────────────────
+
+  /**
+   * Send a heartbeat. Updates agent status to 'active'.
+   */
+  async heartbeat() {
+    return this.#send('heartbeat');
+  }
+
+  /**
+   * Log a task starting.
+   * @param {string} taskName - Name of the task
+   * @param {Object} [meta] - Additional metadata
+   */
+  async taskStart(taskName, meta) {
+    return this.#send('task_start', {
+      taskName,
+      message: `Task started: ${taskName}`,
+      meta,
+    });
+  }
+
+  /**
+   * Log a task completing. Increments the agent's task count.
+   * @param {string} taskName - Name of the task
+   * @param {Object} [meta] - Additional metadata
+   */
+  async taskComplete(taskName, meta) {
+    return this.#send('task_complete', {
+      taskName,
+      message: `Task completed: ${taskName}`,
+      meta,
+    });
+  }
+
+  /**
+   * Log an error. Increments the agent's error count.
+   * If fatal is true, sets agent status to 'error'.
+   * @param {string} errorName - Name/title of the error
+   * @param {Object} [options]
+   * @param {string} [options.message] - Error message (defaults to errorName)
+   * @param {string} [options.stack] - Stack trace
+   * @param {boolean} [options.fatal=false] - Whether this is a fatal error
+   */
+  async error(errorName, { message, stack, fatal = false, ...meta } = {}) {
+    return this.#send('error', {
+      errorName,
+      message: message || errorName,
+      stack,
+      fatal,
+      meta: Object.keys(meta).length ? meta : undefined,
+    });
+  }
+
+  /**
+   * Log a non-critical warning.
+   * @param {string} message - Warning message
+   * @param {Object} [meta] - Additional metadata
+   */
+  async warning(message, meta) {
+    return this.#send('warning', { message, meta });
+  }
+
+  /**
+   * Explicitly set the agent's status.
+   * @param {'active'|'idle'|'paused'|'offline'|'error'} status
+   */
+  async setStatus(status) {
+    const valid = ['active', 'idle', 'paused', 'offline', 'error'];
+    if (!valid.includes(status)) {
+      throw new Error(`oceum: invalid status "${status}". Must be one of: ${valid.join(', ')}`);
+    }
+    return this.#send('status', { status });
+  }
+
+  // ── Auto-heartbeat ─────────────────────────────────
+
+  /**
+   * Start sending heartbeats at a regular interval.
+   * @param {number} [intervalMs=60000] - Heartbeat interval in milliseconds
+   */
+  startHeartbeat(intervalMs = 60000) {
+    this.stopHeartbeat();
+    this.heartbeat().catch(() => {});
+    this.#heartbeatTimer = setInterval(() => {
+      this.heartbeat().catch(() => {});
+    }, intervalMs);
+    // Allow process to exit even if heartbeat is running
+    if (this.#heartbeatTimer.unref) this.#heartbeatTimer.unref();
+  }
+
+  /**
+   * Stop the auto-heartbeat.
+   */
+  stopHeartbeat() {
+    if (this.#heartbeatTimer) {
+      clearInterval(this.#heartbeatTimer);
+      this.#heartbeatTimer = null;
+    }
+  }
+
+  // ── Lifecycle wrapper ──────────────────────────────
+
+  /**
+   * Wrap an async function with automatic task_start, task_complete, and error reporting.
+   * Re-throws any error after reporting it.
+   * @param {string} taskName - Name of the task
+   * @param {Function} fn - Async function to execute
+   * @param {Object} [meta] - Additional metadata
+   * @returns {Promise<*>} - The return value of fn
+   */
+  async wrap(taskName, fn, meta) {
+    await this.taskStart(taskName, meta);
+    try {
+      const result = await fn();
+      await this.taskComplete(taskName, meta);
+      return result;
+    } catch (err) {
+      await this.error(taskName, {
+        message: err.message,
+        stack: err.stack,
+        fatal: false,
+      }).catch(() => {});
+      throw err;
+    }
+  }
+
+  // ── Shared Memory ────────────────────────────────────
+
+  /**
+   * Write a shared memory entry visible to peer agents.
+   * @param {string} content - The memory content (max 2000 chars)
+   * @param {Object} [options]
+   * @param {'insight'|'error_pattern'|'config'|'dependency'|'learning'} [options.category='insight']
+   * @param {'fleet'|'targeted'} [options.scope='fleet']
+   * @param {string} [options.targetAgent] - Required if scope is 'targeted'
+   * @param {string} [options.tags] - Comma-separated tags
+   * @param {'1h'|'6h'|'24h'|'7d'|'30d'|'permanent'} [options.ttl='24h']
+   */
+  async memory(content, { category = 'insight', scope = 'fleet', targetAgent, tags, ttl = '24h' } = {}) {
+    return this.#send('memory', { content, category, scope, targetAgent, tags, ttl });
+  }
+
+  /**
+   * Read shared memory entries from peer agents.
+   * Returns fleet-wide memories and memories targeted to this agent.
+   * @param {Object} [options]
+   * @param {'fleet'|'targeted'} [options.scope]
+   * @param {'insight'|'error_pattern'|'config'|'dependency'|'learning'} [options.category]
+   * @param {string} [options.tag] - Filter by tag
+   * @param {number} [options.limit=20] - Max results (up to 50)
+   * @returns {Promise<{ok: boolean, memories: Array, count: number}>}
+   */
+  async readMemory({ scope, category, tag, limit = 20 } = {}) {
+    const params = new URLSearchParams();
+    params.set('agentId', this.#agentId);
+    if (scope) params.set('scope', scope);
+    if (category) params.set('category', category);
+    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;
+  }
+
+  // ── Vault (Secure Data) ──────────────────────────
+
+  /**
+   * Store sensitive data in the Secure Data Vault.
+   * Returns an opaque vault token (vtk_xxx) for later retrieval.
+   * @param {string} data - Sensitive data to encrypt and store (max 2000 chars)
+   * @param {Object} [options]
+   * @param {'financial'|'medical'|'credentials'|'personal'|'custom'} [options.category='custom']
+   * @param {'owner_only'|'source_agent'|'specified_agents'|'all_agents'} [options.accessPolicy='source_agent']
+   * @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
+   */
+  async vaultStore(data, { category = 'custom', accessPolicy = 'source_agent', allowedAgents, ttl = '30d', label } = {}) {
+    return this.#send('vault_store', { data, category, accessPolicy, allowedAgents, ttl, label });
+  }
+
+  /**
+   * Retrieve sensitive data from the Vault using a vault token.
+   * @param {string} token - Vault token (vtk_xxx)
+   */
+  async vaultRetrieve(token) {
+    return this.#send('vault_retrieve', { token });
+  }
+
+  /**
+   * Revoke a vault token, permanently preventing future retrievals.
+   * @param {string} token - Vault token (vtk_xxx)
+   */
+  async vaultRevoke(token) {
+    const res = await fetch(`${this.#baseUrl}/api/vault`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.#apiKey}`,
+      },
+      body: JSON.stringify({ action: 'revoke', token, agentId: this.#agentId }),
+    });
+
+    const body = await res.json().catch(() => ({}));
+
+    if (!res.ok) {
+      throw new OceumError(
+        body.error || `HTTP ${res.status}`,
+        res.status,
+        body
+      );
+    }
+
+    return body;
+  }
+
+  /**
+   * List vault tokens (metadata only, no decrypted content).
+   * @param {Object} [options]
+   * @param {'financial'|'medical'|'credentials'|'personal'|'custom'} [options.category]
+   * @param {'active'|'revoked'} [options.status='active']
+   * @param {number} [options.limit=20]
+   */
+  async vaultList({ category, status = 'active', limit = 20 } = {}) {
+    const params = new URLSearchParams();
+    if (category) params.set('category', category);
+    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;
+  }
+
+  // ── Getters ────────────────────────────────────────
+
+  get agentId() { return this.#agentId; }
+  get baseUrl() { return this.#baseUrl; }
+}
+
+module.exports = { Oceum, OceumError };

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "oceum",
+  "version": "0.1.0",
+  "description": "Connect your AI agents to Oceum for monitoring, logging, and orchestration.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "monitoring",
+    "oceum",
+    "observability",
+    "llm",
+    "orchestration"
+  ],
+  "author": "Oceum <hello@oceum.ai>",
+  "license": "MIT",
+  "homepage": "https://oceum.ai/docs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/oceum/sdk"
+  }
+}