@realtimex/sdk 1.5.1 → 1.6.0

package/dist/index.d.mts

@@ -1660,6 +1660,32 @@ declare class AuthModule {
     getAccessToken(): Promise<AuthTokenResponse | null>;
 }
 
+/**
+ * Credentials Module — read-only access to user-managed credentials
+ *
+ * Credential values are encrypted at rest and decrypted only on get().
+ * Values should NEVER be printed to stdout or included in agent responses.
+ */
+
+interface CredentialInfo {
+    name: string;
+    type: "http_header" | "query_auth" | "basic_auth" | "env_var";
+    metadata: Record<string, any> | null;
+}
+interface CredentialPayload {
+    name: string;
+    type: string;
+    payload: Record<string, string>;
+}
+declare class CredentialsModule {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /** List available credentials (names and types, no values). */
+    list(): Promise<CredentialInfo[]>;
+    /** Get a credential's decrypted payload by name. */
+    get(name: string): Promise<CredentialPayload>;
+}
+
 interface ContractHttpClientConfig {
     baseUrl: string;
     appId?: string;
@@ -1987,6 +2013,7 @@ declare class RealtimeXSDK {
     contractRuntime: ContractRuntime;
     database: DatabaseModule;
     auth: AuthModule;
+    credentials: CredentialsModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;

package/dist/index.d.ts

@@ -1660,6 +1660,32 @@ declare class AuthModule {
     getAccessToken(): Promise<AuthTokenResponse | null>;
 }
 
+/**
+ * Credentials Module — read-only access to user-managed credentials
+ *
+ * Credential values are encrypted at rest and decrypted only on get().
+ * Values should NEVER be printed to stdout or included in agent responses.
+ */
+
+interface CredentialInfo {
+    name: string;
+    type: "http_header" | "query_auth" | "basic_auth" | "env_var";
+    metadata: Record<string, any> | null;
+}
+interface CredentialPayload {
+    name: string;
+    type: string;
+    payload: Record<string, string>;
+}
+declare class CredentialsModule {
+    private httpClient;
+    constructor(httpClient: HttpClient);
+    /** List available credentials (names and types, no values). */
+    list(): Promise<CredentialInfo[]>;
+    /** Get a credential's decrypted payload by name. */
+    get(name: string): Promise<CredentialPayload>;
+}
+
 interface ContractHttpClientConfig {
     baseUrl: string;
     appId?: string;
@@ -1987,6 +2013,7 @@ declare class RealtimeXSDK {
     contractRuntime: ContractRuntime;
     database: DatabaseModule;
     auth: AuthModule;
+    credentials: CredentialsModule;
     readonly appId: string;
     readonly appName: string | undefined;
     readonly apiKey: string | undefined;

package/dist/index.js

@@ -3009,6 +3009,33 @@ var AuthModule = class {
   }
 };
 
+// src/modules/credentials.ts
+var CredentialsModule = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /** List available credentials (names and types, no values). */
+  async list() {
+    const response = await this.httpClient.fetch("/sdk/credentials");
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data?.error || "Failed to list credentials");
+    }
+    return data.credentials || [];
+  }
+  /** Get a credential's decrypted payload by name. */
+  async get(name) {
+    const response = await this.httpClient.fetch(
+      `/sdk/credentials/${encodeURIComponent(name)}`
+    );
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data?.error || `Failed to get credential: ${name}`);
+    }
+    return data.credential;
+  }
+};
+
 // src/core/auth/AuthProvider.ts
 var StaticAuthProvider = class {
   constructor(options = {}) {
@@ -3706,6 +3733,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     });
     this.database = new DatabaseModule(this.realtimexUrl, this.appId, this.apiKey);
     this.auth = new AuthModule(this.realtimexUrl, this.appId, this.apiKey);
+    this.credentials = new CredentialsModule(this.httpClient);
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);

package/dist/index.mjs

@@ -2916,6 +2916,33 @@ var AuthModule = class {
   }
 };
 
