Skip to main content
skill CX Codex

catalyst-datastreams — Claude Code skill: setup and install

This Claude Code skill explains Catalyst Data Streams, a WebSocket-based publish/subscribe service. It covers channel access, token issuance, and subscriber setup.

Apache-2.0 180 installs ★ 74 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add catalystbyzoho/agent-skills --skill catalyst-datastreams -a claude-code
Open on GitHub

What catalyst-datastreams does

The skill walks through creating Data Streams channels in the Catalyst console and setting their access control. User Roles channels use a userId; Custom Logic channels use a connectionName, with the token issued by the configured Advanced I/O function. That function runs the access check before calling getTokenPair.

Separate reference files cover Node.js, Python, and Java publishing and subscriber code. Subscribers should wait for the open event and call sendAck() after each message. Messages are retained for 48 hours. Resuming a dropped session with '-2' redelivers missed messages twice, while channel creation remains console-only.

Python needs Python 3.10+ and zcatalyst-sdk 1.5.0+. Java uses com.zoho.catalyst:java-sdk version 2.5.0+ from Maven. Administrative publish and channel-read methods run on the server, not in browser or mobile code.

What it helps with

  • publish events to a Catalyst Data Streams channel
  • choose the token identifier for a channel's access mode
  • connect a WebSocket subscriber and acknowledge messages
  • diagnose authentication and reconnect errors

Example prompts for the agent

  • Show how to publish to Catalyst Data Streams from a Node.js function.
  • Explain the “Mandatory parameter app_user_id is missing” error when subscribing.
  • Set up a Python Data Streams subscriber that connects and acknowledges messages.

How to install catalyst-datastreams

1Skills CLI (Vercel)

npx skills add catalystbyzoho/agent-skills --skill catalyst-datastreams -a claude-code

2Manually: put the files in place

~/.claude/skills/catalyst-datastreams/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/catalyst-datastreams/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about catalyst-datastreams

How do I install catalyst-datastreams in Claude Code?

Run npx skills add catalystbyzoho/agent-skills --skill catalyst-datastreams -a claude-code. The skill file is installed at ~/.claude/skills/catalyst-datastreams/SKILL.md.

What does catalyst-datastreams do?

It guides Catalyst Data Streams publishing and WebSocket subscriptions, including access-mode-specific tokens, message acknowledgements, and reconnect behavior.

What does catalyst-datastreams require?

Python examples need Python 3.10+ and zcatalyst-sdk 1.5.0+. Java uses com.zoho.catalyst:java-sdk version 2.5.0+ from Maven, and channels are created in the Catalyst console.

Source text

SKILL.md · Apache-2.0
---
name: catalyst-datastreams
description: "Catalyst Data Streams — real-time publish/subscribe channels over WebSocket. Publish from a function with publishData / publish_data, issue a token pair with getTokenPair / get_token_pair, subscribe with DataStreamsWebSocket / ZCDataStreamsWebSocket (Node.js, browser, Java, Python), sendAck, live/earliest/resume subscribe types, 48-hour retention, User Roles vs Custom Logic access control. Trigger on 'Data Streams', 'datastreams', 'real-time channel', 'live updates', 'pub/sub', 'WebSocket subscriber', 'token pair', 'wss-id', 'app_user_id is missing', 'Invalid access control source', 'Authentication failed 3000', '@zcatalyst/datastreams', or 'zcatalyst_sdk.datastreams'."
metadata:
  version: "2.0.0"
---

## How It Works

1. **Channels and access control are console-only.** Create the channel and choose its access control in Console → Cloud Scale → Data Streams; no SDK, REST, or MCP tool creates channels. Ask the user for the channel ID and its access control type, or list channels with `getAllChannels()` (`control_type` 0 = User Roles, 1 = Custom Logic). Load `references/datastreams-basics.md` for concepts, the token rules, subscribe types, acknowledgement, and the REST API.

2. **Pick the token identifier from the access control — it is not interchangeable.**
   - **User Roles** → `userId` = an app user's ID from Catalyst Authentication. A console admin's user ID is rejected; `connectionName` fails with "Mandatory parameter app_user_id is missing."
   - **Custom Logic** → `connectionName`, and the token must be generated **inside the Advanced I/O function selected as the channel's access control**. That function is the token endpoint: it runs your check, then calls `getTokenPair`. Catalyst never calls it on its own. From any other function or REST: "Invalid access control source!". User-ID tokens on these channels are issued but the WebSocket rejects them (`3000`).

3. **Server code (publish, token pair, channel reads) — load the runtime reference.**
   - Node.js / JavaScript → `references/datastreams-javascript-basics.md`. Initialize with the app: `new DataStreams(await zcAuth.init(req))`. Advanced I/O handlers get Node's raw `req`/`res`: no `req.body`, `res.status()`, or `res.json()`.
   - Python → `references/datastreams-python-basics.md`. Requires `zcatalyst-sdk` 1.5.0+ (Python 3.10+). `app = zcatalyst_sdk.initialize(req=request)`, then `app.datastreams()` (plural). Pass `get_token_pair` a **string** channel ID and a keyword `user_id=` / `connection_name=`; the result's keys are hyphenated (`token["wss-id"]`). The subscriber does nothing until `connect()`.
   - Java → `references/datastreams-java-basics.md`. Dependency is `com.zoho.catalyst:java-sdk` (2.5.0+) from `https://maven.zohodl.com`; no `datastreams` artifact exists.
   - `publishData`, `getAllChannels`, `getChannelDetails` and `getLiveCount` are **admin** methods: server only, never in browser or mobile code. `getTokenPair` also exists in the browser SDK, but a Custom Logic token must come from the configured function.

