realtimex-sdk 1.0.0__tar.gz

realtimex_sdk-1.0.0/.github/workflows/npm-publish.yml

@@ -0,0 +1,37 @@
+name: Publish to npm
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to publish (e.g., 1.0.0)'
+        required: false
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: typescript
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+      
+      - name: Install dependencies
+        run: npm ci
+      
+      - name: Build
+        run: npm run build
+      
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

realtimex_sdk-1.0.0/.github/workflows/pypi-publish.yml

@@ -0,0 +1,32 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+      
+      - name: Build package
+        run: python -m build
+      
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: twine upload dist/*

realtimex_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.4
+Name: realtimex-sdk
+Version: 1.0.0
+Summary: Python SDK for building Local Apps that integrate with RealtimeX
+Project-URL: Homepage, https://github.com/realtimex/rtx-local-app-sdk
+Project-URL: Documentation, https://docs.realtimex.ai/local-apps
+Project-URL: Repository, https://github.com/realtimex/rtx-local-app-sdk
+Author-email: RealtimeX Team <team@realtimex.ai>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: supabase>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# RealtimeX Local App SDK - Python
+
+Python SDK for building Local Apps that integrate with RealtimeX.
+
+## Installation
+
+```bash
+pip 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 required tables and functions
+
+> **Note:** Schema setup is handled entirely by the Main App.
+
+## Quick Start
+
+```python
+import asyncio
+from realtimex_sdk import RealtimeXSDK, SupabaseConfig, RealtimeXConfig
+
+async def main():
+    # Initialize SDK
+    sdk = RealtimeXSDK(
+        supabase=SupabaseConfig(
+            url="https://your-project.supabase.co",
+            anon_key="your-anon-key"
+        ),
+        realtimex=RealtimeXConfig(
+            url="http://localhost:3001",
+            app_name="My Local App"
+        )
+    )
+    
+    # Insert activity
+    activity = await sdk.activities.insert({
+        "type": "new_lead",
+        "email": "user@example.com"
+    })
+    
+    # Trigger agent (auto-run)
+    result = await sdk.webhook.trigger_agent(
+        raw_data=activity,
+        auto_run=True,
+        agent_name="lead-processor",
+        workspace_slug="sales"
+    )
+    print(f"Task created: {result['task_uuid']}")
+    
+    # Or create calendar event for manual review
+    result = await sdk.webhook.trigger_agent(
+        raw_data=activity,
+        auto_run=False
+    )
+
+asyncio.run(main())
+```
+
+## Environment Variables
+
+When your app is started by the Main App, these are auto-set:
+
+| Variable | Description |
+|----------|-------------|
+| `RTX_APP_ID` | Your app's unique ID |
+| `RTX_APP_NAME` | Your app's display name |
+
+## API Reference
+
+See the main [TypeScript README](../typescript/README.md) for full API documentation.

realtimex_sdk-1.0.0/README.md

@@ -0,0 +1,41 @@
+# RealtimeX Local App SDK
+
+Official SDK for building Local Apps that integrate with RealtimeX.
+
+## Overview
+
+This SDK allows your applications to:
+- Insert and manage activities in Supabase
+- Trigger RealtimeX agents automatically or manually
+- Access RealtimeX APIs for workspaces, agents, and threads
+
+## Available SDKs
+
+| Language | Package | Documentation |
+|----------|---------|---------------|
+| TypeScript/JavaScript | `@realtimex/local-app-sdk` | [TypeScript README](./typescript/README.md) |
+| Python | `realtimex-sdk` | [Python README](./python/README.md) |
+
+
+## Prerequisites
+
+Before using the SDK, set up your Supabase database via the RealtimeX Main App:
+
+1. Open **RealtimeX** → **Local Apps** → Your App → **Configure**
+2. Enter your Supabase **URL** and **Anon Key**
+3. Select **Compatible Mode** → **Login to Supabase** → **Auto-Setup Schema**
+
+> Schema setup is handled entirely by the Main App - no manual SQL required.
+
+## Architecture
+
+```
+┌─────────────────┐     ┌──────────────────┐     ┌─────────────┐
+│   Your App      │────▶│  RealtimeX Main  │────▶│  Supabase   │
+│   (SDK)         │     │  App (Proxy)     │     │  Database   │
+└─────────────────┘     └──────────────────┘     └─────────────┘
+```
+
+## License
+
+MIT

realtimex_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "realtimex-sdk"
+version = "1.0.0"
+description = "Python SDK for building Local Apps that integrate with RealtimeX"
+readme = "python/README.md"
+license = "MIT"
+authors = [
+    { name = "RealtimeX Team", email = "team@realtimex.ai" }
+]
+requires-python = ">=3.8"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "supabase>=2.0.0",
+    "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/realtimex/rtx-local-app-sdk"
+Documentation = "https://docs.realtimex.ai/local-apps"
+Repository = "https://github.com/realtimex/rtx-local-app-sdk"
+
+[tool.hatch.build.targets.wheel]
+packages = ["python/realtimex_sdk"]

realtimex_sdk-1.0.0/python/README.md

@@ -0,0 +1,76 @@
+# RealtimeX Local App SDK - Python
+
+Python SDK for building Local Apps that integrate with RealtimeX.
+
+## Installation
+
+```bash
+pip 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 required tables and functions
+
+> **Note:** Schema setup is handled entirely by the Main App.
+
+## Quick Start
+
+```python
+import asyncio
+from realtimex_sdk import RealtimeXSDK, SupabaseConfig, RealtimeXConfig
+
+async def main():
+    # Initialize SDK
+    sdk = RealtimeXSDK(
+        supabase=SupabaseConfig(
+            url="https://your-project.supabase.co",
+            anon_key="your-anon-key"
+        ),
+        realtimex=RealtimeXConfig(
+            url="http://localhost:3001",
+            app_name="My Local App"
+        )
+    )
+    
+    # Insert activity
+    activity = await sdk.activities.insert({
+        "type": "new_lead",
+        "email": "user@example.com"
+    })
+    
+    # Trigger agent (auto-run)
+    result = await sdk.webhook.trigger_agent(
+        raw_data=activity,
+        auto_run=True,
+        agent_name="lead-processor",
+        workspace_slug="sales"
+    )
+    print(f"Task created: {result['task_uuid']}")
+    
+    # Or create calendar event for manual review
+    result = await sdk.webhook.trigger_agent(
+        raw_data=activity,
+        auto_run=False
+    )
+
+asyncio.run(main())
+```
+
+## Environment Variables
+
+When your app is started by the Main App, these are auto-set:
+
+| Variable | Description |
+|----------|-------------|
+| `RTX_APP_ID` | Your app's unique ID |
+| `RTX_APP_NAME` | Your app's display name |
+
+## API Reference
+
+See the main [TypeScript README](../typescript/README.md) for full API documentation.

realtimex_sdk-1.0.0/python/realtimex_sdk/__init__.py

@@ -0,0 +1,13 @@
+"""
+RealtimeX Local App SDK - Python
+
+SDK for building Local Apps that integrate with RealtimeX.
+"""
+
+from .client import RealtimeXSDK
+from .activities import ActivitiesModule
+from .webhook import WebhookModule
+from .api import ApiModule
+
+__version__ = "1.0.0"
+__all__ = ["RealtimeXSDK", "ActivitiesModule", "WebhookModule", "ApiModule"]

realtimex_sdk-1.0.0/python/realtimex_sdk/activities.py

@@ -0,0 +1,67 @@
+"""
+Activities Module - Supabase CRUD operations
+"""
+
+from typing import Any, Dict, List, Optional
+from supabase import create_client, Client
+
+
+class ActivitiesModule:
+    """CRUD operations for activities table in Supabase."""
+    
+    def __init__(self, supabase_url: str, supabase_key: str):
+        self.supabase: Client = create_client(supabase_url, supabase_key)
+        self.table_name = "activities"
+    
+    async def insert(self, raw_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Insert a new activity."""
+        response = self.supabase.table(self.table_name).insert({
+            "raw_data": raw_data,
+            "status": "pending"
+        }).execute()
+        
+        if not response.data:
+            raise Exception("Failed to insert activity")
+        
+        return response.data[0]
+    
+    async def update(self, id: str, updates: Dict[str, Any]) -> Dict[str, Any]:
+        """Update an existing activity."""
+        response = self.supabase.table(self.table_name).update(
+            updates
+        ).eq("id", id).execute()
+        
+        if not response.data:
+            raise Exception("Failed to update activity")
+        
+        return response.data[0]
+    
+    async def delete(self, id: str) -> None:
+        """Delete an activity."""
+        self.supabase.table(self.table_name).delete().eq("id", id).execute()
+    
+    async def get(self, id: str) -> Optional[Dict[str, Any]]:
+        """Get an activity by ID."""
+        response = self.supabase.table(self.table_name).select(
+            "*"
+        ).eq("id", id).execute()
+        
+        if not response.data:
+            return None
+        
+        return response.data[0]
+    
+    async def list(
+        self,
+        status: Optional[str] = None,
+        limit: int = 50
+    ) -> List[Dict[str, Any]]:
+        """List activities with optional filters."""
+        query = self.supabase.table(self.table_name).select("*")
+        
+        if status:
+            query = query.eq("status", status)
+        
+        response = query.order("created_at", desc=True).limit(limit).execute()
+        
+        return response.data or []

realtimex_sdk-1.0.0/python/realtimex_sdk/api.py

@@ -0,0 +1,64 @@
+"""
+API Module - Call RealtimeX public APIs
+"""
+
+from typing import Any, Dict, List
+import httpx
+
+
+class ApiModule:
+    """Call RealtimeX public API endpoints."""
+    
+    def __init__(self, realtimex_url: str):
+        self.realtimex_url = realtimex_url.rstrip("/")
+    
+    async def get_agents(self) -> List[Dict[str, Any]]:
+        """Get available agents."""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(f"{self.realtimex_url}/api/agents")
+            data = response.json()
+            
+            if not response.is_success:
+                raise Exception(data.get("error", "Failed to get agents"))
+            
+            return data.get("agents", [])
+    
+    async def get_workspaces(self) -> List[Dict[str, Any]]:
+        """Get workspaces."""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(f"{self.realtimex_url}/api/workspaces")
+            data = response.json()
+            
+            if not response.is_success:
+                raise Exception(data.get("error", "Failed to get workspaces"))
+            
+            return data.get("workspaces", [])
+    
+    async def get_threads(self, workspace_slug: str) -> List[Dict[str, Any]]:
+        """Get threads in a workspace."""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                f"{self.realtimex_url}/api/workspaces/{workspace_slug}/threads"
+            )
+            data = response.json()
+            
+            if not response.is_success:
+                raise Exception(data.get("error", "Failed to get threads"))
+            
+            return data.get("threads", [])
+    
+    async def get_task(self, task_uuid: str) -> Dict[str, Any]:
+        """Get task status."""
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                f"{self.realtimex_url}/api/task/{task_uuid}"
+            )
+            data = response.json()
+            
+            if not response.is_success:
+                raise Exception(data.get("error", "Failed to get task"))
+            
+            return {
+                **data.get("task", {}),
+                "runs": data.get("runs", [])
+            }

realtimex_sdk-1.0.0/python/realtimex_sdk/client.py

@@ -0,0 +1,58 @@
+"""
+RealtimeX SDK Client
+"""
+
+from dataclasses import dataclass
+from typing import Optional
+
+from .activities import ActivitiesModule
+from .webhook import WebhookModule
+from .api import ApiModule
+
+
+@dataclass
+class SupabaseConfig:
+    url: str
+    anon_key: str
+
+
+@dataclass
+class RealtimeXConfig:
+    url: str = "http://localhost:3001"  # Default fallback
+    app_name: Optional[str] = None
+
+
+class RealtimeXSDK:
+    """
+    Main SDK client for RealtimeX Local Apps.
+    
+    Example:
+        sdk = RealtimeXSDK(
+            supabase=SupabaseConfig(
+                url="https://xxx.supabase.co",
+                anon_key="your-key"
+            ),
+            realtimex=RealtimeXConfig(
+                app_name="My App"  # url defaults to localhost:3001
+            )
+        )
+    """
+    
+    DEFAULT_REALTIMEX_URL = "http://localhost:3001"
+    
+    def __init__(
+        self,
+        supabase: SupabaseConfig,
+        realtimex: Optional[RealtimeXConfig] = None
+    ):
+        if not supabase.url or not supabase.anon_key:
+            raise ValueError("Supabase URL and anon_key are required")
+        
+        # Fallback realtimex config
+        realtimex_url = realtimex.url if realtimex else self.DEFAULT_REALTIMEX_URL
+        app_name = realtimex.app_name if realtimex else None
+        
+        self.activities = ActivitiesModule(supabase.url, supabase.anon_key)
+        self.webhook = WebhookModule(realtimex_url, app_name)
+        self.api = ApiModule(realtimex_url)
+

realtimex_sdk-1.0.0/python/realtimex_sdk/webhook.py

@@ -0,0 +1,80 @@
+"""
+Webhook Module - Call RealtimeX webhook
+"""
+
+from typing import Any, Dict, Optional
+import httpx
+
+
+class WebhookModule:
+    """Call RealtimeX webhook endpoints."""
+    
+    def __init__(self, realtimex_url: str, app_name: Optional[str] = None):
+        self.realtimex_url = realtimex_url.rstrip("/")
+        self.app_name = app_name
+    
+    async def trigger_agent(
+        self,
+        raw_data: Dict[str, Any],
+        auto_run: bool = False,
+        agent_name: Optional[str] = None,
+        workspace_slug: Optional[str] = None,
+        thread_slug: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Trigger agent via webhook.
+        
+        Args:
+            raw_data: Data to send (required)
+            auto_run: If True, trigger agent immediately (default: False)
+            agent_name: Agent to trigger (required if auto_run)
+            workspace_slug: Workspace (required if auto_run)
+            thread_slug: Thread (optional)
+        
+        Returns:
+            Response with task_uuid and status
+        """
+        if auto_run:
+            if not agent_name or not workspace_slug:
+                raise ValueError("auto_run requires agent_name and workspace_slug")
+        
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                f"{self.realtimex_url}/webhooks/realtimex",
+                json={
+                    "app_name": self.app_name,
+                    "event": "trigger-agent",
+                    "payload": {
+                        "raw_data": raw_data,
+                        "auto_run": auto_run,
+                        "agent_name": agent_name,
+                        "workspace_slug": workspace_slug,
+                        "thread_slug": thread_slug,
+                    }
+                }
+            )
+            
+            data = response.json()
+            
+            if not response.is_success:
+                raise Exception(data.get("error", "Failed to trigger agent"))
+            
+            return data
+    
+    async def ping(self) -> Dict[str, Any]:
+        """Ping webhook to check connection."""
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                f"{self.realtimex_url}/webhooks/realtimex",
+                json={
+                    "app_name": self.app_name,
+                    "event": "ping"
+                }
+            )
+            
+            data = response.json()
+            
+            if not response.is_success:
+                raise Exception(data.get("error", "Ping failed"))
+            
+            return data

realtimex_sdk-1.0.0/typescript/README.md

@@ -0,0 +1,142 @@
+# RealtimeX Local App SDK
+
+TypeScript/JavaScript SDK for building Local Apps that integrate with RealtimeX.
+
+## Installation
+
+```bash
+npm install @realtimex/local-app-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/local-app-sdk';
+
+// No config needed - RTX_APP_ID is auto-detected from environment
+const sdk = new RealtimeXSDK();
+
+// 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',
+});
+```
+
+## 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
+    appId: 'custom-id',               // Override auto-detected
+    appName: 'My App',                // Override auto-detected
+  }
+});
+```
+
+## 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
+});
+```
+
+### 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');
+```
+
+## 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

realtimex_sdk-1.0.0/typescript/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "@realtimex/local-app-sdk",
+    "version": "1.0.0",
+    "description": "SDK for building Local Apps that integrate with RealtimeX",
+    "main": "dist/index.js",
+    "module": "dist/index.mjs",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/index.mjs",
+            "require": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
+    },
+    "scripts": {
+        "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+        "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+        "test": "vitest run",
+        "prepublishOnly": "npm run build"
+    },
+    "keywords": [
+        "realtimex",
+        "local-apps",
+        "sdk",
+        "supabase"
+    ],
+    "author": "RealtimeX Team",
+    "license": "MIT",
+    "dependencies": {},
+    "devDependencies": {
+        "@types/node": "^20.10.0",
+        "tsup": "^8.0.0",
+        "typescript": "^5.3.0",
+        "vitest": "^1.0.0"
+    },
+    "files": [
+        "dist",
+        "README.md"
+    ],
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

realtimex_sdk-1.0.0/typescript/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * RealtimeX Local App SDK
+ * 
+ * SDK for building Local Apps that integrate with RealtimeX
+ * All operations go through RealtimeX Main App proxy
+ */
+
+import { SDKConfig } from './types';
+import { ActivitiesModule } from './modules/activities';
+import { WebhookModule } from './modules/webhook';
+import { ApiModule } from './modules/api';
+
+export class RealtimeXSDK {
+    public activities: ActivitiesModule;
+    public webhook: WebhookModule;
+    public api: ApiModule;
+    public readonly appId: string;
+    public readonly appName: string | undefined;
+
+    private static DEFAULT_REALTIMEX_URL = 'http://localhost:3001';
+
+    constructor(config: SDKConfig = {}) {
+        // Auto-detect app ID from environment (injected by Main App)
+        const envAppId = this.getEnvVar('RTX_APP_ID');
+        const envAppName = this.getEnvVar('RTX_APP_NAME');
+
+        this.appId = config.realtimex?.appId || envAppId || '';
+        this.appName = config.realtimex?.appName || envAppName;
+
+        // Default to localhost:3001
+        const realtimexUrl = config.realtimex?.url || RealtimeXSDK.DEFAULT_REALTIMEX_URL;
+
+        // Initialize modules
+        this.activities = new ActivitiesModule(realtimexUrl, this.appId);
+        this.webhook = new WebhookModule(realtimexUrl, this.appName, this.appId);
+        this.api = new ApiModule(realtimexUrl);
+    }
+
+    /**
+     * Get environment variable (works in Node.js and browser)
+     */
+    private getEnvVar(name: string): string | undefined {
+        // Node.js environment
+        if (typeof process !== 'undefined' && process.env) {
+            return process.env[name];
+        }
+        // Browser with injected globals
+        if (typeof window !== 'undefined') {
+            return (window as any)[name];
+        }
+        return undefined;
+    }
+}
+
+// Re-export types
+export * from './types';
+
+// Re-export modules for advanced usage
+export { ActivitiesModule } from './modules/activities';
+export { WebhookModule } from './modules/webhook';
+export { ApiModule } from './modules/api';

