@realtimex/sdk 2.0.3 → 2.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@realtimex/sdk",
-    "version": "2.0.3",
+    "version": "2.0.4",
     "description": "SDK for building Local Apps that integrate with RealtimeX",
     "main": "dist/index.js",
     "module": "dist/index.mjs",
@@ -27,7 +27,7 @@
         "skill:generate": "node ../scripts/generate-skill.mjs --force",
         "pp-cli:build": "node ../scripts/build-pp-cli-packages.mjs",
         "pp-cli:publish": "node ../scripts/publish-pp-cli-packages.mjs",
-        "prepublishOnly": "npm run build"
+        "prepublishOnly": "npm run build && npm run skill:generate"
     },
     "keywords": [
         "realtimex",

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

@@ -0,0 +1,326 @@
+---
+name: realtimex-moderator-sdk
+description: "Use the RealTimeX API through the generated CLI for workspace, thread, and chat operations."
+author: ""
+license: "Apache-2.0"
+argument-hint: "<command> [args] | install cli"
+allowed-tools: "Read Bash"
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - realtimex-pp-cli
+---
+
+# Realtimex — Printing Press CLI
+
+## Prerequisites: Install the CLI
+
+This skill drives the `realtimex-pp-cli` binary. Verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
+
+1. Install via npm:
+   ```bash
+   npm install -g @realtimex/pp-cli@2.0.4
+   ```
+2. Verify: `realtimex-pp-cli --version`
+
+If `--version` reports "command not found" after install, the npm global bin directory is not on `$PATH`. Do not proceed with skill commands until verification succeeds.
+
+## Command Reference
+
+**chat-feedback** — Manage chat feedback
+
+- `realtimex-pp-cli chat-feedback <slug> <chatId>` — Update workspace chat feedback.
+
+**chats** — Manage chats
+
+- `realtimex-pp-cli chats <slug>` — Get workspace chats.
+
+**config** — Manage config
+
+- `realtimex-pp-cli config get-workspace` — Get or create workspace config.
+- `realtimex-pp-cli config update-workspace` — Update workspace config.
+
+**delete-chats** — Manage delete chats
+
+- `realtimex-pp-cli delete-chats <slug>` — Delete selected workspace chats.
+
+**delete-edited-chats** — Manage delete edited chats
+
+- `realtimex-pp-cli delete-edited-chats <slug>` — Delete edited workspace chats from a starting id.
+
+**document** — Manage document
+
+- `realtimex-pp-cli document <slug> <docPath>` — Get document content for a workspace document.
+
+**linked-terminal-message** — Manage linked terminal message
+
+- `realtimex-pp-cli linked-terminal-message <slug>` — Persist a linked terminal message.
+
+**llm-provider** — Manage llm provider
+
+- `realtimex-pp-cli llm-provider <slug>` — Get workspace LLM provider metadata.
+
+**local-llm-tuning-suggestion** — Manage local llm tuning suggestion
+
+- `realtimex-pp-cli local-llm-tuning-suggestion <slug>` — Generate a local LLM tuning suggestion.
+
+**pfp** — Manage pfp
+
+- `realtimex-pp-cli pfp <slug>` — Get a workspace profile picture.
+
+**prompt-history** — Manage prompt history
+
+- `realtimex-pp-cli prompt-history delete-workspace` — Clear workspace prompt history.
+- `realtimex-pp-cli prompt-history delete-workspace-entry` — Delete a workspace prompt history entry.
+- `realtimex-pp-cli prompt-history get-workspace` — Get workspace prompt history.
+
+**realtimex-developer-search** — Manage realtimex developer search
+
+- `realtimex-pp-cli realtimex-developer-search <slug>` — Validate search provider configuration.
+
+**remove-and-unembed** — Manage remove and unembed
+
+- `realtimex-pp-cli remove-and-unembed <slug>` — Remove and unembed a document.
+
+**remove-pfp** — Manage remove pfp
+
+- `realtimex-pp-cli remove-pfp <slug>` — Remove a workspace profile picture.
+
+**reset-vector-db** — Manage reset vector db
+
+- `realtimex-pp-cli reset-vector-db <slug>` — Reset workspace vector database records.
+
+**stream-chat** — Manage stream chat
+
+- `realtimex-pp-cli stream-chat <slug>` — Stream a chat response for a workspace default thread.
+
+**suggested-messages** — Manage suggested messages
+
+- `realtimex-pp-cli suggested-messages get-workspace` — Get suggested messages for a workspace.
+- `realtimex-pp-cli suggested-messages save-workspace` — Save suggested messages for a workspace.
+
+**terminal-goal** — Manage terminal goal
+
+- `realtimex-pp-cli terminal-goal <slug>` — Create a terminal goal for a workspace.
+
+**terminal-goal-draft** — Manage terminal goal draft
+
+- `realtimex-pp-cli terminal-goal-draft <slug>` — Draft a terminal goal for a workspace.
+
+**terminal-session-details** — Manage terminal session details
+
+- `realtimex-pp-cli terminal-session-details <slug>` — Get workspace terminal session details.
+
+**terminal-ui-events** — Manage terminal ui events
+
+- `realtimex-pp-cli terminal-ui-events <slug>` — Persist terminal UI events.
+
+**thread** — Manage thread
+
+- `realtimex-pp-cli thread coordinate-task` — Coordinate a task into a workspace thread.
+- `realtimex-pp-cli thread create` — Create a workspace thread.
+- `realtimex-pp-cli thread delete` — Delete a workspace thread.
+- `realtimex-pp-cli thread fork` — Fork the workspace default thread.
+- `realtimex-pp-cli thread get` — Get a workspace thread.
+
+**thread-bulk-delete** — Manage thread bulk delete
+
+- `realtimex-pp-cli thread-bulk-delete <slug>` — Bulk delete workspace threads.
+
+**thread-events** — Manage thread events
+
+- `realtimex-pp-cli thread-events <slug>` — Open an SSE stream for workspace thread events.
+
+**threads** — Manage threads
+
+- `realtimex-pp-cli threads <slug>` — List workspace threads.
+
+**tts** — Manage tts
+
+- `realtimex-pp-cli tts <slug> <chatId>` — Generate text-to-speech audio for a workspace chat.
+
+**update** — Manage update
+
+- `realtimex-pp-cli update <slug>` — Update workspace settings by slug.
+
+**update-chat** — Manage update chat
+
+- `realtimex-pp-cli update-chat <slug>` — Update a workspace chat response.
+
+**update-embeddings** — Manage update embeddings
+
+- `realtimex-pp-cli update-embeddings <slug>` — Update workspace document embeddings.
+
+**update-pin** — Manage update pin
+
+- `realtimex-pp-cli update-pin <slug>` — Update workspace document pin status.
+
+**upload** — Manage upload
+
+- `realtimex-pp-cli upload <slug>` — Upload a document to workspace documents.
+
+**upload-and-embed** — Manage upload and embed
+
+- `realtimex-pp-cli upload-and-embed <slug>` — Upload and embed a document.
+
+**upload-link** — Manage upload link
+
+- `realtimex-pp-cli upload-link <slug>` — Upload a link to workspace documents.
+
+**upload-pfp** — Manage upload pfp
+
+- `realtimex-pp-cli upload-pfp <slug>` — Upload a workspace profile picture.
+
+**vision-availability** — Manage vision availability
+
+- `realtimex-pp-cli vision-availability <slug>` — Get workspace vision availability.
+
+**workspace** — Manage workspace
+
+- `realtimex-pp-cli workspace create` — Create a workspace using the app workspace creation behavior.
+- `realtimex-pp-cli workspace delete` — Delete a workspace.
+- `realtimex-pp-cli workspace get` — Get a workspace by slug.
+- `realtimex-pp-cli workspace hide-chat` — Hide a workspace chat.
+- `realtimex-pp-cli workspace search` — Search workspaces and threads.
+
+**workspaces** — Manage workspaces
+
+- `realtimex-pp-cli workspaces` — List workspaces using the app workspace list behavior.
+
+
+### Finding the right command
+
+When you know what you want to do but not which command does it, ask the CLI directly:
+
+```bash
+realtimex-pp-cli which "<capability in your own words>"
+```
+
+`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query.
+
+## Auth Setup
+Run `realtimex-pp-cli auth setup` to print the URL and steps for getting a key (add `--launch` to open the URL). Then set:
+
+```bash
+export REALTIMEX_APP_ID_AUTH="<your-key>"
+```
+
+Or persist it in `~/.config/realtimex-developer-pp-cli/config.toml`.
+
+Run `realtimex-pp-cli doctor` to verify setup.
+
+## Agent Mode
+
+Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color --yes`.
+
+- **Pipeable** — JSON on stdout, errors on stderr
+- **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
+
+  ```bash
+  realtimex-pp-cli thread get mock-value mock-value --agent --select id,name,status
+  ```
+- **Previewable** — `--dry-run` shows the request without sending
+- **Offline-friendly** — sync/search commands can use the local SQLite store when available
+- **Non-interactive** — never prompts, every input is a flag
+- **Explicit retries** — use `--idempotent` only when an already-existing create should count as success, and `--ignore-missing` only when a missing delete target should count as success
+
+### Response envelope
+
+Commands that read from the local store or the API wrap output in a provenance envelope:
+
+```json
+{
+  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
+  "results": <data>
+}
+```
+
+Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.
+
+## Agent Feedback
+
+When you (or the agent) notice something off about this CLI, record it:
+
+```
+realtimex-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
+realtimex-pp-cli feedback --stdin < notes.txt
+realtimex-pp-cli feedback list --json --limit 10
+```
+
+Entries are stored locally at `~/.local/share/realtimex-pp-cli/feedback.jsonl`. They are never POSTed unless `REALTIMEX_FEEDBACK_ENDPOINT` is set AND either `--send` is passed or `REALTIMEX_FEEDBACK_AUTO_SEND=true`. Default behavior is local-only.
+
+Write what *surprised* you, not a bug report. Short, specific, one line: that is the part that compounds.
+
+## Output Delivery
+
+Every command accepts `--deliver <sink>`. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
+
+| Sink | Effect |
+|------|--------|
+| `stdout` | Default; write to stdout only |
+| `file:<path>` | Atomically write output to `<path>` (tmp + rename) |
+| `webhook:<url>` | POST the output body to the URL (`application/json` or `application/x-ndjson` when `--compact`) |
+
+Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
+
+## Named Profiles
+
+A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
+
+```
+realtimex-pp-cli profile save briefing --json
+realtimex-pp-cli --profile briefing thread get mock-value mock-value
+realtimex-pp-cli profile list --json
+realtimex-pp-cli profile show briefing
+realtimex-pp-cli profile delete briefing --yes
+```
+
+Explicit flags always win over profile values; profile values win over defaults. `agent-context` lists all available profiles under `available_profiles` so introspecting agents discover them at runtime.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 2 | Usage error (wrong arguments) |
+| 3 | Resource not found |
+| 4 | Authentication required |
+| 5 | API error (upstream issue) |
+| 7 | Rate limited (wait and retry) |
+| 10 | Config error |
+
+## Argument Parsing
+
+Parse `$ARGUMENTS`:
+
+1. **Empty, `help`, or `--help`** → show `realtimex-pp-cli --help` output
+2. **Starts with `install`** → ends with `mcp` → MCP installation; otherwise → see Prerequisites above
+3. **Anything else** → Direct Use (execute as CLI command with `--agent`)
+
+## MCP Server Installation
+
+Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:
+
+```bash
+claude mcp add realtimex-pp-mcp -- realtimex-pp-mcp
+```
+
+Verify: `claude mcp list`
+
+## Direct Use
+
+1. Check if installed: `which realtimex-pp-cli`
+   If not found, offer to install (see Prerequisites at the top of this skill).
+2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
+3. Execute with the `--agent` flag:
+   ```bash
+   realtimex-pp-cli <command> [subcommand] [args] --agent
+   ```
+4. If ambiguous, drill into subcommand help: `realtimex-pp-cli <command> --help`.
+
+## Constraints
+
+Use only the `realtimex-pp-cli` commands documented by this skill. Never call the RealTimeX API directly with `curl`, `fetch`, raw HTTP clients, or custom scripts.
+
+If a requested task is impossible with the current CLI commands, do not work around it through direct API calls or undocumented behavior. Say the feature is not available and will be added soon.