@restless-stream/core 0.1.1 → 0.1.2

package/README.md

@@ -11,7 +11,7 @@ Use this package when you need framework-neutral TypeScript support. Use `@restl
 - A Restless Stream account and API key.
 - A runtime with `fetch` for REST and SSE support.
 - A runtime with `WebSocket` for WebSocket helpers, or an explicit `WebSocket` implementation passed in options.
-- Node.js `>=20.19.0` for local development and package tests.
+- Node.js `>=24` for local development and package tests.
 
 Do not expose long-lived API keys in public browser applications. For browser clients, prefer backend-created stream or direct-session URLs.
 
@@ -346,6 +346,114 @@ type ErrorEvent = {
 | `RestlessClient`, `RestlessStreamsClient`, `RestlessDirectClient`, `RestlessUrlBuilder` | Client interfaces. |
 | Stream, direct, snippet, and runtime types | Request, response, event, URL, and snippet types exported from `types.ts`. |
 
+## Appendix: Creating an API Key
+
+API keys authenticate requests to the Restless Stream management API and runtime streams. Keys start with `rs_` followed by a hex string:
+
+```
+rs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+### Create a key in the dashboard
+
+1. Sign in at [restlessapi.stream](https://restlessapi.stream) and go to **API Keys** in the dashboard.
+
+![API Keys dashboard showing existing keys](docs/api-keys-dashboard.png)
+
+2. Click **Create API Key**, enter a name and optional description, and set an optional expiry date.
+
+![Create API Key modal form](docs/api-keys-create-modal.png)
+
+3. Copy the key immediately — it is shown only once after creation.
+
+```bash
+export RESTLESS_API_KEY="rs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+```
+
+### Pass the key to the client
+
+```ts
+import { createRestlessClient } from '@restless-stream/core';
+
+const client = createRestlessClient({
+  apiKey: process.env.RESTLESS_API_KEY,
+});
+```
+
+## Sample Responses
+
+### `streams.list()`
+
+```ts
+const page = await client.streams.list({ limit: 5, offset: 0 });
+console.log(page);
+```
+
+**Response:**
+
+```json
+{
+  "streams": [],
+  "paginationInfo": {
+    "hasNextPage": false
+  }
+}
+```
+
+### `streams.validateApiKey()`
+
+```ts
+const result = await client.streams.validateApiKey();
+```
+
+**Response:**
+
+```json
+{
+  "id": "rs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "affected": true
+}
+```
+
+### `streams.subscribeSse()` — direct mode, live event
+
+```ts
+const sseUrl =
+  'https://stream.restlessapi.stream/?url=' +
+  encodeURIComponent('https://httpbin.org/get') +
+  '&pollingInterval=15';
+
+for await (const event of client.streams.subscribeSse({ sseUrl, reconnect: false })) {
+  console.log(event);
+  break; // receive one event then stop
+}
+```
+
+**Event received:**
+
+```json
+{
+  "type": "update",
+  "meta": {
+    "timestamp": "2026-06-07T00:49:36.562+00:00",
+    "attempt_id": "a59d80d4-7d36-4019-b2c6-40cc8b8742ce",
+    "status": 200,
+    "latency_ms": 43
+  },
+  "data": {
+    "args": {},
+    "headers": {
+      "Accept": "*/*",
+      "Host": "httpbin.org",
+      "User-Agent": "Mozilla/5.0 (compatible; OurInternalService/1.0)",
+      "X-Amzn-Trace-Id": "Root=1-6a24c020-316d1d396470c0900ce68495"
+    },
+    "origin": "140.82.14.127",
+    "url": "https://httpbin.org/get"
+  }
+}
+```
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@restless-stream/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "TypeScript SDK for Restless Stream.",
   "license": "MIT",
   "repository": {