@restless-stream/node 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,312 @@
+# @restless-stream/node
+
+Official Node.js helpers for Restless Stream: <https://restlessapi.stream>
+
+This package builds on `@restless-stream/core` and re-exports the core SDK. It adds a Node WebSocket transport based on `ws`, support for WebSocket handshake headers, default Bearer-token auth, reconnect and resume behavior, and Node-friendly SSE helpers.
+
+Use this package for server-side Node.js applications. Use `@restless-stream/core` for browser-compatible primitives and `@restless-stream/react` for React hooks.
+
+## Requirements
+
+- Node.js `>=20.19.0`.
+- A Restless Stream account and API key.
+
+## Installation
+
+```bash
+npm install @restless-stream/node
+```
+
+```bash
+pnpm add @restless-stream/node
+```
+
+```bash
+yarn add @restless-stream/node
+```
+
+## Getting Started
+
+Subscribe directly to a REST endpoint over WebSocket. The client API key is sent as `Authorization: Bearer <key>` during the WebSocket handshake.
+
+```ts
+import { createNodeRestlessClient } from '@restless-stream/node';
+
+const client = createNodeRestlessClient({
+  apiKey: process.env.RESTLESS_API_KEY,
+});
+
+for await (const event of client.direct.subscribeWebSocket({
+  url: 'https://api.example.com/orders',
+  method: 'GET',
+  pollingInterval: 30,
+})) {
+  console.log(event);
+}
+```
+
+You can also create or fetch a managed stream with the inherited core REST methods, then subscribe to `stream.wsUrl` or `stream.sseUrl`.
+
+```ts
+const stream = await client.streams.create({
+  name: 'Orders',
+  description: 'Live order feed',
+  status: 'ACTIVE',
+  method: 'GET',
+  url: 'https://api.example.com/orders',
+  payloadMode: 'FULL_DATA',
+  pollingInterval: 30,
+});
+
+for await (const event of client.streams.subscribeWs({ wsUrl: stream.wsUrl })) {
+  console.log(event);
+}
+```
+
+## Client API
+
+`createNodeRestlessClient(options)` accepts all `createRestlessClient` options from `@restless-stream/core`.
+
+```ts
+const client = createNodeRestlessClient({
+  apiKey: process.env.RESTLESS_API_KEY,
+  apiBaseUrl: 'https://api.restlessapi.stream',
+  streamBaseUrl: 'https://stream.restlessapi.stream',
+  headers: { 'X-App': 'worker' },
+});
+```
+
+The returned client includes all core REST and URL APIs, plus Node-specific streaming methods:
+
+| Method | Description |
+| --- | --- |
+| `client.subscribeWebSocket(options)` | Top-level Node WebSocket subscription helper. |
+| `client.subscribeWs(options)` | Alias for `subscribeWebSocket`. |
+| `client.streams.subscribeWebSocket(options)` | Managed stream WebSocket subscription helper. |
+| `client.streams.subscribeWs(options)` | Alias for `streams.subscribeWebSocket`. |
+| `client.direct.subscribeWebSocket(input, options?)` | Direct stream WebSocket subscription helper using the Node transport. |
+| `client.subscribeSse(options)` | Top-level Node SSE helper. |
+| `client.streams.subscribeSse(options)` | Managed stream SSE helper. |
+
+All core stream management methods are also available, including `streams.list`, `streams.get`, `streams.create`, `streams.update`, `streams.start`, `streams.stop`, `streams.delete`, `streams.validateApiKey`, `streams.creditUsageStats`, and `streams.connectionSnippets`.
+
+## WebSocket Subscriptions
+
+Use the standalone helper when you already have a WebSocket URL.
+
+```ts
+import { subscribeWebSocket } from '@restless-stream/node';
+
+for await (const event of subscribeWebSocket({
+  wsUrl: 'wss://stream.restlessapi.stream/ws?streamId=stream_123',
+  apiKey: process.env.RESTLESS_API_KEY,
+})) {
+  console.log(event);
+}
+```
+
+WebSocket options:
+
+| Option | Description |
+| --- | --- |
+| `wsUrl` | WebSocket URL returned by Restless Stream. |
+| `websocketUrl` | Alias for `wsUrl`. |
+| `url` | Alias for `wsUrl`; useful when adapting generic stream records. |
+| `apiKey` | Sends `Authorization: Bearer <apiKey>` unless an Authorization header is already provided. |
+| `protocols` | Optional WebSocket subprotocol or list of subprotocols. |
+| `headers` | Additional WebSocket handshake headers. |
+| `signal` | `AbortSignal` used to stop iteration and close the socket. |
+| `cursor` | Initial cursor used for resume. Updated automatically from received events. |
+| `since` | Initial timestamp or cursor used only until a cursor is observed. |
+| `reconnect` | `false`, `true`, or reconnect policy object. Defaults to enabled. |
+| `clientOptions` | Extra options passed to the `ws` client. |
+| `parse` | Set `false` to yield raw text frames instead of parsed events. |
+| `parser` | Custom parser for text or JSON messages. |
+
+`headers` override `clientOptions.headers` with the same key. If `apiKey` is set, an `Authorization` header is added only when no Authorization header already exists.
+
+## Reconnect and Resume
+
+Reconnects are enabled by default for abnormal closes and connection errors. Normal close codes `1000` and `1001` end the iterator.
+
+```ts
+for await (const event of subscribeWebSocket({
+  wsUrl: 'wss://stream.restlessapi.stream/ws?streamId=stream_123',
+  apiKey: process.env.RESTLESS_API_KEY,
+  since: '2026-01-01T00:00:00Z',
+  reconnect: {
+    maxRetries: 5,
+    initialDelayMs: 250,
+    maxDelayMs: 5000,
+    factor: 2,
+  },
+})) {
+  console.log(event);
+}
+```
+
+Reconnect policy fields:
+
+| Field | Default | Description |
+| --- | --- | --- |
+| `enabled` | `true` | Enables reconnects after retryable closes and errors. |
+| `maxRetries` | `Infinity` | Maximum reconnect attempts. |
+| `initialDelayMs` | `250` | First reconnect delay. |
+| `maxDelayMs` | `5000` | Maximum reconnect delay. |
+| `factor` | `2` | Exponential backoff multiplier. |
+
+Resume cursor detection checks received events in this order:
+
+| Source | Description |
+| --- | --- |
+| `cursor` | Preferred cursor field. |
+| `id` | Generic event ID. |
+| `eventId` | Browser-style event ID field. |
+| `lastEventId` | Last-event ID field. |
+| `meta.timestamp` | Restless runtime event timestamp converted to Unix milliseconds. |
+
+The subscription appends `cursor` on reconnect once a cursor is known. Before that, it appends `since` when provided.
+
+## Message Parsing
+
+By default, WebSocket frames are parsed as JSON.
+
+```ts
+for await (const event of subscribeWebSocket<{ type: string }>({
+  wsUrl: 'wss://stream.restlessapi.stream/ws?streamId=stream_123',
+})) {
+  console.log(event.type);
+}
+```
+
+Yield raw text frames with `parse: false`.
+
+```ts
+for await (const text of subscribeWebSocket<string>({
+  wsUrl: 'wss://stream.restlessapi.stream/ws?streamId=stream_123',
+  parse: false,
+})) {
+  console.log(text);
+}
+```
+
+Provide a custom parser when you want your own validation or transformation.
+
+```ts
+for await (const event of subscribeWebSocket({
+  wsUrl: 'wss://stream.restlessapi.stream/ws?streamId=stream_123',
+  parser(message) {
+    const value = typeof message === 'string' ? JSON.parse(message) : message;
+    return { receivedAt: new Date(), value };
+  },
+})) {
+  console.log(event.receivedAt, event.value);
+}
+```
+
+Application-level `ping` and `pong` messages are hidden from the iterator. A received `ping` is answered with `pong` when the socket is open.
+
+## SSE Subscriptions
+
+Node SSE helpers delegate to the core SSE implementation and yield raw SSE message objects with `data`, optional `parsed`, `id`, `event`, and `retry` fields.
+
+```ts
+import { subscribeSse } from '@restless-stream/node';
+
+for await (const message of subscribeSse({
+  sseUrl: 'https://stream.restlessapi.stream?streamId=stream_123',
+  clientOptions: { apiKey: process.env.RESTLESS_API_KEY },
+  cursor: '1700000000000',
+  reconnect: false,
+})) {
+  console.log(message.id, message.parsed ?? message.data);
+}
+```
+
+You can also pass an existing client explicitly.
+
+```ts
+for await (const message of subscribeSse(client, {
+  sseUrl: stream.sseUrl,
+  since: '2026-01-01T00:00:00Z',
+})) {
+  console.log(message);
+}
+```
+
+SSE options include `sseUrl`, `cursor`, `since`, `signal`, `reconnect`, `reconnectDelayMs`, and `maxReconnectDelayMs`.
+
+Use `buildNodeSseUrl` to append resume parameters without subscribing.
+
+```ts
+import { buildNodeSseUrl } from '@restless-stream/node';
+
+const url = buildNodeSseUrl({
+  sseUrl: stream.sseUrl,
+  cursor: '42',
+});
+```
+
+## Direct Subscriptions
+
+Direct WebSocket subscriptions build the runtime URL through the core client and then use the Node transport.
+
+```ts
+for await (const event of client.direct.subscribeWebSocket(
+  {
+    url: 'https://api.example.com/search',
+    method: 'POST',
+    body: { query: 'restless' },
+    payloadMode: 'FULL_DATA',
+  },
+  {
+    cursor: '42',
+    reconnect: { maxRetries: 3 },
+  },
+)) {
+  console.log(event);
+}
+```
+
+For reusable URLs, create a direct session first with the inherited core API.
+
+```ts
+const session = await client.direct.createSession({
+  dedupeKey: 'orders-feed-v1',
+  method: 'GET',
+  url: 'https://api.example.com/orders',
+});
+
+for await (const event of client.streams.subscribeWs({ wsUrl: session.wsUrl })) {
+  console.log(event);
+}
+```
+
+## Public Exports
+
+| Export | Purpose |
+| --- | --- |
+| `createNodeRestlessClient` | Creates a core client with Node-specific streaming helpers. |
+| `subscribeWebSocket` | Standalone Node WebSocket async iterable. |
+| `subscribeSse` | Standalone or client-bound Node SSE helper. |
+| `buildNodeSseUrl` | Adds `cursor` and `since` resume params to an SSE URL. |
+| `CoreRestlessClientOptions` | Type alias for core client options. |
+| `NodeRestlessClientOptions` | Node client options. |
+| `NodeRestlessClient` | Node client interface. |
+| `NodeStreamsClient` | Node stream resource interface. |
+| `NodeDirectClient` | Node direct resource interface. |
+| `NodeWebSocketSubscriptionOptions` | WebSocket subscription options. |
+| `NodeWebSocketReconnectOptions` | WebSocket reconnect policy. |
+| `NodeSseSubscriptionOptions` | SSE subscription options. |
+| `NodeSseHelperOptions` | Standalone SSE helper options. |
+| Core exports | Everything exported by `@restless-stream/core` is re-exported. |
+
+## Development
+
+```bash
+cd packages/typescript
+pnpm install
+pnpm --filter @restless-stream/node typecheck
+pnpm --filter @restless-stream/node test
+pnpm --filter @restless-stream/node build
+```

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@restless-stream/node",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Node.js SDK helpers for Restless Stream.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/restless-stream/sdk.git",
+    "directory": "packages/typescript/node"
+  },
+  "homepage": "https://github.com/restless-stream/sdk/tree/main/packages/typescript/node#readme",
+  "bugs": {
+    "url": "https://github.com/restless-stream/sdk/issues"
+  },
+  "keywords": [
+    "restless-stream",
+    "sdk",
+    "sse",
+    "websocket",
+    "streaming",
+    "node"
+  ],
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -9,6 +27,9 @@
   "files": [
     "dist"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -18,7 +39,7 @@
   },
   "dependencies": {
     "ws": "^8.18.0",
-    "@restless-stream/core": "0.1.0"
+    "@restless-stream/core": "0.1.1"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"