realtimex_sdk-1.0.0/typescript/src/modules/activities.ts

@@ -0,0 +1,103 @@
+/**
+ * Activities Module - HTTP Proxy to RealtimeX Main App
+ * No direct Supabase access - all operations go through Main App
+ */
+
+import { Activity } from '../types';
+
+export class ActivitiesModule {
+    private baseUrl: string;
+    private appId: string;
+
+    constructor(realtimexUrl: string, appId: string) {
+        this.baseUrl = realtimexUrl.replace(/\/$/, '');
+        this.appId = appId;
+    }
+
+    private async request<T>(
+        path: string,
+        options: RequestInit = {}
+    ): Promise<T> {
+        const url = `${this.baseUrl}/api${path}`;
+        const headers: Record<string, string> = {
+            'Content-Type': 'application/json',
+        };
+
+        // Add app ID header if available
+        if (this.appId) {
+            headers['X-App-Id'] = this.appId;
+        }
+
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                ...headers,
+                ...options.headers,
+            },
+        });
+
+        const data = await response.json();
+        if (!response.ok) {
+            throw new Error(data.error || `Request failed: ${response.status}`);
+        }
+        return data;
+    }
+
+    /**
+     * Insert a new activity
+     */
+    async insert(rawData: Record<string, unknown>): Promise<Activity> {
+        const result = await this.request<{ data: Activity }>('/activities', {
+            method: 'POST',
+            body: JSON.stringify({ raw_data: rawData }),
+        });
+        return result.data;
+    }
+
+    /**
+     * Update an existing activity
+     */
+    async update(id: string, updates: Partial<Activity>): Promise<Activity> {
+        const result = await this.request<{ data: Activity }>(`/activities/${id}`, {
+            method: 'PATCH',
+            body: JSON.stringify(updates),
+        });
+        return result.data;
+    }
+
+    /**
+     * Delete an activity
+     */
+    async delete(id: string): Promise<void> {
+        await this.request<{ success: boolean }>(`/activities/${id}`, {
+            method: 'DELETE',
+        });
+    }
+
+    /**
+     * Get a single activity by ID
+     */
+    async get(id: string): Promise<Activity | null> {
+        try {
+            const result = await this.request<{ data: Activity }>(`/activities/${id}`);
+            return result.data;
+        } catch (error: any) {
+            if (error.message?.includes('not found')) return null;
+            throw error;
+        }
+    }
+
+    /**
+     * List activities with optional filters
+     */
+    async list(options?: { status?: string; limit?: number; offset?: number }): Promise<Activity[]> {
+        const params = new URLSearchParams();
+        if (options?.status) params.set('status', options.status);
+        if (options?.limit) params.set('limit', String(options.limit));
+        if (options?.offset) params.set('offset', String(options.offset));
+
+        const query = params.toString() ? `?${params}` : '';
+        const result = await this.request<{ data: Activity[] }>(`/activities${query}`);
+        return result.data;
+    }
+}