4. **Subscriber code — read the token correctly and always acknowledge.** The token pair's keys are hyphenated: pass `token['wss-id']` as `zuid`, plus `token.url` and `token.key`. Subscribe only after the `open` event. Call `sendAck()` after every message, or the next message is never delivered. Messages carry `data` (always a string) and `streamingId` (plus `url`/`method` on API-operation messages). To reconnect, release the old session (old token → `unsubscribe()`), take a fresh token, `subscribe('0')`, and reload state from your own store; resuming a dropped session with `'-2'` redelivers missed messages twice and replays the 48-hour retention. Unsubscribe before every deliberate close; the `error` event with code `1000` that follows your own `unsubscribe()` is expected. In Node, `getLiveCount()` returns `{ status, data: { connections } }`. Java: `subscribe()` throws the checked `ZCDataStreamException`, and outside a Catalyst function create the client with `new ZCDataStreamsWebSocket(config)`, not `ZCDatastream.getInstance()`.

5. **Verify end to end before reporting success.** Open a subscriber, check `getLiveCount()` shows it, publish a test message, and confirm the subscriber received it. For anything the references do not cover, fetch the page under <https://docs.catalyst.zoho.com/en/cloud-scale/help/data-streams/> as Markdown (`<page-url>/index.md`), and prefer the references where they disagree.

## Security Checklist

- `publishData` and the channel-read methods are admin operations: run them only in a Catalyst function, never in a browser or mobile app.
- Protect the token endpoint. Anyone who can call it can subscribe to the channel, so authenticate the caller before issuing a token.
- On Custom Logic channels, the configured function is the only gatekeeper: put the real validation there before calling `getTokenPair`.
- Do not log or return the token `key` anywhere except to the client that asked for it.

## Triggers

Use this skill for: "Data Streams", "Catalyst Data Streams", "datastreams", "real-time channel", "live updates", "push updates to the browser", "pub/sub", "publish data", `publishData`, `getTokenPair`, "token pair", "wss-id", `DataStreamsWebSocket`, `ZCDataStreamsWebSocket`, `ZCDatastream`, "WebSocket subscriber", `sendAck`, "subscribe type", "resume from last message", "live count", `getLiveCount`, "channel access control", "User Roles channel", "Custom Logic channel", "app_user_id is missing", "Invalid access control source", "Authentication failed 3000", "reconnect", "duplicate messages after reconnect", "DUPLICATE_VALUE", `@zcatalyst/datastreams`, `zcatalyst_sdk`, `get_token_pair`, `publish_data`, `send_ack`, or "Data Streams Python".

## References

| Reference | Load when the query is about… |
|-----------|-------------------------------|
| `references/datastreams-basics.md` | Concepts, channels, access control (User Roles vs Custom Logic), which token identifier to use, token pair shape, subscribe types, acknowledgement, retention, message fields, REST API endpoints and scopes |
| `references/datastreams-javascript-basics.md` | Node.js functions (init, publish, token endpoint, Custom Logic function, channel reads), Node and browser subscribers, package versions |
| `references/datastreams-python-basics.md` | Python functions and subscribers: `zcatalyst-sdk` 1.5.0+, `app.datastreams()`, `get_token_pair` argument rules, `DataStreamsWebSocket` with `connect()` and `set_on_*` callbacks, deploying Python functions |
| `references/datastreams-java-basics.md` | Java functions and subscribers: Maven setup, `ZCDatastream`, `ZCDataStreamsWebSocket`, checked exceptions, running outside Catalyst |

© catalystbyzoho · Apache-2.0 · catalystbyzoho/agent-skills

Similar skills

All skills for Backend and APIs →

From the same set19

The whole set →
catalyst-functions catalyst-functions guides development and deployment for all 7 Zoho Catalyst serverless function types. Helps configure API Gateway routing, resolve CORS bugs, and handle file uploads. CX Codex +1 1,200installs catalyst-appsail Skill for Claude Code, Codex, Cursor and other platforms: deploys persistent servers on Catalyst AppSail — managed Node.js, Java, Python runtimes and custom Docker containers. CX Codex +1 1,200installs catalyst-basics catalyst-basics — a skill that walks the agent through Zoho Catalyst project setup: directory layout, environments, CLI commands and every project ID. Handy when you need a Table ID or a look at .catalystrc. CX Codex +1 1,200installs catalyst-by-zoho catalyst-by-zoho is a Claude Code skill for building and deploying cloud applications on Zoho Catalyst with CLI, SDKs, and Zoho MCP tools. CX Codex +1 1,200installs catalyst-smartbrowz Teaches coding assistants to automate browsers and generate PDFs via Catalyst SmartBrowz. It guides Puppeteer, Playwright, and Selenium workflows in the Catalyst cloud. CX Codex +1 1,100installs catalyst-signals A skill for working with Catalyst Signals: set up publishers, rules, webhooks and dispatch policies from the console. CX Codex +1 1,100installs catalyst-job-scheduling catalyst-job-scheduling orchestrates job pools, background executions, and cron triggers in Zoho Catalyst. It helps write job handlers and prevents SDK payload errors. CX Codex +1 727installs catalyst-quickml The catalyst-quickml skill guides an agent through QuickML tasks, from training prediction models to working with RAG and pricing questions. QuickML must first be activated for the project. CX Codex +1 476installs

Project sponsors

Companies that keep this analytics open