@restless-stream/react 0.1.1 → 0.1.2

package/README.md

@@ -252,6 +252,94 @@ function DirectSessionEvents({ session }: { session: { sseUrl?: string | null }
 | `UseManagedStreamOptions` | Managed stream hook options type. |
 | `UseDirectStreamOptions` | Direct stream hook options type. |
 
+## Appendix: Creating an API Key
+
+API keys are used by the core client passed to `RestlessProvider`, or by your backend when generating stream URLs. 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.
+
+> **Browser safety:** Do not embed long-lived API keys in public browser bundles. Create stream URLs or direct sessions on your backend and pass the SSE URL to React components.
+
+### Pass the key to the provider (trusted environments only)
+
+```tsx
+import { RestlessProvider } from '@restless-stream/react';
+
+export function App({ sseUrl }: { sseUrl: string }) {
+  return (
+    <RestlessProvider apiKey={process.env.RESTLESS_API_KEY}>
+      {/* children */}
+    </RestlessProvider>
+  );
+}
+```
+
+## Sample Responses
+
+The `useStreamSubscription` hook result object has the following shape when connected to a direct-mode SSE URL:
+
+```ts
+const {
+  status,      // 'idle' | 'connecting' | 'open' | 'reconnecting' | 'closed' | 'error'
+  events,      // StreamEvent[]  — bounded buffer of received events
+  latestEvent, // StreamEvent | null
+  error,       // Error | null
+  isConnected, // boolean
+  connect,     // () => void
+  disconnect,  // () => void
+  reset,       // () => void
+} = useStreamSubscription({ sseUrl, maxEvents: 100 });
+```
+
+**Example `latestEvent` value** (after an update from `https://httpbin.org/get`):
+
+```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"
+  }
+}
+```
+
+**`status` progression for a successful connection:**
+
+| Step | `status` |
+|------|----------|
+| Before `enabled` | `idle` |
+| Opening connection | `connecting` |
+| First event received | `open` |
+| After disconnect | `closed` |
+| After error | `error` |
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@restless-stream/react",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Lightweight React bindings for the Restless Stream SDK.",
   "license": "MIT",
   "repository": {
@@ -42,7 +42,7 @@
     "react": ">=18.2 <20"
   },
   "dependencies": {
-    "@restless-stream/core": "0.1.1"
+    "@restless-stream/core": "0.1.2"
   },
   "devDependencies": {
     "@testing-library/react": "^16.3.0",