realtimex_sdk-1.0.0/typescript/src/modules/api.ts

@@ -0,0 +1,41 @@
+/**
+ * API Module - Call RealtimeX public APIs
+ */
+
+import { Agent, Workspace, Thread, Task } from '../types';
+
+export class ApiModule {
+    private realtimexUrl: string;
+
+    constructor(realtimexUrl: string) {
+        this.realtimexUrl = realtimexUrl.replace(/\/$/, '');
+    }
+
+    async getAgents(): Promise<Agent[]> {
+        const response = await fetch(`${this.realtimexUrl}/api/agents`);
+        const data = await response.json();
+        if (!response.ok) throw new Error(data.error || 'Failed to get agents');
+        return data.agents;
+    }
+
+    async getWorkspaces(): Promise<Workspace[]> {
+        const response = await fetch(`${this.realtimexUrl}/api/workspaces`);
+        const data = await response.json();
+        if (!response.ok) throw new Error(data.error || 'Failed to get workspaces');
+        return data.workspaces;
+    }
+
+    async getThreads(workspaceSlug: string): Promise<Thread[]> {
+        const response = await fetch(`${this.realtimexUrl}/api/workspaces/${encodeURIComponent(workspaceSlug)}/threads`);
+        const data = await response.json();
+        if (!response.ok) throw new Error(data.error || 'Failed to get threads');
+        return data.threads;
+    }
+
+    async getTask(taskUuid: string): Promise<Task> {
+        const response = await fetch(`${this.realtimexUrl}/api/task/${encodeURIComponent(taskUuid)}`);
+        const data = await response.json();
+        if (!response.ok) throw new Error(data.error || 'Failed to get task');
+        return { ...data.task, runs: data.runs };
+    }
+}

