@realtimex/sdk 2.0.17 → 2.0.18

package/package.json

@@ -1,61 +1,28 @@
 {
     "name": "@realtimex/sdk",
-    "version": "2.0.17",
-    "description": "SDK for building Local Apps that integrate with RealtimeX",
-    "main": "dist/index.js",
-    "module": "dist/index.mjs",
-    "types": "dist/index.d.ts",
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "import": "./dist/index.mjs",
-            "require": "./dist/index.js"
-        },
-        "./v1": {
-            "types": "./dist/v1/index.d.ts",
-            "import": "./dist/v1/index.mjs",
-            "require": "./dist/v1/index.js"
-        },
-        "./cli": {
-            "types": "./dist/cli/index.d.ts",
-            "import": "./dist/cli/index.mjs",
-            "require": "./dist/cli/index.js"
-        }
-    },
+    "version": "2.0.18",
+    "description": "RealtimeX SDK package assets, including the moderator agent skill.",
+    "private": false,
     "scripts": {
-        "build": "node ../scripts/generate-v1-sdk.mjs --force && tsup src/index.ts src/v1/index.ts src/cli/index.ts --format cjs,esm --dts --clean",
-        "dev": "tsup src/index.ts src/v1/index.ts src/cli/index.ts --format cjs,esm --dts --watch",
-        "test": "vitest run --passWithNoTests",
-        "sdk:generate": "node ../scripts/generate-v1-sdk.mjs",
-        "sdk:generate:force": "node ../scripts/generate-v1-sdk.mjs --force",
-        "sdk:diff": "node ../scripts/generate-v1-sdk.mjs --dry-run",
         "skill:generate": "node ../scripts/generate-skill.mjs --force",
-        "skill:local-test": "node ../scripts/local-test-realtimex-skill.mjs",
         "pp-cli:build": "node ../scripts/build-pp-cli-packages.mjs",
-        "pp-cli:publish": "node ../scripts/publish-pp-cli-packages.mjs",
-        "prepublishOnly": "npm run build && npm run skill:generate"
+        "pp-cli:publish": "node ../scripts/publish-pp-cli-packages.mjs"
     },
     "keywords": [
         "realtimex",
-        "local-apps",
-        "sdk",
-        "supabase"
+        "cli",
+        "agent-skill"
     ],
     "author": "RealtimeX Team",
     "license": "MIT",
