@restless-stream/react 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,263 @@
+# @restless-stream/react
+
+Lightweight React bindings for Restless Stream: <https://restlessapi.stream>
+
+This package provides a `RestlessProvider`, access to the core Restless Stream client through context, and hooks for consuming SSE stream URLs in React components.
+
+Use this package when a React app already has a Restless Stream SSE URL, managed stream object, or direct-session response. Use `@restless-stream/core` or `@restless-stream/node` on a trusted backend to create streams or sessions when you do not want to expose API keys to the browser.
+
+## Requirements
+
+- React `>=18.2 <20`.
+- A Restless Stream account and API key when creating a client in the provider.
+- An SSE URL from a managed stream or direct session.
+
+Do not put long-lived API keys in public browser bundles. For browser applications, prefer generating stream URLs or direct sessions on your backend and passing only the runtime URL to React.
+
+## Installation
+
+```bash
+npm install @restless-stream/react @restless-stream/core
+```
+
+```bash
+pnpm add @restless-stream/react @restless-stream/core
+```
+
+```bash
+yarn add @restless-stream/react @restless-stream/core
+```
+
+`@restless-stream/core` is installed as a dependency by package managers, but adding it explicitly can make shared client types easier to import in your application.
+
+## Getting Started
+
+Wrap your app in `RestlessProvider`, then subscribe with `useStreamSubscription`.
+
+```tsx
+import { RestlessProvider, useStreamSubscription } from '@restless-stream/react';
+
+function StreamEvents({ sseUrl }: { sseUrl: string }) {
+  const { error, events, status } = useStreamSubscription({
+    enabled: Boolean(sseUrl),
+    maxEvents: 100,
+    sseUrl,
+  });
+
+  if (error) {
+    return <p>{error.message}</p>;
+  }
+
+  return <pre>{JSON.stringify({ status, events }, null, 2)}</pre>;
+}
+
+export function App({ apiKey, sseUrl }: { apiKey: string; sseUrl: string }) {
+  return (
+    <RestlessProvider apiKey={apiKey}>
+      <StreamEvents sseUrl={sseUrl} />
+    </RestlessProvider>
+  );
+}
+```
+
+If you do not want to use context, pass an explicit core client to the hook.
+
+```tsx
+import { createRestlessClient } from '@restless-stream/core';
+import { useStreamSubscription } from '@restless-stream/react';
+
+const client = createRestlessClient({ apiKey: 'rs_server_or_private_runtime_key' });
+
+function StreamEvents({ sseUrl }: { sseUrl: string }) {
+  const subscription = useStreamSubscription({ client, sseUrl });
+  return <pre>{JSON.stringify(subscription.latestEvent, null, 2)}</pre>;
+}
+```
+
+## Provider API
+
+`RestlessProvider` creates or provides a core Restless Stream client.
+
+```tsx
+<RestlessProvider
+  apiKey={apiKey}
+  apiBaseUrl="https://api.restlessapi.stream"
+  streamBaseUrl="https://stream.restlessapi.stream"
+  headers={{ 'X-App': 'dashboard' }}
+>
+  <App />
+</RestlessProvider>
+```
+
+Provider props:
+
+| Prop | Description |
+| --- | --- |
+| `client` | Existing `RestlessClient`. When provided, config props are ignored. |
+| `config` | Full core client config object. |
+| `apiKey` | API key passed to `createRestlessClient`. |
+| `apiBaseUrl` | REST API base URL. |
+| `streamBaseUrl` | Runtime stream base URL. |
+| `fetch` | Custom fetch implementation. |
+| `headers` | Default REST headers. |
+| `children` | React children. |
+
+Use `useRestlessClient()` to read the client from context.
+
+```tsx
+import { useRestlessClient } from '@restless-stream/react';
+
+function StreamCount() {
+  const client = useRestlessClient();
+  // Use the client in effects, event handlers, or data loading code.
+  return <button onClick={() => void client.streams.list()}>Refresh</button>;
+}
+```
+
+`useRestlessClient` throws when used outside `RestlessProvider`.
+
+## `useStreamSubscription`
+
+`useStreamSubscription(options)` subscribes to an SSE URL through the core client's `streams.subscribeSse` method.
+
+```tsx
+const {
+  connect,
+  disconnect,
+  error,
+  events,
+  isConnected,
+  isConnecting,
+  latestEvent,
+  reset,
+  status,
+} = useStreamSubscription({
+  sseUrl,
+  enabled: true,
+  maxEvents: 100,
+  reconnect: true,
+  maxReconnectAttempts: 3,
+  reconnectDelayMs: (attempt) => attempt * 1000,
+  onEvent: (event) => console.log(event),
+  onError: (error) => console.error(error),
+});
+```
+
+Options:
+
+| Option | Description |
+| --- | --- |
+| `sseUrl` | Runtime SSE URL to subscribe to. |
+| `client` | Explicit core `RestlessClient`. Uses provider context when omitted. |
+| `enabled` | Starts the subscription automatically. Defaults to `true`. |
+| `maxEvents` | Maximum number of events kept in state. Defaults to `100`. Use `0` to keep none. |
+| `maxReconnectAttempts` | Hook-level retry count after subscription failures. Defaults to `0`. |
+| `onEvent` | Callback fired for each parsed Restless Stream event. |
+| `onError` | Callback fired when the subscription throws. |
+| `reconnect` | Enables hook-level reconnect attempts. Defaults to `false`. |
+| `reconnectDelayMs` | Number or function returning the delay for each reconnect attempt. Defaults to `1000`. |
+| `headers` | Additional SSE request headers. |
+| `allowApiKeyInUrl` | Opts into API key query-parameter auth for runtime URLs. Use carefully. |
+| `cursor` | Initial cursor or event ID. |
+| `since` | Initial timestamp or cursor. |
+
+Result fields:
+
+| Field | Description |
+| --- | --- |
+| `events` | Bounded array of received events. |
+| `latestEvent` | Most recent event, or `null`. |
+| `error` | Last normalized `Error`, or `null`. |
+| `status` | `idle`, `connecting`, `open`, `reconnecting`, `closed`, or `error`. |
+| `isConnected` | `true` when `status === 'open'`. |
+| `isConnecting` | `true` when `status` is `connecting` or `reconnecting`. |
+| `connect()` | Starts or restarts the subscription. |
+| `disconnect()` | Aborts the active subscription and sets status to `closed`. |
+| `reset()` | Clears buffered events and error state. |
+
+Manual connection example:
+
+```tsx
+function ManualStream({ sseUrl }: { sseUrl: string }) {
+  const stream = useStreamSubscription({
+    enabled: false,
+    sseUrl,
+  });
+
+  return (
+    <section>
+      <p>Status: {stream.status}</p>
+      <button onClick={stream.connect}>Connect</button>
+      <button onClick={stream.disconnect}>Disconnect</button>
+      <button onClick={stream.reset}>Clear events</button>
+    </section>
+  );
+}
+```
+
+## `useManagedStream`
+
+`useManagedStream` is a convenience wrapper for managed stream objects. It accepts either `sseUrl` directly or a `stream` object with an `sseUrl` field.
+
+```tsx
+function ManagedStream({ stream }: { stream: { sseUrl?: string | null } | null }) {
+  const { latestEvent, status } = useManagedStream({
+    stream,
+    maxEvents: 25,
+  });
+
+  return <pre>{JSON.stringify({ latestEvent, status }, null, 2)}</pre>;
+}
+```
+
+The hook auto-enables only when a non-empty URL is available, unless you pass `enabled` explicitly.
+
+## `useDirectStream`
+
+`useDirectStream` is a convenience wrapper for direct stream URLs or direct-session responses. It accepts `directUrl`, `sseUrl`, or `session.sseUrl`.
+
+```tsx
+function DirectSessionEvents({ session }: { session: { sseUrl?: string | null } | null }) {
+  const { latestEvent, status } = useDirectStream({
+    session,
+    reconnect: true,
+    maxReconnectAttempts: 3,
+  });
+
+  return <pre>{JSON.stringify({ latestEvent, status }, null, 2)}</pre>;
+}
+```
+
+`useDirectStream` does not create direct sessions. Create sessions with a trusted backend or the core SDK, then pass the returned `sseUrl` into React.
+
+## Browser Auth Notes
+
+`allowApiKeyInUrl` is supported by the underlying core client, but URLs can appear in logs, analytics, browser history, and referrer headers. Prefer header-based auth from trusted server runtimes or backend-created runtime URLs.
+
+## Public Exports
+
+| Export | Purpose |
+| --- | --- |
+| `RestlessProvider` | React context provider for a core Restless client. |
+| `RestlessProviderProps` | Provider props type. |
+| `useRestlessClient` | Reads the client from provider context. |
+| `useStreamSubscription` | Main SSE subscription hook. |
+| `useManagedStream` | Hook wrapper for managed stream objects or managed SSE URLs. |
+| `useDirectStream` | Hook wrapper for direct URLs or direct-session responses. |
+| `DEFAULT_MAX_EVENTS` | Default event buffer size, `100`. |
+| `StreamSubscriptionStatus` | Subscription status union. |
+| `StreamSubscriptionControls` | `connect`, `disconnect`, and `reset` controls. |
+| `UseStreamSubscriptionOptions` | Main hook options type. |
+| `UseStreamSubscriptionResult` | Main hook result type. |
+| `UseManagedStreamOptions` | Managed stream hook options type. |
+| `UseDirectStreamOptions` | Direct stream hook options type. |
+
+## Development
+
+```bash
+cd packages/typescript
+pnpm install
+pnpm --filter @restless-stream/react typecheck
+pnpm --filter @restless-stream/react test
+pnpm --filter @restless-stream/react build
+```

package/package.json

@@ -1,7 +1,25 @@
 {
   "name": "@restless-stream/react",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Lightweight React bindings for the Restless Stream SDK.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/restless-stream/sdk.git",
+    "directory": "packages/typescript/react"
+  },
+  "homepage": "https://github.com/restless-stream/sdk/tree/main/packages/typescript/react#readme",
+  "bugs": {
+    "url": "https://github.com/restless-stream/sdk/issues"
+  },
+  "keywords": [
+    "restless-stream",
+    "sdk",
+    "sse",
+    "streaming",
+    "react",
+    "hooks"
+  ],
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.cjs",
@@ -17,11 +35,14 @@
   "files": [
     "dist"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "peerDependencies": {
     "react": ">=18.2 <20"
   },
   "dependencies": {
-    "@restless-stream/core": "0.1.0"
+    "@restless-stream/core": "0.1.1"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",