realtimex_sdk-1.0.0/typescript/src/modules/webhook.ts

@@ -0,0 +1,59 @@
+/**
+ * Webhook Module - Call RealtimeX webhook
+ */
+
+import { TriggerAgentPayload, TriggerAgentResponse } from '../types';
+
+export class WebhookModule {
+    private realtimexUrl: string;
+    private appName?: string;
+    private appId?: string;
+
+    constructor(realtimexUrl: string, appName?: string, appId?: string) {
+        this.realtimexUrl = realtimexUrl.replace(/\/$/, '');
+        this.appName = appName;
+        this.appId = appId;
+    }
+
+    async triggerAgent(payload: TriggerAgentPayload): Promise<TriggerAgentResponse> {
+        if (payload.auto_run && (!payload.agent_name || !payload.workspace_slug)) {
+            throw new Error('auto_run requires agent_name and workspace_slug');
+        }
+
+        const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                app_name: this.appName,
+                app_id: this.appId,
+                event: 'trigger-agent',
+                payload: {
+                    raw_data: payload.raw_data,
+                    auto_run: payload.auto_run ?? false,
+                    agent_name: payload.agent_name,
+                    workspace_slug: payload.workspace_slug,
+                    thread_slug: payload.thread_slug,
+                },
+            }),
+        });
+
+        const data = await response.json();
+        if (!response.ok) throw new Error(data.error || 'Failed to trigger agent');
+        return data as TriggerAgentResponse;
+    }
+
+    async ping(): Promise<{ success: boolean; app_name: string; message: string }> {
+        const response = await fetch(`${this.realtimexUrl}/webhooks/realtimex`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                app_name: this.appName,
+                app_id: this.appId,
+                event: 'ping'
+            }),
+        });
+        const data = await response.json();
+        if (!response.ok) throw new Error(data.error || 'Ping failed');
+        return data;
+    }
+}