+// src/modules/credentials.ts
+var CredentialsModule = class {
+  constructor(httpClient) {
+    this.httpClient = httpClient;
+  }
+  /** List available credentials (names and types, no values). */
+  async list() {
+    const response = await this.httpClient.fetch("/sdk/credentials");
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data?.error || "Failed to list credentials");
+    }
+    return data.credentials || [];
+  }
+  /** Get a credential's decrypted payload by name. */
+  async get(name) {
+    const response = await this.httpClient.fetch(
+      `/sdk/credentials/${encodeURIComponent(name)}`
+    );
+    const data = await response.json();
+    if (!response.ok) {
+      throw new Error(data?.error || `Failed to get credential: ${name}`);
+    }
+    return data.credential;
+  }
+};
+
 // src/core/auth/AuthProvider.ts
 var StaticAuthProvider = class {
   constructor(options = {}) {
@@ -3613,6 +3640,7 @@ var _RealtimeXSDK = class _RealtimeXSDK {
     });
     this.database = new DatabaseModule(this.realtimexUrl, this.appId, this.apiKey);
     this.auth = new AuthModule(this.realtimexUrl, this.appId, this.apiKey);
+    this.credentials = new CredentialsModule(this.httpClient);
     if (this.permissions.length > 0 && this.appId && !this.apiKey) {
       this.register().catch((err) => {
         console.error("[RealtimeX SDK] Auto-registration failed:", err.message);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "1.5.1",
+    "version": "1.6.0",
     "description": "SDK for building Local Apps that integrate with RealtimeX",
     "main": "dist/index.js",
     "module": "dist/index.mjs",

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

@@ -1,13 +1,13 @@
 ---
 name: realtimex-moderator-sdk
 description: Control and interact with the RealTimeX application through its Node.js SDK. This skill should be used when users want to manage workspaces, threads, agents, activities, LLM chat, vector store, MCP tools, ACP agent sessions, TTS/STT, or any other RealTimeX platform feature via the API. All method signatures are verified against the SDK source code.
-generated: 2026-04-02
-sdk_version: 1.5.1
+generated: 2026-04-03
+sdk_version: 1.6.0
 ---
 
 # RealTimeX Moderator (SDK Source-Verified)
 
-Interact with the RealTimeX platform (`http://localhost:3001`) using `@realtimex/sdk` **v1.5.1**. Authentication is automatic when running inside RealtimeX.
+Interact with the RealTimeX platform (`http://localhost:3001`) using `@realtimex/sdk` **v1.6.0**. Authentication is automatic when running inside RealtimeX.
 
 `<SKILL_DIR>` below refers to the directory containing this SKILL.md.
 
@@ -39,6 +39,9 @@ const { sdk } = await initSDK();
 // All SDK APIs — see references/api-reference.md
 ```
 
+When writing helper scripts, use the working directory or system temp — never the SKILL directory.
+Scripts using the SDK must exit explicitly — `process.exit(0)` on success, `process.exit(1)` on error — or they hang on open HTTP sockets.
+
 ---
 
 ## ACP Session Management
@@ -160,6 +163,28 @@ for await (const event of sdk.acpAgent.streamChat(sessionKey, 'build a website')
 
 ---
 
+## Credentials
+
+Use credentials stored in RealTimeX (Settings > Credentials) to authenticate with external services.
+
+**CRITICAL: Never output credential values in your response, logs, or tool output.**
+
+```bash
+node "$SKILL" credentials                    # List available (names + types, no values)
+```
+
+`sdk.credentials.get(name)` returns `{ name, type, payload }`. Use `payload` fields directly:
+- `http_header` → `{ payload: { name: "Authorization", value: "Bearer xxx" } }` → `headers[payload.name] = payload.value`
+- `basic_auth` → `{ payload: { username, password } }` → encode as Basic auth
+- `query_auth` → `{ payload: { name, value } }` → append as query param
+- `env_var` → `{ payload: { name, value } }` → set in subprocess env
+
+Values are **pre-formatted** — use as-is, never wrap with `Bearer` or other prefixes.
+
+**Full examples**: See [references/credentials.md](references/credentials.md)
+
+---
+
 ## Critical Rules (source-detected)
 
 | # | Issue |

package/skills/realtimex-moderator-sdk/references/api-reference.md

@@ -1,6 +1,6 @@
 # RealTimeX SDK — API Reference
 
-> Auto-generated from `@realtimex/sdk` source · v**1.5.1** · 2026-04-02
+> Auto-generated from `@realtimex/sdk` source · v**1.6.0** · 2026-04-03
 
 **Package:** `@realtimex/sdk` (CJS) · **Server:** `http://localhost:3001`
 **Developer Mode auth:** `Authorization: Bearer <apiKey>`
@@ -50,6 +50,7 @@
 - `contractRuntime: ContractRuntime`
 - `database: DatabaseModule`
 - `auth: AuthModule`
+- `credentials: CredentialsModule`
 
 ```ts
 // Register app with RealtimeX hub and request declared permissions upfront.

package/skills/realtimex-moderator-sdk/references/credentials.md

@@ -0,0 +1,111 @@
+# Credentials Reference
+
+Credentials are managed by the user in **Settings > Credentials**. Agents have read-only access via `sdk.credentials`.
+
+## Security Rules
+
+1. **Never** print credential values to stdout (they become tool results in chat history)
+2. **Never** include credential values in your response text
+3. **Never** write credential values to files or logs
+4. **Never** pass credential values as CLI arguments (visible in process list)
+5. **Always** consume credentials inside scripts — fetch, use, discard
+6. **Always** call `process.exit(0)` at the end of custom scripts (prevents hanging on open HTTP sockets)
+7. **Never** write helper scripts into the SKILL directory — use the working directory or system temp
+
+## Credential Types
+
+| Type | Payload | How to Apply |
+|------|---------|-------------|
+| `http_header` | `{ name, value }` | Set as HTTP header: `headers[payload.name] = payload.value` |
+| `query_auth` | `{ name, value }` | Append to URL: `?${payload.name}=${payload.value}` |
+| `basic_auth` | `{ username, password }` | Encode: `Authorization: Basic ${btoa(username + ":" + password)}` |
+| `env_var` | `{ name, value }` | Set in subprocess: `env[payload.name] = payload.value` |
+
+## Usage Patterns
+
+### List available credentials
+
+```bash
+node "$SKILL" credentials
+```
+
+Output: table of names and types (no values).
+
+### Important: credential payload structure
+
+`sdk.credentials.get(name)` returns `{ name, type, payload }`. The `payload` object contains structured fields — use them directly. **Never** extract raw values and construct headers manually.
+
+### Use an http_header credential in a script
+
+```javascript
+const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
+(async () => {
+  const { sdk } = await initSDK();
+  const cred = await sdk.credentials.get('github-token');
+  // cred.type === "http_header"
+  // cred.payload === { name: "Authorization", value: "Bearer ghp_xxx" }
+  // The value already includes the full header value — use as-is
+  const res = await fetch('https://api.github.com/user', {
+    headers: { [cred.payload.name]: cred.payload.value }
+  });
+  console.log('Status:', res.status); // Only non-sensitive output
+  process.exit(0);
+})();
+// WRONG: const token = cred.payload.value; headers.Authorization = `Bearer ${token}`
+// The value already contains "Bearer ..." — adding prefix again causes 401
+```
+
+### Use a basic_auth credential
+
+```javascript
+const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
+(async () => {
+  const { sdk } = await initSDK();
+  const cred = await sdk.credentials.get('registry-login');
+  const auth = Buffer.from(cred.payload.username + ':' + cred.payload.password).toString('base64');
+  const res = await fetch('https://registry.example.com/v2/_catalog', {
+    headers: { 'Authorization': 'Basic ' + auth }
+  });
+  console.log('Status:', res.status);
+  process.exit(0);
+})();
+```
+
+### Use an env_var credential with a subprocess
+
+```javascript
+const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
+const { execSync } = require('child_process');
+(async () => {
+  const { sdk } = await initSDK();
+  const cred = await sdk.credentials.get('aws-key');
+  // cred.type === "env_var"
+  // cred.payload === { name: "AWS_ACCESS_KEY_ID", value: "AKIA..." }
+  execSync('aws s3 ls', {
+    env: { ...process.env, [cred.payload.name]: cred.payload.value },
+    stdio: 'inherit'
+  });
+  process.exit(0);
+})();
+```
+
+### Error handling
+
+```javascript
+const { initSDK } = require('<SKILL_DIR>/scripts/lib/sdk-init');
+(async () => {
+  try {
+    const { sdk } = await initSDK();
+    const cred = await sdk.credentials.get('my-key');
+    // use cred...
+    process.exit(0);
+  } catch (err) {
+    if (err.message.includes('not found')) {
+      console.log('Credential not found. Ask the user to add it in Settings > Credentials.');
+    } else {
+      console.log('Error:', err.message);
+    }
+    process.exit(1);
+  }
+})();
+```

package/skills/realtimex-moderator-sdk/references/known-issues.md

@@ -1,6 +1,6 @@
 # Known Issues — Source-Detected
 
-> Auto-generated by `scripts/generate-skill.mjs` · SDK **1.5.1** · 2026-04-02
+> Auto-generated by `scripts/generate-skill.mjs` · SDK **1.6.0** · 2026-04-03
 
 Run `node scripts/generate-skill.mjs --force` after SDK source changes to refresh.
 

package/skills/realtimex-moderator-sdk/scripts/rtx.js

@@ -304,6 +304,13 @@ CMD['mcp-exec'] = async () => {
   print(await sdk.mcp.executeTool(server, tool, argsStr ? JSON.parse(argsStr) : {}, flags.provider));
 };
 
+// -- credentials ------------------------------------------------------------
+CMD['credentials'] = async () => {
+  const { sdk } = await getSDK();
+  const list = await sdk.credentials.list();
+  printTable(list, ['name', 'type']);
+};
+
 // -- acp-agents -------------------------------------------------------------
 // Source: AcpAgentModule.listAgents({ includeModels? })
 // Returns: AcpAgentInfo[] { id, label, handles[], installed, authReady, status }
@@ -797,6 +804,10 @@ sdk.mcp.*:
   mcp-tools <server> [--provider]
   mcp-exec <server> <tool> [<args-json>] [--provider]
 
+sdk.credentials.*:
+  credentials
+    List available credentials (names and types, no values).
+
 sdk.acpAgent.* — Session Management:
   acp-agents [--models=true]
     List available ACP CLI agents.
@@ -871,8 +882,10 @@ sdk.database.* / sdk.auth.*:
     console.error('Unknown command: ' + (command || '(none)') + '\nRun: node rtx.js help');
     process.exit(1);
   }
-  try { await handler(); }
-  catch (err) {
+  try {
+    await handler();
+    process.exit(0);
+  } catch (err) {
     console.error('Error:', err.message || err);
     if (flags.debug) console.error(err);
     process.exit(1);