@realtimex/sdk 2.0.16 → 2.0.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +10 -43
- package/skills/realtimex-moderator-sdk/SKILL.md +34 -6
- package/README.md +0 -382
- package/dist/chunk-SFY6E7TY.mjs +0 -132
- package/dist/chunk-UPXEAZIT.mjs +0 -41
- package/dist/chunk-XKQRTTIC.mjs +0 -567
- package/dist/cli/index.d.mts +0 -54
- package/dist/cli/index.d.ts +0 -54
- package/dist/cli/index.js +0 -185
- package/dist/cli/index.mjs +0 -9
- package/dist/errors-DwEt8WYf.d.mts +0 -399
- package/dist/errors-DwEt8WYf.d.ts +0 -399
- package/dist/index.d.mts +0 -32
- package/dist/index.d.ts +0 -32
- package/dist/index.js +0 -785
- package/dist/index.mjs +0 -59
- package/dist/v1/index.d.mts +0 -64
- package/dist/v1/index.d.ts +0 -64
- package/dist/v1/index.js +0 -733
- package/dist/v1/index.mjs +0 -124
package/package.json
CHANGED
|
@@ -1,61 +1,28 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@realtimex/sdk",
|
|
3
|
-
"version": "2.0.
|
|
4
|
-
"description": "SDK
|
|
5
|
-
"
|
|
6
|
-
"module": "dist/index.mjs",
|
|
7
|
-
"types": "dist/index.d.ts",
|
|
8
|
-
"exports": {
|
|
9
|
-
".": {
|
|
10
|
-
"types": "./dist/index.d.ts",
|
|
11
|
-
"import": "./dist/index.mjs",
|
|
12
|
-
"require": "./dist/index.js"
|
|
13
|
-
},
|
|
14
|
-
"./v1": {
|
|
15
|
-
"types": "./dist/v1/index.d.ts",
|
|
16
|
-
"import": "./dist/v1/index.mjs",
|
|
17
|
-
"require": "./dist/v1/index.js"
|
|
18
|
-
},
|
|
19
|
-
"./cli": {
|
|
20
|
-
"types": "./dist/cli/index.d.ts",
|
|
21
|
-
"import": "./dist/cli/index.mjs",
|
|
22
|
-
"require": "./dist/cli/index.js"
|
|
23
|
-
}
|
|
24
|
-
},
|
|
3
|
+
"version": "2.0.18",
|
|
4
|
+
"description": "RealtimeX SDK package assets, including the moderator agent skill.",
|
|
5
|
+
"private": false,
|
|
25
6
|
"scripts": {
|
|
26
|
-
"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",
|
|
27
|
-
"dev": "tsup src/index.ts src/v1/index.ts src/cli/index.ts --format cjs,esm --dts --watch",
|
|
28
|
-
"test": "vitest run --passWithNoTests",
|
|
29
|
-
"sdk:generate": "node ../scripts/generate-v1-sdk.mjs",
|
|
30
|
-
"sdk:generate:force": "node ../scripts/generate-v1-sdk.mjs --force",
|
|
31
|
-
"sdk:diff": "node ../scripts/generate-v1-sdk.mjs --dry-run",
|
|
32
7
|
"skill:generate": "node ../scripts/generate-skill.mjs --force",
|
|
33
|
-
"skill:local-test": "node ../scripts/local-test-realtimex-skill.mjs",
|
|
34
8
|
"pp-cli:build": "node ../scripts/build-pp-cli-packages.mjs",
|
|
35
|
-
"pp-cli:publish": "node ../scripts/publish-pp-cli-packages.mjs"
|
|
36
|
-
"prepublishOnly": "npm run build && npm run skill:generate"
|
|
9
|
+
"pp-cli:publish": "node ../scripts/publish-pp-cli-packages.mjs"
|
|
37
10
|
},
|
|
38
11
|
"keywords": [
|
|
39
12
|
"realtimex",
|
|
40
|
-
"
|
|
41
|
-
"
|
|
42
|
-
"supabase"
|
|
13
|
+
"cli",
|
|
14
|
+
"agent-skill"
|
|
43
15
|
],
|
|
44
16
|
"author": "RealtimeX Team",
|
|
45
17
|
"license": "MIT",
|
|
46
|
-
"
|
|
47
|
-
"
|
|
48
|
-
"rollup": "^4.55.1",
|
|
49
|
-
"tsup": "^8.0.0",
|
|
50
|
-
"typescript": "^5.3.0",
|
|
51
|
-
"vitest": "^1.0.0"
|
|
18
|
+
"engines": {
|
|
19
|
+
"node": ">=18.0.0"
|
|
52
20
|
},
|
|
53
21
|
"files": [
|
|
54
|
-
"dist",
|
|
55
22
|
"skills",
|
|
56
23
|
"README.md"
|
|
57
24
|
],
|
|
58
|
-
"
|
|
59
|
-
"
|
|
25
|
+
"publishConfig": {
|
|
26
|
+
"access": "public"
|
|
60
27
|
}
|
|
61
28
|
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: realtimex-moderator-sdk
|
|
3
|
-
description: "Use the RealTimeX API through the generated CLI for workspace, thread, terminal-agent sessions, channel (Telegram, Zalo, Discord), skills, plugins and send messages, setup personality, heartbeat tasks operations, run tour guide to setup working dir."
|
|
3
|
+
description: "Use the RealTimeX API through the generated CLI for workspace, thread, terminal-agent sessions, channel (Telegram, Zalo, Discord), skills, plugins and send messages, setup personality, heartbeat tasks operations, publish and manage artifacts, run tour guide to setup working dir."
|
|
4
4
|
author: ""
|
|
5
5
|
license: "Apache-2.0"
|
|
6
6
|
argument-hint: "<command> [args] | install cli"
|
|
@@ -20,15 +20,15 @@ This skill drives the `realtimex-pp-cli` binary. Verify the CLI is installed and
|
|
|
20
20
|
|
|
21
21
|
1. Install or reinstall the pinned version via npm:
|
|
22
22
|
```bash
|
|
23
|
-
npm install -g @realtimex/pp-cli@2.0.
|
|
23
|
+
npm install -g @realtimex/pp-cli@2.0.18
|
|
24
24
|
```
|
|
25
25
|
2. Verify the exact version:
|
|
26
26
|
```bash
|
|
27
27
|
realtimex-pp-cli --version
|
|
28
28
|
```
|
|
29
|
-
The output must be `realtimex-pp-cli 2.0.
|
|
29
|
+
The output must be `realtimex-pp-cli 2.0.18`.
|
|
30
30
|
|
|
31
|
-
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.
|
|
31
|
+
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.
|
|
32
32
|
|
|
33
33
|
* Always run first:
|
|
34
34
|
|
|
@@ -86,6 +86,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
|
|
|
86
86
|
|
|
87
87
|
- `realtimex-pp-cli enable-workspace-agent-skill <workspaceSlug> <skillId>` — Enable one agent skill in a workspace. Use a skill id, name, or displayName from list-workspace-agent-skills.
|
|
88
88
|
|
|
89
|
+
**get-artifact** — Manage get artifact
|
|
90
|
+
|
|
91
|
+
- `realtimex-pp-cli get-artifact <artifactId>` — Get one public artifact by artifact id.
|
|
92
|
+
|
|
89
93
|
**get-thread** — Manage get thread
|
|
90
94
|
|
|
91
95
|
- `realtimex-pp-cli get-thread <workspaceSlug> <threadSlug>` — Get one thread by exact workspace slug and exact thread slug.
|
|
@@ -98,6 +102,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
|
|
|
98
102
|
|
|
99
103
|
- `realtimex-pp-cli list-agent-skills` — List published agent skills. Use list-workspace-agent-skills to see enabled/disabled state for one workspace.
|
|
100
104
|
|
|
105
|
+
**list-artifacts** — Manage list artifacts
|
|
106
|
+
|
|
107
|
+
- `realtimex-pp-cli list-artifacts <workspaceSlug>` — List public artifacts for one exact workspace slug. Revoked artifacts are hidden unless includeRevoked=true is passed.
|
|
108
|
+
|
|
101
109
|
**list-channels** — Manage list channels
|
|
102
110
|
|
|
103
111
|
- `realtimex-pp-cli list-channels` — List configured chat channels. Use returned channel ids with update-channel.
|
|
@@ -138,10 +146,18 @@ If `--version` reports "command not found" after install, the npm global bin dir
|
|
|
138
146
|
|
|
139
147
|
- `realtimex-pp-cli open-terminal-session` — Open a new desktop terminal session for one terminal CLI agent. Use list-terminal-agents or prepare.
|
|
140
148
|
|
|
149
|
+
**pause-artifact** — Manage pause artifact
|
|
150
|
+
|
|
151
|
+
- `realtimex-pp-cli pause-artifact <artifactId>` — Pause one published artifact by artifact id. Paused artifacts remain listed but stop serving publicly.
|
|
152
|
+
|
|
141
153
|
**prepare** — Manage prepare
|
|
142
154
|
|
|
143
155
|
- `realtimex-pp-cli prepare` — Return compact workspace, thread, current workspace/thread from explicit workspaceSlug and threadSlug query parameters
|
|
144
156
|
|
|
157
|
+
**publish-artifact** — Manage publish artifact
|
|
158
|
+
|
|
159
|
+
- `realtimex-pp-cli publish-artifact <workspaceSlug>` — Publish a browser-viewable file or folder under a workspace artifacts directory.
|
|
160
|
+
|
|
145
161
|
**reload-agent-skills** — Manage reload agent skills
|
|
146
162
|
|
|
147
163
|
- `realtimex-pp-cli reload-agent-skills` — Force reload all enabled agent skills into one workspace working directory.
|
|
@@ -158,6 +174,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
|
|
|
158
174
|
|
|
159
175
|
- `realtimex-pp-cli rename-workspace <workspaceSlug>` — Rename one workspace by exact workspace slug. Only the name is changed.
|
|
160
176
|
|
|
177
|
+
**resume-artifact** — Manage resume artifact
|
|
178
|
+
|
|
179
|
+
- `realtimex-pp-cli resume-artifact <artifactId>` — Resume one paused artifact by artifact id.
|
|
180
|
+
|
|
161
181
|
**resume-latest-terminal-session** — Manage resume latest terminal session
|
|
162
182
|
|
|
163
183
|
- `realtimex-pp-cli resume-latest-terminal-session` — Resume the latest terminal runtime session for one exact thread.
|
|
@@ -166,6 +186,10 @@ If `--version` reports "command not found" after install, the npm global bin dir
|
|
|
166
186
|
|
|
167
187
|
- `realtimex-pp-cli resume-terminal-session <sessionId>` — Resume a terminal runtime session by attaching a CLI controller.
|
|
168
188
|
|
|
189
|
+
**revoke-artifact** — Manage revoke artifact
|
|
190
|
+
|
|
191
|
+
- `realtimex-pp-cli revoke-artifact <artifactId>` — Revoke one artifact by artifact id.
|
|
192
|
+
|
|
169
193
|
**run-automation-workflow** — Manage run automation workflow
|
|
170
194
|
|
|
171
195
|
- `realtimex-pp-cli run-automation-workflow` — Run any app automation flow or scenario exposed via flowMetadata.cli.enabled=true by passing workflowName.
|
|
@@ -372,9 +396,9 @@ Verify: `claude mcp list`
|
|
|
372
396
|
```bash
|
|
373
397
|
realtimex-pp-cli --version
|
|
374
398
|
```
|
|
375
|
-
If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.
|
|
399
|
+
If the command is missing or the output is not exactly `realtimex-pp-cli 2.0.18`, reinstall the pinned version:
|
|
376
400
|
```bash
|
|
377
|
-
npm install -g @realtimex/pp-cli@2.0.
|
|
401
|
+
npm install -g @realtimex/pp-cli@2.0.18
|
|
378
402
|
```
|
|
379
403
|
Then run `realtimex-pp-cli --version` again and proceed only after exact-version verification succeeds.
|
|
380
404
|
2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
|
|
@@ -469,3 +493,7 @@ For personality and heartbeat setup:
|
|
|
469
493
|
For `setup-working-dir` and `run-automation-workflow*`:
|
|
470
494
|
|
|
471
495
|
* Never auto retry on error code 500 or timeout, just inform error to user
|
|
496
|
+
|
|
497
|
+
For `publish-artifact`:
|
|
498
|
+
|
|
499
|
+
* files or folders have to be placed in <working-dir>/artifacts/ to be able to published
|
package/README.md
DELETED
|
@@ -1,382 +0,0 @@
|
|
|
1
|
-
# RealtimeX Local App SDK
|
|
2
|
-
|
|
3
|
-
TypeScript/JavaScript SDK for building Local Apps that integrate with RealtimeX.
|
|
4
|
-
|
|
5
|
-
## Installation
|
|
6
|
-
|
|
7
|
-
```bash
|
|
8
|
-
npm install @realtimex/sdk
|
|
9
|
-
```
|
|
10
|
-
|
|
11
|
-
## Prerequisites
|
|
12
|
-
|
|
13
|
-
Before using this SDK, ensure your Supabase database is set up:
|
|
14
|
-
|
|
15
|
-
1. Open **RealtimeX Main App** → **Local Apps** → Your App → **Configure**
|
|
16
|
-
2. Enter your Supabase **URL** and **Anon Key**
|
|
17
|
-
3. Select **Compatible Mode** and click **Login to Supabase**
|
|
18
|
-
4. Click **Auto-Setup Schema** to create the required tables and functions
|
|
19
|
-
|
|
20
|
-
> **Note:** Schema setup is handled entirely by the Main App. You don't need to run any SQL manually.
|
|
21
|
-
|
|
22
|
-
## Quick Start
|
|
23
|
-
|
|
24
|
-
```typescript
|
|
25
|
-
import { RealtimeXSDK } from '@realtimex/sdk';
|
|
26
|
-
|
|
27
|
-
const sdk = new RealtimeXSDK({
|
|
28
|
-
// Development Mode: Use API key for full access
|
|
29
|
-
realtimex: { apiKey: 'sk-abc123...' },
|
|
30
|
-
// OR Production Mode: Declare permissions
|
|
31
|
-
permissions: ['activities.read', 'activities.write', 'webhook.trigger']
|
|
32
|
-
});
|
|
33
|
-
|
|
34
|
-
// Insert activity
|
|
35
|
-
const activity = await sdk.activities.insert({
|
|
36
|
-
type: 'new_lead',
|
|
37
|
-
email: 'user@example.com',
|
|
38
|
-
});
|
|
39
|
-
|
|
40
|
-
// Trigger agent (optional - for auto-processing)
|
|
41
|
-
await sdk.webhook.triggerAgent({
|
|
42
|
-
raw_data: activity,
|
|
43
|
-
auto_run: true,
|
|
44
|
-
agent_name: 'processor',
|
|
45
|
-
workspace_slug: 'sales',
|
|
46
|
-
thread_slug: 'general', //create_new for new thread
|
|
47
|
-
prompt: 'Process this lead',//optional
|
|
48
|
-
});
|
|
49
|
-
```
|
|
50
|
-
|
|
51
|
-
## How It Works
|
|
52
|
-
|
|
53
|
-
When you start your Local App from the RealtimeX Main App:
|
|
54
|
-
|
|
55
|
-
1. Environment variables `RTX_APP_ID` and `RTX_APP_NAME` are automatically set
|
|
56
|
-
2. The SDK auto-detects these - no manual configuration needed
|
|
57
|
-
3. All operations go through the Main App's proxy endpoints
|
|
58
|
-
|
|
59
|
-
## Configuration (Optional)
|
|
60
|
-
|
|
61
|
-
```typescript
|
|
62
|
-
const sdk = new RealtimeXSDK({
|
|
63
|
-
realtimex: {
|
|
64
|
-
url: 'http://custom-host:3001', // Default: localhost:3001
|
|
65
|
-
apiKey: 'sk-abc123...', // Development mode
|
|
66
|
-
appId: 'custom-id', // Production mode (override)
|
|
67
|
-
appName: 'My App', // Optional
|
|
68
|
-
}
|
|
69
|
-
});
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
## API Reference
|
|
73
|
-
|
|
74
|
-
### Activities CRUD
|
|
75
|
-
|
|
76
|
-
```typescript
|
|
77
|
-
// Insert
|
|
78
|
-
const activity = await sdk.activities.insert({ type: 'order', amount: 100 });
|
|
79
|
-
|
|
80
|
-
// List
|
|
81
|
-
const pending = await sdk.activities.list({ status: 'pending', limit: 50 });
|
|
82
|
-
|
|
83
|
-
// Get
|
|
84
|
-
const item = await sdk.activities.get('activity-uuid');
|
|
85
|
-
|
|
86
|
-
// Update
|
|
87
|
-
await sdk.activities.update('activity-uuid', { status: 'processed' });
|
|
88
|
-
|
|
89
|
-
// Delete
|
|
90
|
-
await sdk.activities.delete('activity-uuid');
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
### Webhook - Trigger Agent
|
|
94
|
-
|
|
95
|
-
```typescript
|
|
96
|
-
// Manual mode (creates calendar event only)
|
|
97
|
-
await sdk.webhook.triggerAgent({
|
|
98
|
-
raw_data: { email: 'customer@example.com' },
|
|
99
|
-
});
|
|
100
|
-
|
|
101
|
-
// Auto-run mode (creates event and triggers agent immediately)
|
|
102
|
-
await sdk.webhook.triggerAgent({
|
|
103
|
-
raw_data: activity,
|
|
104
|
-
auto_run: true,
|
|
105
|
-
agent_name: 'processor',
|
|
106
|
-
workspace_slug: 'sales',
|
|
107
|
-
thread_slug: 'optional-thread', // Optional: specific thread
|
|
108
|
-
});
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
### Contract Discovery
|
|
112
|
-
|
|
113
|
-
```typescript
|
|
114
|
-
// Read canonical contract metadata published by Main App
|
|
115
|
-
const contract = await sdk.contract.getLocalAppV1();
|
|
116
|
-
|
|
117
|
-
console.log(contract.version); // local-app-contract/v1
|
|
118
|
-
console.log(contract.supported_events); // task.trigger, task.claimed, ...
|
|
119
|
-
console.log(contract.callback?.signature_header); // x-rtx-contract-signature
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
### Worker Callback Lifecycle
|
|
123
|
-
|
|
124
|
-
Use this when your worker receives `task_uuid`, `attempt_id`, and callback metadata from RealtimeX task context.
|
|
125
|
-
|
|
126
|
-
```typescript
|
|
127
|
-
sdk.task.configureContract({
|
|
128
|
-
callbackSecret: process.env.RTX_CONTRACT_CALLBACK_SECRET,
|
|
129
|
-
signCallbacksByDefault: true,
|
|
130
|
-
});
|
|
131
|
-
|
|
132
|
-
await sdk.task.claim(taskUuid, {
|
|
133
|
-
callbackUrl,
|
|
134
|
-
machineId,
|
|
135
|
-
attemptId,
|
|
136
|
-
userEmail,
|
|
137
|
-
});
|
|
138
|
-
|
|
139
|
-
await sdk.task.start(taskUuid, {
|
|
140
|
-
callbackUrl,
|
|
141
|
-
machineId,
|
|
142
|
-
attemptId,
|
|
143
|
-
});
|
|
144
|
-
|
|
145
|
-
await sdk.task.progress(taskUuid, { percent: 50, message: 'Halfway done' }, {
|
|
146
|
-
callbackUrl,
|
|
147
|
-
machineId,
|
|
148
|
-
attemptId,
|
|
149
|
-
});
|
|
150
|
-
|
|
151
|
-
await sdk.task.complete(taskUuid, { summary: 'Done' }, {
|
|
152
|
-
callbackUrl,
|
|
153
|
-
machineId,
|
|
154
|
-
attemptId,
|
|
155
|
-
});
|
|
156
|
-
```
|
|
157
|
-
|
|
158
|
-
`TaskModule` auto-populates:
|
|
159
|
-
- `event_id` for idempotency
|
|
160
|
-
- canonical `event` names
|
|
161
|
-
- optional HMAC signature header (`x-rtx-contract-signature`) when signing is enabled
|
|
162
|
-
- legacy `action` alongside canonical `event` for compatibility when posting to callback URLs
|
|
163
|
-
|
|
164
|
-
### Contract Compatibility Check
|
|
165
|
-
|
|
166
|
-
Run the cross-language harness (Main App endpoint + TypeScript SDK + Python SDK):
|
|
167
|
-
|
|
168
|
-
```bash
|
|
169
|
-
RTX_API_KEY=sk-... RTX_CONTRACT_VERIFY_BASE_URL=http://127.0.0.1:3001 npm run contract:verify
|
|
170
|
-
```
|
|
171
|
-
|
|
172
|
-
### Public APIs
|
|
173
|
-
|
|
174
|
-
```typescript
|
|
175
|
-
// Get available agents in a workspace
|
|
176
|
-
const agents = await sdk.api.getAgents();
|
|
177
|
-
|
|
178
|
-
// Get all workspaces
|
|
179
|
-
const workspaces = await sdk.api.getWorkspaces();
|
|
180
|
-
|
|
181
|
-
// Get threads in a workspace
|
|
182
|
-
const threads = await sdk.api.getThreads('sales');
|
|
183
|
-
|
|
184
|
-
// Get task status
|
|
185
|
-
const task = await sdk.api.getTask('task-uuid');
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
### LLM Module
|
|
189
|
-
|
|
190
|
-
Access AI capabilities through the RealtimeX proxy:
|
|
191
|
-
|
|
192
|
-
```typescript
|
|
193
|
-
const sdk = new RealtimeXSDK({
|
|
194
|
-
permissions: ['llm.chat', 'llm.embed', 'llm.providers', 'vectors.write', 'vectors.read']
|
|
195
|
-
});
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
#### List Providers & Models
|
|
199
|
-
|
|
200
|
-
```typescript
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
// Get only configured Chat providers (recommended)
|
|
204
|
-
const chatRes = await sdk.llm.chatProviders();
|
|
205
|
-
// chatRes.providers: Array of chat providers with models
|
|
206
|
-
|
|
207
|
-
// Get only configured Embedding providers (recommended)
|
|
208
|
-
const embedRes = await sdk.llm.embedProviders();
|
|
209
|
-
// embedRes.providers: Array of embedding providers with models
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
#### Chat Completion
|
|
214
|
-
|
|
215
|
-
```typescript
|
|
216
|
-
// Sync Chat
|
|
217
|
-
const response = await sdk.llm.chat(
|
|
218
|
-
[
|
|
219
|
-
{ role: 'system', content: 'You are a helpful assistant.' },
|
|
220
|
-
{ role: 'user', content: 'What is RealtimeX?' }
|
|
221
|
-
],
|
|
222
|
-
{
|
|
223
|
-
model: 'gpt-4o', // Optional: specific model
|
|
224
|
-
provider: 'openai', // Optional: specific provider
|
|
225
|
-
temperature: 0.7, // Optional: 0.0-2.0
|
|
226
|
-
max_tokens: 1000 // Optional: max response tokens
|
|
227
|
-
}
|
|
228
|
-
);
|
|
229
|
-
console.log(response.response?.content);
|
|
230
|
-
|
|
231
|
-
// Multimodal Chat (text + file/image blocks)
|
|
232
|
-
const multimodal = await sdk.llm.chat([
|
|
233
|
-
{
|
|
234
|
-
role: 'user',
|
|
235
|
-
content: [
|
|
236
|
-
{ type: 'text', text: 'Summarize the attached document' },
|
|
237
|
-
{ type: 'input_file', file_url: 'https://example.com/report.pdf' },
|
|
238
|
-
{ type: 'input_image', image_url: 'https://example.com/chart.png' }
|
|
239
|
-
]
|
|
240
|
-
}
|
|
241
|
-
]);
|
|
242
|
-
console.log(multimodal.response?.content);
|
|
243
|
-
|
|
244
|
-
// Streaming Chat
|
|
245
|
-
for await (const chunk of sdk.llm.chatStream(messages, options)) {
|
|
246
|
-
process.stdout.write(chunk.textResponse || '');
|
|
247
|
-
}
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
#### Generate Embeddings
|
|
251
|
-
|
|
252
|
-
```typescript
|
|
253
|
-
const { embeddings, dimensions, provider, model } = await sdk.llm.embed(
|
|
254
|
-
['Hello world', 'Goodbye'],
|
|
255
|
-
{ provider: 'openai', model: 'text-embedding-3-small' } // Optional
|
|
256
|
-
);
|
|
257
|
-
// embeddings: number[][] - vector arrays
|
|
258
|
-
// dimensions: number - vector dimension (e.g., 1536)
|
|
259
|
-
```
|
|
260
|
-
|
|
261
|
-
#### Vector Store Operations
|
|
262
|
-
|
|
263
|
-
```typescript
|
|
264
|
-
// Upsert vectors with metadata
|
|
265
|
-
await sdk.llm.vectors.upsert([
|
|
266
|
-
{
|
|
267
|
-
id: 'chunk-1',
|
|
268
|
-
vector: embeddings[0],
|
|
269
|
-
metadata: {
|
|
270
|
-
text: 'Hello world', // Original text (for retrieval)
|
|
271
|
-
documentId: 'doc-1', // Logical grouping
|
|
272
|
-
customField: 'any value' // Any custom metadata
|
|
273
|
-
}
|
|
274
|
-
}
|
|
275
|
-
], {
|
|
276
|
-
workspaceId: 'ws-123' // Optional: physical namespace isolation
|
|
277
|
-
});
|
|
278
|
-
|
|
279
|
-
// Query similar vectors
|
|
280
|
-
const results = await sdk.llm.vectors.query(queryVector, {
|
|
281
|
-
topK: 5, // Number of results
|
|
282
|
-
workspaceId: 'ws-123', // Optional: search in specific workspace
|
|
283
|
-
filter: { documentId: 'doc-1' } // Optional: filter by document
|
|
284
|
-
});
|
|
285
|
-
// returns: { success, results: [{ id, score, metadata }] }
|
|
286
|
-
|
|
287
|
-
// List all workspaces for this app
|
|
288
|
-
const { workspaces } = await sdk.llm.vectors.listWorkspaces();
|
|
289
|
-
// returns: { success, workspaces: ['ws-123', 'default', ...] }
|
|
290
|
-
|
|
291
|
-
// Delete all vectors in a workspace
|
|
292
|
-
await sdk.llm.vectors.delete({
|
|
293
|
-
deleteAll: true,
|
|
294
|
-
workspaceId: 'ws-123'
|
|
295
|
-
});
|
|
296
|
-
```
|
|
297
|
-
|
|
298
|
-
#### High-Level Helpers
|
|
299
|
-
|
|
300
|
-
These combine multiple operations for common RAG patterns:
|
|
301
|
-
|
|
302
|
-
```typescript
|
|
303
|
-
// embedAndStore: Text → Embed → Store (one call)
|
|
304
|
-
await sdk.llm.embedAndStore(
|
|
305
|
-
['Document text 1', 'Document text 2'], // texts to embed
|
|
306
|
-
{
|
|
307
|
-
documentId: 'doc-123', // Optional: logical grouping
|
|
308
|
-
workspaceId: 'ws-456', // Optional: physical isolation
|
|
309
|
-
provider: 'openai', // Optional: embedding provider
|
|
310
|
-
model: 'text-embedding-3-small' // Optional: embedding model
|
|
311
|
-
}
|
|
312
|
-
);
|
|
313
|
-
|
|
314
|
-
// search: Query → Embed → Search (one call)
|
|
315
|
-
const searchResults = await sdk.llm.search(
|
|
316
|
-
'What is RealtimeX?', // search query (text, not vector)
|
|
317
|
-
{
|
|
318
|
-
topK: 5, // Number of results
|
|
319
|
-
workspaceId: 'ws-123', // Optional: search in workspace
|
|
320
|
-
documentId: 'doc-1', // Optional: filter by document
|
|
321
|
-
provider: 'openai', // Optional: embedding provider
|
|
322
|
-
model: 'text-embedding-3-small' // Optional: embedding model
|
|
323
|
-
}
|
|
324
|
-
);
|
|
325
|
-
// returns: [{ id, score, metadata: { text, documentId, ... } }]
|
|
326
|
-
```
|
|
327
|
-
|
|
328
|
-
> **Note on Isolation:**
|
|
329
|
-
> - `workspaceId`: Creates **physical namespace** (`sdk_{appId}_{wsId}`) - data completely isolated
|
|
330
|
-
> - `documentId`: Stored as **metadata**, filtered after search (post-filter)
|
|
331
|
-
|
|
332
|
-
### Error Handling
|
|
333
|
-
|
|
334
|
-
The SDK provides specific error classes for handling LLM-related issues:
|
|
335
|
-
|
|
336
|
-
```typescript
|
|
337
|
-
import { LLMPermissionError, LLMProviderError } from '@realtimex/sdk';
|
|
338
|
-
|
|
339
|
-
try {
|
|
340
|
-
for await (const chunk of sdk.llm.chatStream(messages)) {
|
|
341
|
-
process.stdout.write(chunk.textResponse || '');
|
|
342
|
-
}
|
|
343
|
-
} catch (error) {
|
|
344
|
-
if (error instanceof LLMPermissionError) {
|
|
345
|
-
// Permission not granted: 'llm.chat' etc.
|
|
346
|
-
console.error(`Permission required: ${error.permission}`);
|
|
347
|
-
} else if (error instanceof LLMProviderError) {
|
|
348
|
-
// Provider errors: rate limit, timeout, model unavailable, etc.
|
|
349
|
-
console.error(`Provider error: ${error.message} (code: ${error.code})`);
|
|
350
|
-
// Common codes: LLM_STREAM_ERROR, RATE_LIMIT, PROVIDER_UNAVAILABLE
|
|
351
|
-
}
|
|
352
|
-
}
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
| Error Class | Common Codes | Description |
|
|
356
|
-
|-------------|--------------|-------------|
|
|
357
|
-
| `LLMPermissionError` | `PERMISSION_REQUIRED` | Missing or denied permission |
|
|
358
|
-
| `LLMProviderError` | `LLM_STREAM_ERROR`, `RATE_LIMIT`, `PROVIDER_UNAVAILABLE` | AI provider issues |
|
|
359
|
-
|
|
360
|
-
## Environment Variables
|
|
361
|
-
|
|
362
|
-
| Variable | Description |
|
|
363
|
-
|----------|-------------|
|
|
364
|
-
| `RTX_APP_ID` | Auto-set by Main App when starting your app |
|
|
365
|
-
| `RTX_APP_NAME` | Auto-set by Main App when starting your app |
|
|
366
|
-
|
|
367
|
-
## Architecture
|
|
368
|
-
|
|
369
|
-
```
|
|
370
|
-
┌─────────────────┐ ┌──────────────────┐ ┌─────────────┐
|
|
371
|
-
│ Your App │────▶│ RealtimeX Main │────▶│ Supabase │
|
|
372
|
-
│ (SDK) │ │ App (Proxy) │ │ Database │
|
|
373
|
-
└─────────────────┘ └──────────────────┘ └─────────────┘
|
|
374
|
-
```
|
|
375
|
-
|
|
376
|
-
- Your app uses the SDK to communicate with the Main App
|
|
377
|
-
- Main App proxies all database operations to Supabase
|
|
378
|
-
- Schema is managed by Main App (no direct database access needed)
|
|
379
|
-
|
|
380
|
-
## License
|
|
381
|
-
|
|
382
|
-
MIT
|
package/dist/chunk-SFY6E7TY.mjs
DELETED
|
@@ -1,132 +0,0 @@
|
|
|
1
|
-
import {
|
|
2
|
-
AuthenticationError,
|
|
3
|
-
DeveloperApiError,
|
|
4
|
-
NotFoundError,
|
|
5
|
-
ServerError,
|
|
6
|
-
ValidationError
|
|
7
|
-
} from "./chunk-UPXEAZIT.mjs";
|
|
8
|
-
|
|
9
|
-
// src/cli/client.ts
|
|
10
|
-
var CliApiClient = class {
|
|
11
|
-
constructor(baseUrl, apiKey, appId) {
|
|
12
|
-
this.baseUrl = baseUrl.replace(/\/$/, "");
|
|
13
|
-
this.apiKey = apiKey;
|
|
14
|
-
this.appId = appId;
|
|
15
|
-
}
|
|
16
|
-
getHeaders(extra) {
|
|
17
|
-
const headers = {
|
|
18
|
-
"Content-Type": "application/json",
|
|
19
|
-
"Authorization": `Bearer ${this.apiKey}`
|
|
20
|
-
};
|
|
21
|
-
if (this.appId) headers["x-app-id"] = this.appId;
|
|
22
|
-
return { ...headers, ...extra };
|
|
23
|
-
}
|
|
24
|
-
async handleResponse(response) {
|
|
25
|
-
let data;
|
|
26
|
-
try {
|
|
27
|
-
data = await response.json();
|
|
28
|
-
} catch {
|
|
29
|
-
data = {};
|
|
30
|
-
}
|
|
31
|
-
if (response.ok) return data;
|
|
32
|
-
const message = data?.message || data?.error || response.statusText || "Request failed";
|
|
33
|
-
switch (response.status) {
|
|
34
|
-
case 400:
|
|
35
|
-
throw new ValidationError(message);
|
|
36
|
-
case 401:
|
|
37
|
-
case 403:
|
|
38
|
-
throw new AuthenticationError(message);
|
|
39
|
-
case 404:
|
|
40
|
-
throw new NotFoundError(message);
|
|
41
|
-
case 500:
|
|
42
|
-
case 502:
|
|
43
|
-
case 503:
|
|
44
|
-
throw new ServerError(message);
|
|
45
|
-
default:
|
|
46
|
-
throw new DeveloperApiError(response.status, "API_ERROR", message);
|
|
47
|
-
}
|
|
48
|
-
}
|
|
49
|
-
async request(method, path, body) {
|
|
50
|
-
const url = `${this.baseUrl}/cli${path}`;
|
|
51
|
-
const response = await fetch(url, {
|
|
52
|
-
method,
|
|
53
|
-
headers: this.getHeaders(),
|
|
54
|
-
body: body !== void 0 ? JSON.stringify(body) : void 0
|
|
55
|
-
});
|
|
56
|
-
return this.handleResponse(response);
|
|
57
|
-
}
|
|
58
|
-
};
|
|
59
|
-
|
|
60
|
-
// src/cli/namespace.ts
|
|
61
|
-
var CliApiNamespace = class {
|
|
62
|
-
constructor(baseUrl, apiKey, appId) {
|
|
63
|
-
this._client = new CliApiClient(baseUrl, apiKey, appId);
|
|
64
|
-
}
|
|
65
|
-
async prepare() {
|
|
66
|
-
return this._client.request("GET", "/prepare");
|
|
67
|
-
}
|
|
68
|
-
async listWorkspaces() {
|
|
69
|
-
return this._client.request("GET", "/list-workspaces");
|
|
70
|
-
}
|
|
71
|
-
async createWorkspace(body) {
|
|
72
|
-
return this._client.request("POST", "/create-workspace", body);
|
|
73
|
-
}
|
|
74
|
-
async getWorkspace(workspaceSlug) {
|
|
75
|
-
return this._client.request("GET", `/get-workspace/${encodeURIComponent(workspaceSlug)}`);
|
|
76
|
-
}
|
|
77
|
-
async renameWorkspace(workspaceSlug, body) {
|
|
78
|
-
return this._client.request("POST", `/rename-workspace/${encodeURIComponent(workspaceSlug)}`, body);
|
|
79
|
-
}
|
|
80
|
-
async deleteWorkspace(workspaceSlug) {
|
|
81
|
-
return this._client.request("DELETE", `/delete-workspace/${encodeURIComponent(workspaceSlug)}`);
|
|
82
|
-
}
|
|
83
|
-
async setWorkspaceDefaultAgent(workspaceSlug, body) {
|
|
84
|
-
return this._client.request("POST", `/set-workspace-default-agent/${encodeURIComponent(workspaceSlug)}`, body);
|
|
85
|
-
}
|
|
86
|
-
async clearWorkspaceDefaultAgent(workspaceSlug) {
|
|
87
|
-
return this._client.request("DELETE", `/clear-workspace-default-agent/${encodeURIComponent(workspaceSlug)}`);
|
|
88
|
-
}
|
|
89
|
-
async listThreads(workspaceSlug) {
|
|
90
|
-
return this._client.request("GET", `/list-threads/${encodeURIComponent(workspaceSlug)}`);
|
|
91
|
-
}
|
|
92
|
-
async createThread(workspaceSlug, body) {
|
|
93
|
-
return this._client.request("POST", `/create-thread/${encodeURIComponent(workspaceSlug)}`, body);
|
|
94
|
-
}
|
|
95
|
-
async getThread(workspaceSlug, threadSlug) {
|
|
96
|
-
return this._client.request(
|
|
97
|
-
"GET",
|
|
98
|
-
`/get-thread/${encodeURIComponent(workspaceSlug)}/${encodeURIComponent(threadSlug)}`
|
|
99
|
-
);
|
|
100
|
-
}
|
|
101
|
-
async renameThread(workspaceSlug, threadSlug, body) {
|
|
102
|
-
return this._client.request(
|
|
103
|
-
"POST",
|
|
104
|
-
`/rename-thread/${encodeURIComponent(workspaceSlug)}/${encodeURIComponent(threadSlug)}`,
|
|
105
|
-
body
|
|
106
|
-
);
|
|
107
|
-
}
|
|
108
|
-
async deleteThread(workspaceSlug, threadSlug) {
|
|
109
|
-
return this._client.request(
|
|
110
|
-
"DELETE",
|
|
111
|
-
`/delete-thread/${encodeURIComponent(workspaceSlug)}/${encodeURIComponent(threadSlug)}`
|
|
112
|
-
);
|
|
113
|
-
}
|
|
114
|
-
async sendLlmMessage(workspaceSlug, threadSlug, body) {
|
|
115
|
-
return this._client.request(
|
|
116
|
-
"POST",
|
|
117
|
-
`/send-llm-message/${encodeURIComponent(workspaceSlug)}/${encodeURIComponent(threadSlug)}`,
|
|
118
|
-
body
|
|
119
|
-
);
|
|
120
|
-
}
|
|
121
|
-
async listLlmProviders() {
|
|
122
|
-
return this._client.request("GET", "/list-llm-providers");
|
|
123
|
-
}
|
|
124
|
-
async listLlmModels(provider) {
|
|
125
|
-
return this._client.request("GET", `/list-llm-models/${encodeURIComponent(provider)}`);
|
|
126
|
-
}
|
|
127
|
-
};
|
|
128
|
-
|
|
129
|
-
export {
|
|
130
|
-
CliApiClient,
|
|
131
|
-
CliApiNamespace
|
|
132
|
-
};
|