@restless-stream/core 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,465 @@
+# @restless-stream/core
+
+Official TypeScript SDK for Restless Stream core APIs: <https://restlessapi.stream>
+
+Restless Stream turns REST APIs into live Server-Sent Events and WebSocket streams. This package provides the browser-compatible client, shared types, runtime URL builders, SSE parsing, and basic WebSocket iteration used by the other Restless Stream TypeScript packages.
+
+Use this package when you need framework-neutral TypeScript support. Use `@restless-stream/node` for Node.js WebSocket subscriptions with handshake headers, and `@restless-stream/react` for React provider and hook APIs.
+
+## Requirements
+
+- 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 `>=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.
+
+## Installation
+
+```bash
+npm install @restless-stream/core
+```
+
+```bash
+pnpm add @restless-stream/core
+```
+
+```bash
+yarn add @restless-stream/core
+```
+
+## Getting Started
+
+Create a stream with the REST API, then subscribe to the returned SSE URL.
+
+```ts
+import { createRestlessClient } from '@restless-stream/core';
+
+const client = createRestlessClient({
+  apiKey: process.env.RESTLESS_API_KEY,
+});
+
+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.subscribeSse({ sseUrl: stream.sseUrl })) {
+  if (event.type === 'update') {
+    console.log('data', event.data);
+  }
+
+  if (event.type === 'error') {
+    console.error(event.error.message);
+  }
+}
+```
+
+The top-level client methods and the `client.streams` resource expose the same management operations. For example, `client.createStream(input)` and `client.streams.create(input)` both create a stream.
+
+## Client Configuration
+
+```ts
+const client = createRestlessClient({
+  apiKey: process.env.RESTLESS_API_KEY,
+  apiBaseUrl: 'https://api.restlessapi.stream',
+  streamBaseUrl: 'https://stream.restlessapi.stream',
+  headers: { 'X-App': 'orders-service' },
+  fetch: globalThis.fetch,
+});
+```
+
+| Option | Description |
+| --- | --- |
+| `apiKey` | Sends `x-api-key` on REST requests and `Authorization: Bearer <key>` on SSE runtime requests. |
+| `apiBaseUrl` | REST API base URL. Defaults to `https://api.restlessapi.stream`. |
+| `streamBaseUrl` | Runtime stream base URL. Defaults to `https://stream.restlessapi.stream`. |
+| `headers` | Default headers for REST API requests. |
+| `fetch` | Custom `fetch` implementation. Required only when the runtime does not provide global `fetch`. |
+
+`createStream` and `updateStream` automatically add `apiKey` to the JSON body when the client has an API key and the input does not already provide one.
+
+## Stream Management
+
+```ts
+const page = await client.streams.list({ limit: 20, offset: 0 });
+const stream = await client.streams.get('stream_123');
+
+await client.streams.update(stream.id, {
+  name: 'Orders v2',
+  pollingInterval: 60,
+});
+
+await client.streams.stop(stream.id);
+await client.streams.start(stream.id);
+
+const usage = await client.streams.creditUsageStats(stream.id);
+const snippets = await client.streams.connectionSnippets({
+  streamId: stream.id,
+  language: 'javascript',
+});
+```
+
+| Method | Description |
+| --- | --- |
+| `streams.list(input?)` / `listStreams(input?)` | List streams with optional `limit` and `offset`. |
+| `streams.get(id)` / `getStream(id)` | Get one stream by ID. |
+| `streams.create(input)` / `createStream(input)` | Create a persisted stream. |
+| `streams.update(id, input)` / `updateStream(id, input)` | Patch stream configuration. |
+| `streams.start(id)` / `startStream(id)` | Mark a stream active. |
+| `streams.stop(id)` / `stopStream(id)` | Mark a stream inactive. |
+| `streams.delete(id)` / `deleteStream(id)` | Delete a stream. |
+| `streams.validateApiKey(apiKey?)` / `validateApiKey(apiKey?)` | Validate an API key. Uses the client API key when omitted. |
+| `streams.creditUsageStats(id)` / `creditUsageStats(id)` | Fetch credit usage totals and daily usage. |
+| `streams.connectionSnippets(input)` / `connectionSnippets(input)` | Generate runtime URLs and connection snippets. |
+
+## Direct Streams
+
+Direct streams let you subscribe to a REST endpoint without creating a persisted stream first.
+
+```ts
+for await (const event of client.direct.subscribeSse({
+  url: 'https://api.example.com/orders',
+  method: 'GET',
+  pollingInterval: 30,
+})) {
+  console.log(event);
+}
+```
+
+Create a reusable direct session when you want a stable runtime URL.
+
+```ts
+const session = await client.direct.createSession({
+  dedupeKey: 'orders-feed-v1',
+  method: 'GET',
+  url: 'https://api.example.com/orders',
+  pollingInterval: 30,
+});
+
+for await (const event of client.streams.subscribeSse({ sseUrl: session.sseUrl })) {
+  console.log(event);
+}
+```
+
+Generate setup commands and snippets without opening a stream connection.
+
+```ts
+const setup = await client.direct.setup({
+  method: 'POST',
+  url: 'https://api.example.com/search',
+  body: { query: 'restless' },
+  language: 'javascript',
+});
+
+console.log(setup.commands.header.curl);
+console.log(setup.runtime.directSseUrl);
+```
+
+Direct stream input supports:
+
+| Field | Description |
+| --- | --- |
+| `url` | Target REST URL. Required. |
+| `method` | HTTP method. Defaults to `GET` when omitted from runtime URLs. |
+| `headers` | JSON object of upstream request headers. |
+| `body` | JSON object request body. |
+| `jqFilter` | Optional jq filter applied by Restless Stream. |
+| `payloadMode` | `FULL_DATA` or `JSON_PATCH`. |
+| `pollingInterval` | Polling interval in seconds. |
+| `pollingStrategies` | Time-windowed polling strategies. |
+| `apiKey` | Optional API key for query-parameter auth in generated direct URLs. |
+
+## SSE Streaming
+
+`streams.subscribeSse` yields parsed Restless Stream runtime events and skips non-JSON SSE messages.
+
+```ts
+const controller = new AbortController();
+
+for await (const event of client.streams.subscribeSse({
+  sseUrl: stream.sseUrl,
+  cursor: '1700000000000',
+  reconnect: true,
+  signal: controller.signal,
+})) {
+  console.log(event.type, event.meta?.timestamp);
+}
+```
+
+Use `client.sse` or `streamSse` when you need raw SSE message metadata such as `id`, `event`, `retry`, and `data`.
+
+```ts
+for await (const message of client.sse(stream.sseUrl, { reconnect: false })) {
+  console.log(message.id, message.parsed ?? message.data);
+}
+```
+
+SSE options include:
+
+| Option | Description |
+| --- | --- |
+| `sseUrl` | Runtime SSE URL for `subscribeSse`. |
+| `headers` | Additional runtime request headers. |
+| `signal` | `AbortSignal` used to stop iteration. |
+| `reconnect` | Set `false` to stop after the first connection ends or fails. Defaults to reconnecting. |
+| `reconnectDelayMs` | Initial reconnect delay. Defaults to `1000`. |
+| `maxReconnectDelayMs` | Maximum reconnect delay. Defaults to `30000`. |
+| `cursor` | Resume from a cursor or event ID. |
+| `since` | Resume from a timestamp or cursor when no event cursor is known yet. |
+| `allowApiKeyInUrl` | Adds the client API key as `apiKey` in the URL. Disabled by default because URLs can leak. |
+
+## WebSocket Streaming
+
+Core WebSocket helpers use the runtime `WebSocket` API and yield parsed JSON messages when possible, otherwise raw strings.
+
+```ts
+for await (const event of client.direct.subscribeWebSocket(
+  {
+    url: 'https://api.example.com/orders',
+    method: 'GET',
+  },
+  {
+    cursor: '42',
+  },
+)) {
+  console.log(event);
+}
+```
+
+```ts
+for await (const message of client.websocket('wss://stream.restlessapi.stream/ws?streamId=stream_123')) {
+  console.log(message);
+}
+```
+
+Browser WebSocket constructors do not support custom handshake headers. Use `@restless-stream/node` when you need `Authorization` headers for WebSocket subscriptions in Node.js.
+
+## Runtime URL Builders
+
+```ts
+import {
+  buildDirectSseUrl,
+  buildDirectWebSocketUrl,
+  buildSseUrl,
+  buildWebSocketUrl,
+  toWebSocketStreamUrl,
+} from '@restless-stream/core';
+
+const sseUrl = buildSseUrl(undefined, { streamId: 'stream_123' }, { since: '2026-01-01T00:00:00Z' });
+const wsUrl = buildWebSocketUrl(undefined, { sessionId: 'session_123' });
+
+const directSseUrl = buildDirectSseUrl(undefined, {
+  url: 'https://api.example.com/orders',
+  method: 'POST',
+  body: { page: 1 },
+});
+
+const directWsUrl = buildDirectWebSocketUrl(undefined, {
+  url: 'https://api.example.com/orders',
+});
+
+console.log(toWebSocketStreamUrl(sseUrl));
+console.log(wsUrl, directSseUrl, directWsUrl);
+```
+
+The client also exposes URL builders bound to its `streamBaseUrl`.
+
+```ts
+const sse = client.urls.sse({ streamId: 'stream_123' });
+const websocket = client.urls.websocket({ streamId: 'stream_123' });
+const directSse = client.urls.directSse({ url: 'https://api.example.com/orders' });
+const directWebSocket = client.urls.directWebSocket({ url: 'https://api.example.com/orders' });
+```
+
+## Error Handling
+
+REST API failures throw `RestlessApiError`.
+
+```ts
+import { RestlessApiError } from '@restless-stream/core';
+
+try {
+  await client.streams.get('missing');
+} catch (error) {
+  if (error instanceof RestlessApiError) {
+    console.error(error.status, error.statusText, error.body);
+  }
+}
+```
+
+## Runtime Events
+
+Update events contain data from the upstream REST endpoint.
+
+```ts
+type UpdateEvent<TData> = {
+  type: 'update';
+  meta: {
+    timestamp: string;
+    attempt_id: string;
+    status?: number;
+    latency_ms: number;
+    payload_mode_fallback?: 'FULL_DATA' | 'JSON_PATCH';
+  };
+  data: TData;
+  signature?: string;
+};
+```
+
+Error events contain a code and message.
+
+```ts
+type ErrorEvent = {
+  type: 'error';
+  meta?: Partial<UpdateEvent<unknown>['meta']>;
+  error: {
+    code: string;
+    message: string;
+  };
+};
+```
+
+## Public Exports
+
+| Export | Purpose |
+| --- | --- |
+| `createRestlessClient` | Creates the core REST and runtime client. |
+| `DEFAULT_API_BASE_URL` | Default REST API base URL. |
+| `DEFAULT_STREAM_BASE_URL` | Default runtime stream base URL. |
+| `RestlessApiError` | Error type thrown for non-2xx REST API responses. |
+| `streamSse` | Low-level SSE async iterator. |
+| `parseSseStream` | Parses a `ReadableStream<Uint8Array>` into SSE messages. |
+| `streamWebSocket` | Low-level WebSocket async iterator. |
+| `buildSseUrl`, `buildWebSocketUrl` | Build managed stream runtime URLs. |
+| `buildDirectSseUrl`, `buildDirectWebSocketUrl` | Build direct stream runtime URLs. |
+| `appendDirectQueryParams` | Append direct stream query params to `URLSearchParams`. |
+| `normalizeBaseUrl` | Trim a trailing slash from a base URL. |
+| `toWebSocketStreamUrl` | Convert an SSE URL to a WebSocket URL. |
+| `withRuntimeCursor` | Add `cursor` or `since` resume params to a runtime URL. |
+| `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
+cd packages/typescript
+pnpm install
+pnpm --filter @restless-stream/core typecheck
+pnpm --filter @restless-stream/core test
+pnpm --filter @restless-stream/core build
+```

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@restless-stream/core",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "TypeScript SDK for Restless Stream.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/restless-stream/sdk.git",
+    "directory": "packages/typescript/core"
+  },
+  "homepage": "https://github.com/restless-stream/sdk/tree/main/packages/typescript/core#readme",
+  "bugs": {
+    "url": "https://github.com/restless-stream/sdk/issues"
+  },
+  "keywords": [
+    "restless-stream",
+    "sdk",
+    "sse",
+    "websocket",
+    "streaming",
+    "typescript"
+  ],
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -16,6 +34,9 @@
   "files": [
     "dist"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "sideEffects": false,
   "devDependencies": {
     "tsup": "^8.5.1",