-    "devDependencies": {
-        "@types/node": "^20.10.0",
-        "rollup": "^4.55.1",
-        "tsup": "^8.0.0",
-        "typescript": "^5.3.0",
-        "vitest": "^1.0.0"
+    "engines": {
+        "node": ">=18.0.0"
     },
     "files": [
-        "dist",
         "skills",
         "README.md"
     ],
-    "engines": {
-        "node": ">=18.0.0"
+    "publishConfig": {
+        "access": "public"
     }
 }

package/skills/realtimex-moderator-sdk/SKILL.md

@@ -20,15 +20,15 @@ This skill drives the `realtimex-pp-cli` binary. Verify the CLI is installed and
 
 1. Install or reinstall the pinned version via npm:
    ```bash
-   npm install -g @realtimex/pp-cli@2.0.17
+   npm install -g @realtimex/pp-cli@2.0.18
    ```
 2. Verify the exact version:
    ```bash
    realtimex-pp-cli --version
    ```
-   The output must be `realtimex-pp-cli 2.0.17`.
+   The output must be `realtimex-pp-cli 2.0.18`.
 
-If `--version` reports "command not found" after install, the npm global bin directory is not on `$PATH`. If it reports any version other than `2.0.17`, reinstall with the pinned npm command above. Do not proceed with skill commands until exact-version verification succeeds.
+If `--version` reports "command not found" after install, the npm global bin directory is not on `$PATH`. If it reports any version other than `2.0.18`, reinstall with the pinned npm command above. Do not proceed with skill commands until exact-version verification succeeds.
 
 * Always run first:
 
@@ -396,9 +396,9 @@ Verify: `claude mcp list`
    ```bash
    realtimex-pp-cli --version
    ```
-   If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.17`, reinstall the pinned version:
+   If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.18`, reinstall the pinned version:
    ```bash
-   npm install -g @realtimex/pp-cli@2.0.17
+   npm install -g @realtimex/pp-cli@2.0.18
    ```
    Then run `realtimex-pp-cli --version` again and proceed only after exact-version verification succeeds.
 2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
@@ -493,3 +493,7 @@ For personality and heartbeat setup:
 For `setup-working-dir` and `run-automation-workflow*`:
 
 * Never auto retry on error code 500 or timeout, just inform error to user
+
+For `publish-artifact`:
+
+* files or folders have to be placed in <working-dir>/artifacts/ to be able to published

package/README.md

@@ -1,382 +0,0 @@
-# RealtimeX Local App SDK
-
-TypeScript/JavaScript SDK for building Local Apps that integrate with RealtimeX.
-
-## Installation
-
-```bash
-npm install @realtimex/sdk
-```
-
-## Prerequisites
-
-Before using this SDK, ensure your Supabase database is set up:
-
-1. Open **RealtimeX Main App** → **Local Apps** → Your App → **Configure**
-2. Enter your Supabase **URL** and **Anon Key**
-3. Select **Compatible Mode** and click **Login to Supabase**
-4. Click **Auto-Setup Schema** to create the required tables and functions
-
-> **Note:** Schema setup is handled entirely by the Main App. You don't need to run any SQL manually.
-
-## Quick Start
-
-```typescript
-import { RealtimeXSDK } from '@realtimex/sdk';
-
-const sdk = new RealtimeXSDK({
-  // Development Mode: Use API key for full access
-  realtimex: { apiKey: 'sk-abc123...' }, 
-  // OR Production Mode: Declare permissions
-  permissions: ['activities.read', 'activities.write', 'webhook.trigger']
-});
-
-// Insert activity
-const activity = await sdk.activities.insert({
-  type: 'new_lead',
-  email: 'user@example.com',
-});
-
-// Trigger agent (optional - for auto-processing)
-await sdk.webhook.triggerAgent({
-  raw_data: activity,
-  auto_run: true,
-  agent_name: 'processor',
-  workspace_slug: 'sales',
-  thread_slug: 'general', //create_new for new thread
-  prompt: 'Process this lead',//optional
-});
-```
-
-## How It Works
-
-When you start your Local App from the RealtimeX Main App:
-
-1. Environment variables `RTX_APP_ID` and `RTX_APP_NAME` are automatically set
-2. The SDK auto-detects these - no manual configuration needed
-3. All operations go through the Main App's proxy endpoints
-
-## Configuration (Optional)
-
-```typescript
-const sdk = new RealtimeXSDK({
-  realtimex: {
-    url: 'http://custom-host:3001',  // Default: localhost:3001
-    apiKey: 'sk-abc123...',           // Development mode
-    appId: 'custom-id',               // Production mode (override)
-    appName: 'My App',                // Optional
-  }
-});
-```
-
-## API Reference
-
-### Activities CRUD
-
-```typescript
-// Insert
-const activity = await sdk.activities.insert({ type: 'order', amount: 100 });
-
-// List
-const pending = await sdk.activities.list({ status: 'pending', limit: 50 });
-
-// Get
-const item = await sdk.activities.get('activity-uuid');
-
-// Update
-await sdk.activities.update('activity-uuid', { status: 'processed' });
-
-// Delete
-await sdk.activities.delete('activity-uuid');
-```
-
-### Webhook - Trigger Agent
-
-```typescript
-// Manual mode (creates calendar event only)
-await sdk.webhook.triggerAgent({
-  raw_data: { email: 'customer@example.com' },
-});
-
-// Auto-run mode (creates event and triggers agent immediately)
-await sdk.webhook.triggerAgent({
-  raw_data: activity,
-  auto_run: true,
-  agent_name: 'processor',
-  workspace_slug: 'sales',
-  thread_slug: 'optional-thread',  // Optional: specific thread
-});
-```
-
-### Contract Discovery
-
-```typescript
-// Read canonical contract metadata published by Main App
-const contract = await sdk.contract.getLocalAppV1();
-
-console.log(contract.version); // local-app-contract/v1
-console.log(contract.supported_events); // task.trigger, task.claimed, ...
-console.log(contract.callback?.signature_header); // x-rtx-contract-signature
-```
-
-### Worker Callback Lifecycle
-
-Use this when your worker receives `task_uuid`, `attempt_id`, and callback metadata from RealtimeX task context.
-
-```typescript
-sdk.task.configureContract({
-  callbackSecret: process.env.RTX_CONTRACT_CALLBACK_SECRET,
-  signCallbacksByDefault: true,
-});
-
-await sdk.task.claim(taskUuid, {
-  callbackUrl,
-  machineId,
-  attemptId,
-  userEmail,
-});
-
-await sdk.task.start(taskUuid, {
-  callbackUrl,
-  machineId,
-  attemptId,
-});
-
-await sdk.task.progress(taskUuid, { percent: 50, message: 'Halfway done' }, {
-  callbackUrl,
-  machineId,
-  attemptId,
-});
-
-await sdk.task.complete(taskUuid, { summary: 'Done' }, {
-  callbackUrl,
-  machineId,
-  attemptId,
-});
-```
-
-`TaskModule` auto-populates:
-- `event_id` for idempotency
-- canonical `event` names
-- optional HMAC signature header (`x-rtx-contract-signature`) when signing is enabled
-- legacy `action` alongside canonical `event` for compatibility when posting to callback URLs
-
-### Contract Compatibility Check
-
-Run the cross-language harness (Main App endpoint + TypeScript SDK + Python SDK):
-
-```bash
-RTX_API_KEY=sk-... RTX_CONTRACT_VERIFY_BASE_URL=http://127.0.0.1:3001 npm run contract:verify
-```
-
-### Public APIs
-
-```typescript
-// Get available agents in a workspace
-const agents = await sdk.api.getAgents();
-
-// Get all workspaces
-const workspaces = await sdk.api.getWorkspaces();
-
-// Get threads in a workspace
-const threads = await sdk.api.getThreads('sales');
-
-// Get task status
-const task = await sdk.api.getTask('task-uuid');
-```
-
-### LLM Module
-
-Access AI capabilities through the RealtimeX proxy:
-
-```typescript
-const sdk = new RealtimeXSDK({
-  permissions: ['llm.chat', 'llm.embed', 'llm.providers', 'vectors.write', 'vectors.read']
-});
-```
-
-#### List Providers & Models
-
-```typescript
-
-
-// Get only configured Chat providers (recommended)
-const chatRes = await sdk.llm.chatProviders();
-// chatRes.providers: Array of chat providers with models
-
-// Get only configured Embedding providers (recommended)
-const embedRes = await sdk.llm.embedProviders();
-// embedRes.providers: Array of embedding providers with models
-```
-
-
-#### Chat Completion
-
-```typescript
-// Sync Chat
-const response = await sdk.llm.chat(
-  [
-    { role: 'system', content: 'You are a helpful assistant.' },
-    { role: 'user', content: 'What is RealtimeX?' }
-  ],
-  { 
-    model: 'gpt-4o',           // Optional: specific model
-    provider: 'openai',        // Optional: specific provider
-    temperature: 0.7,          // Optional: 0.0-2.0
-    max_tokens: 1000           // Optional: max response tokens
-  }
-);
-console.log(response.response?.content);
-
-// Multimodal Chat (text + file/image blocks)
-const multimodal = await sdk.llm.chat([
-  {
-    role: 'user',
-    content: [
-      { type: 'text', text: 'Summarize the attached document' },
-      { type: 'input_file', file_url: 'https://example.com/report.pdf' },
-      { type: 'input_image', image_url: 'https://example.com/chart.png' }
-    ]
-  }
-]);
-console.log(multimodal.response?.content);
-
-// Streaming Chat
-for await (const chunk of sdk.llm.chatStream(messages, options)) {
-  process.stdout.write(chunk.textResponse || '');
-}
-```
-
-#### Generate Embeddings
-
-```typescript
-const { embeddings, dimensions, provider, model } = await sdk.llm.embed(
-  ['Hello world', 'Goodbye'],
-  { provider: 'openai', model: 'text-embedding-3-small' } // Optional
-);
-// embeddings: number[][] - vector arrays
-// dimensions: number - vector dimension (e.g., 1536)
-```
-
-#### Vector Store Operations
-
-```typescript
-// Upsert vectors with metadata
-await sdk.llm.vectors.upsert([
-  { 
-    id: 'chunk-1', 
-    vector: embeddings[0], 
-    metadata: { 
-      text: 'Hello world',      // Original text (for retrieval)
-      documentId: 'doc-1',       // Logical grouping
-      customField: 'any value'   // Any custom metadata
-    } 
-  }
-], { 
-  workspaceId: 'ws-123'          // Optional: physical namespace isolation
-});
-
-// Query similar vectors
-const results = await sdk.llm.vectors.query(queryVector, {
-  topK: 5,                       // Number of results
-  workspaceId: 'ws-123',         // Optional: search in specific workspace
-  filter: { documentId: 'doc-1' } // Optional: filter by document
-});
-// returns: { success, results: [{ id, score, metadata }] }
-
-// List all workspaces for this app
-const { workspaces } = await sdk.llm.vectors.listWorkspaces();
-// returns: { success, workspaces: ['ws-123', 'default', ...] }
-
-// Delete all vectors in a workspace
-await sdk.llm.vectors.delete({ 
-  deleteAll: true, 
-  workspaceId: 'ws-123' 
-});
-```
-
-#### High-Level Helpers
-
-These combine multiple operations for common RAG patterns:
-
-```typescript
-// embedAndStore: Text → Embed → Store (one call)
-await sdk.llm.embedAndStore(
-  ['Document text 1', 'Document text 2'],  // texts to embed
-  {
-    documentId: 'doc-123',                  // Optional: logical grouping
-    workspaceId: 'ws-456',                  // Optional: physical isolation
-    provider: 'openai',                     // Optional: embedding provider
-    model: 'text-embedding-3-small'         // Optional: embedding model
-  }
-);
-
-// search: Query → Embed → Search (one call)
-const searchResults = await sdk.llm.search(
-  'What is RealtimeX?',                     // search query (text, not vector)
-  {
-    topK: 5,                                // Number of results
-    workspaceId: 'ws-123',                  // Optional: search in workspace
-    documentId: 'doc-1',                    // Optional: filter by document
-    provider: 'openai',                     // Optional: embedding provider
-    model: 'text-embedding-3-small'         // Optional: embedding model
-  }
-);
-// returns: [{ id, score, metadata: { text, documentId, ... } }]
-```
-
-> **Note on Isolation:**
-> - `workspaceId`: Creates **physical namespace** (`sdk_{appId}_{wsId}`) - data completely isolated
-> - `documentId`: Stored as **metadata**, filtered after search (post-filter)
-
-### Error Handling
-
-The SDK provides specific error classes for handling LLM-related issues:
-
-```typescript
-import { LLMPermissionError, LLMProviderError } from '@realtimex/sdk';
-
-try {
-  for await (const chunk of sdk.llm.chatStream(messages)) {
-    process.stdout.write(chunk.textResponse || '');
-  }
-} catch (error) {
-  if (error instanceof LLMPermissionError) {
-    // Permission not granted: 'llm.chat' etc.
-    console.error(`Permission required: ${error.permission}`);
-  } else if (error instanceof LLMProviderError) {
-    // Provider errors: rate limit, timeout, model unavailable, etc.
-    console.error(`Provider error: ${error.message} (code: ${error.code})`);
-    // Common codes: LLM_STREAM_ERROR, RATE_LIMIT, PROVIDER_UNAVAILABLE
-  }
-}
-```
-
-| Error Class | Common Codes | Description |
-|-------------|--------------|-------------|
-| `LLMPermissionError` | `PERMISSION_REQUIRED` | Missing or denied permission |
-| `LLMProviderError` | `LLM_STREAM_ERROR`, `RATE_LIMIT`, `PROVIDER_UNAVAILABLE` | AI provider issues |
-
-## Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `RTX_APP_ID` | Auto-set by Main App when starting your app |
-| `RTX_APP_NAME` | Auto-set by Main App when starting your app |
-
-## Architecture
-
-```
-┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
-│   Your App      │────▶│  RealtimeX Main  │────▶│  Supabase   │
-│   (SDK)         │     │  App (Proxy)     │     │  Database   │
-└─────────────────┘     └──────────────────┘     └─────────────┘
-```
-
-- Your app uses the SDK to communicate with the Main App
-- Main App proxies all database operations to Supabase
-- Schema is managed by Main App (no direct database access needed)
-
-## License
-
-MIT

package/dist/chunk-SFY6E7TY.mjs

@@ -1,132 +0,0 @@
-import {
-  AuthenticationError,
-  DeveloperApiError,
-  NotFoundError,
-  ServerError,
-  ValidationError
-} from "./chunk-UPXEAZIT.mjs";
-
-// src/cli/client.ts
-var CliApiClient = class {
-  constructor(baseUrl, apiKey, appId) {
-    this.baseUrl = baseUrl.replace(/\/$/, "");
-    this.apiKey = apiKey;
-    this.appId = appId;
-  }
-  getHeaders(extra) {
-    const headers = {
-      "Content-Type": "application/json",
-      "Authorization": `Bearer ${this.apiKey}`
-    };
-    if (this.appId) headers["x-app-id"] = this.appId;
-    return { ...headers, ...extra };
-  }
-  async handleResponse(response) {
-    let data;
-    try {
-      data = await response.json();
-    } catch {
-      data = {};
-    }
-    if (response.ok) return data;
-    const message = data?.message || data?.error || response.statusText || "Request failed";
-    switch (response.status) {
-      case 400:
-        throw new ValidationError(message);
-      case 401:
-      case 403:
-        throw new AuthenticationError(message);
-      case 404:
-        throw new NotFoundError(message);
-      case 500:
-      case 502:
-      case 503:
-        throw new ServerError(message);
-      default:
-        throw new DeveloperApiError(response.status, "API_ERROR", message);
-    }
-  }
-  async request(method, path, body) {
-    const url = `${this.baseUrl}/cli${path}`;
-    const response = await fetch(url, {
-      method,
-      headers: this.getHeaders(),
-      body: body !== void 0 ? JSON.stringify(body) : void 0
-    });
-    return this.handleResponse(response);
-  }
-};
-
-// src/cli/namespace.ts
-var CliApiNamespace = class {
-  constructor(baseUrl, apiKey, appId) {
-    this._client = new CliApiClient(baseUrl, apiKey, appId);
-  }
-  async prepare() {
-    return this._client.request("GET", "/prepare");
-  }
-  async listWorkspaces() {
-    return this._client.request("GET", "/list-workspaces");
-  }
-  async createWorkspace(body) {
-    return this._client.request("POST", "/create-workspace", body);
-  }
-  async getWorkspace(workspaceSlug) {
-    return this._client.request("GET", `/get-workspace/${encodeURIComponent(workspaceSlug)}`);
-  }
-  async renameWorkspace(workspaceSlug, body) {
-    return this._client.request("POST", `/rename-workspace/${encodeURIComponent(workspaceSlug)}`, body);
-  }
-  async deleteWorkspace(workspaceSlug) {
-    return this._client.request("DELETE", `/delete-workspace/${encodeURIComponent(workspaceSlug)}`);
-  }
-  async setWorkspaceDefaultAgent(workspaceSlug, body) {
-    return this._client.request("POST", `/set-workspace-default-agent/${encodeURIComponent(workspaceSlug)}`, body);
-  }
-  async clearWorkspaceDefaultAgent(workspaceSlug) {
-    return this._client.request("DELETE", `/clear-workspace-default-agent/${encodeURIComponent(workspaceSlug)}`);
-  }
-  async listThreads(workspaceSlug) {
-    return this._client.request("GET", `/list-threads/${encodeURIComponent(workspaceSlug)}`);
-  }
-  async createThread(workspaceSlug, body) {
-    return this._client.request("POST", `/create-thread/${encodeURIComponent(workspaceSlug)}`, body);
-  }
-  async getThread(workspaceSlug, threadSlug) {
-    return this._client.request(
-      "GET",
-      `/get-thread/${encodeURIComponent(workspaceSlug)}/${encodeURIComponent(threadSlug)}`
-    );
-  }
-  async renameThread(workspaceSlug, threadSlug, body) {
-    return this._client.request(
-      "POST",
-      `/rename-thread/${encodeURIComponent(workspaceSlug)}/${encodeURIComponent(threadSlug)}`,
-      body
-    );
-  }
-  async deleteThread(workspaceSlug, threadSlug) {
-    return this._client.request(
-      "DELETE",
-      `/delete-thread/${encodeURIComponent(workspaceSlug)}/${encodeURIComponent(threadSlug)}`
-    );
-  }
-  async sendLlmMessage(workspaceSlug, threadSlug, body) {
-    return this._client.request(
-      "POST",
-      `/send-llm-message/${encodeURIComponent(workspaceSlug)}/${encodeURIComponent(threadSlug)}`,
-      body
-    );
-  }
-  async listLlmProviders() {
-    return this._client.request("GET", "/list-llm-providers");
-  }
-  async listLlmModels(provider) {
-    return this._client.request("GET", `/list-llm-models/${encodeURIComponent(provider)}`);
-  }
-};
-
-export {
-  CliApiClient,
-  CliApiNamespace
-};

package/dist/chunk-UPXEAZIT.mjs

@@ -1,41 +0,0 @@
-// src/v1/errors.ts
-var DeveloperApiError = class extends Error {
-  constructor(status, code, message) {
-    super(message);
-    this.status = status;
-    this.code = code;
-    this.name = "DeveloperApiError";
-  }
-};
-var AuthenticationError = class extends DeveloperApiError {
-  constructor(message = "Invalid or missing API key") {
-    super(403, "AUTHENTICATION_ERROR", message);
-    this.name = "AuthenticationError";
-  }
-};
-var NotFoundError = class extends DeveloperApiError {
-  constructor(message = "Resource not found") {
-    super(404, "NOT_FOUND", message);
-    this.name = "NotFoundError";
-  }
-};
-var ValidationError = class extends DeveloperApiError {
-  constructor(message) {
-    super(400, "VALIDATION_ERROR", message);
-    this.name = "ValidationError";
-  }
-};
-var ServerError = class extends DeveloperApiError {
-  constructor(message = "Internal server error") {
-    super(500, "SERVER_ERROR", message);
-    this.name = "ServerError";
-  }
-};
-
-export {
-  DeveloperApiError,
-  AuthenticationError,
-  NotFoundError,
-  ValidationError,
-  ServerError
-};