realtimex_sdk-1.0.0/typescript/src/types.ts

@@ -0,0 +1,86 @@
+/**
+ * RealtimeX Local App SDK - Types
+ */
+
+export interface SDKConfig {
+    realtimex?: {
+        url?: string;     // Default: http://localhost:3001
+        appId?: string;   // Auto-detected from RTX_APP_ID env
+        appName?: string; // Auto-detected from RTX_APP_NAME env
+    };
+}
+
+export interface Activity {
+    id: string;
+    raw_data: Record<string, unknown>;
+    old_data?: Record<string, unknown>;
+    status: 'pending' | 'claimed' | 'completed' | 'failed';
+    locked_by?: string;
+    locked_at?: string;
+    completed_at?: string;
+    error_message?: string;
+    result?: Record<string, unknown>;
+    created_at: string;
+}
+
+export interface TriggerAgentPayload {
+    raw_data: Record<string, unknown>;
+    auto_run?: boolean;
+    agent_name?: string;
+    workspace_slug?: string;
+    thread_slug?: string;
+}
+
+export interface TriggerAgentResponse {
+    success: boolean;
+    task_uuid?: string;
+    calendar_event_uuid?: string;
+    auto_run?: boolean;
+    message?: string;
+    error?: string;
+}
+
+export interface Agent {
+    slug: string;
+    name: string;
+    description?: string;
+    hub_id?: string;
+}
+
+export interface Workspace {
+    id: number;
+    slug: string;
+    name: string;
+    type: string;
+    created_at: string;
+}
+
+export interface Thread {
+    id: number;
+    slug: string;
+    name: string;
+    created_at: string;
+}
+
+export interface TaskRun {
+    id: number;
+    agent_name: string;
+    workspace_slug: string;
+    thread_slug?: string;
+    status: string;
+    started_at?: string;
+    completed_at?: string;
+    error?: string;
+}
+
+export interface Task {
+    uuid: string;
+    title: string;
+    status: string;
+    action_type: string;
+    source_app: string;
+    error?: string;
+    created_at: string;
+    updated_at: string;
+    runs: TaskRun[];
+}

realtimex_sdk-1.0.0/typescript/tsconfig.json

@@ -0,0 +1,31 @@
+{
+    "compilerOptions": {
+        "target": "ES2020",
+        "module": "ESNext",
+        "moduleResolution": "node",
+        "lib": [
+            "ES2020",
+            "DOM"
+        ],
+        "types": [
+            "node"
+        ],
+        "declaration": true,
+        "declarationMap": true,
+        "sourceMap": true,
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "resolveJsonModule": true
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}