@ekairos/story-react 1.21.91-beta.0 → 1.21.100-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +80 -80
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,80 +1,80 @@
1
- # @ekairos/story-react
2
-
3
- React primitives for Ekairos **Story** UIs.
4
-
5
- This package ships the core client hook: **`useStory()`**.
6
-
7
- ## Install
8
-
9
- ```bash
10
- pnpm add @ekairos/story-react
11
- ```
12
-
13
- ## What `useStory` does
14
-
15
- - **Timeline DX**: merges **persisted events** (InstantDB) + **optimistic user events** + **streaming assistant overlay**
16
- - **Streaming**: consumes `ai` UIMessage stream (SSE) and updates the timeline live
17
- - **Resumable streams (optional)**: stores `runId` + `chunkIndex` in `localStorage` and can resume with GET `?runId=...&startIndex=...`
18
-
19
- ## Usage
20
-
21
- ```tsx
22
- "use client";
23
-
24
- import { useStory } from "@ekairos/story-react";
25
-
26
- export function MyStoryUI({ db, apiUrl, contextId }: { db: any; apiUrl: string; contextId?: string }) {
27
- const story = useStory(db, {
28
- apiUrl,
29
- initialContextId: contextId,
30
- enableResumableStreams: true,
31
- onContextUpdate: (id) => console.log("contextId:", id),
32
- });
33
-
34
- return (
35
- <div>
36
- <pre>status: {story.contextStatus}</pre>
37
- <button
38
- disabled={story.sendStatus === "submitting"}
39
- onClick={() => story.append({ parts: [{ type: "text", text: "Hola" }] })}
40
- >
41
- Send
42
- </button>
43
- <pre>{JSON.stringify(story.events, null, 2)}</pre>
44
- </div>
45
- );
46
- }
47
- ```
48
-
49
- ## Default InstantDB queries (overrideable)
50
-
51
- By default, `useStory` expects these namespaces:
52
-
53
- - `context_contexts` (by `id`)
54
- - `context_events` (by `context.id`, ordered by `createdAt: "asc"`)
55
-
56
- If your schema differs, pass overrides (they MUST be hooks):
57
-
58
- ```ts
59
- useStory(db, {
60
- apiUrl,
61
- context: (db, { contextId }) => {
62
- const res = db.useQuery(/* your query */);
63
- return { context: res.data?...., contextStatus: "open" };
64
- },
65
- events: (db, { contextId }) => {
66
- const res = db.useQuery(/* your query */);
67
- return { events: res.data?.... ?? [] };
68
- },
69
- });
70
- ```
71
-
72
- ## API contract (server)
73
-
74
- `useStory` sends:
75
-
76
- - `POST apiUrl` with JSON `{ messages: [uiMessage], webSearch, reasoningLevel, contextId }`
77
- - `GET apiUrl?runId=...&startIndex=...` (only if `enableResumableStreams` is enabled)
78
-
79
- The server must respond with an `ai` SSE stream (`createUIMessageStreamResponse`).
80
-
1
+ # @ekairos/story-react
2
+
3
+ React primitives for Ekairos **Story** UIs.
4
+
5
+ This package ships the core client hook: **`useStory()`**.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pnpm add @ekairos/story-react
11
+ ```
12
+
13
+ ## What `useStory` does
14
+
15
+ - **Timeline DX**: merges **persisted events** (InstantDB) + **optimistic user events** + **streaming assistant overlay**
16
+ - **Streaming**: consumes `ai` UIMessage stream (SSE) and updates the timeline live
17
+ - **Resumable streams (optional)**: stores `runId` + `chunkIndex` in `localStorage` and can resume with GET `?runId=...&startIndex=...`
18
+
19
+ ## Usage
20
+
21
+ ```tsx
22
+ "use client";
23
+
24
+ import { useStory } from "@ekairos/story-react";
25
+
26
+ export function MyStoryUI({ db, apiUrl, contextId }: { db: any; apiUrl: string; contextId?: string }) {
27
+ const story = useStory(db, {
28
+ apiUrl,
29
+ initialContextId: contextId,
30
+ enableResumableStreams: true,
31
+ onContextUpdate: (id) => console.log("contextId:", id),
32
+ });
33
+
34
+ return (
35
+ <div>
36
+ <pre>status: {story.contextStatus}</pre>
37
+ <button
38
+ disabled={story.sendStatus === "submitting"}
39
+ onClick={() => story.append({ parts: [{ type: "text", text: "Hola" }] })}
40
+ >
41
+ Send
42
+ </button>
43
+ <pre>{JSON.stringify(story.events, null, 2)}</pre>
44
+ </div>
45
+ );
46
+ }
47
+ ```
48
+
49
+ ## Default InstantDB queries (overrideable)
50
+
51
+ By default, `useStory` expects these namespaces:
52
+
53
+ - `context_contexts` (by `id`)
54
+ - `context_events` (by `context.id`, ordered by `createdAt: "asc"`)
55
+
56
+ If your schema differs, pass overrides (they MUST be hooks):
57
+
58
+ ```ts
59
+ useStory(db, {
60
+ apiUrl,
61
+ context: (db, { contextId }) => {
62
+ const res = db.useQuery(/* your query */);
63
+ return { context: res.data?...., contextStatus: "open" };
64
+ },
65
+ events: (db, { contextId }) => {
66
+ const res = db.useQuery(/* your query */);
67
+ return { events: res.data?.... ?? [] };
68
+ },
69
+ });
70
+ ```
71
+
72
+ ## API contract (server)
73
+
74
+ `useStory` sends:
75
+
76
+ - `POST apiUrl` with JSON `{ messages: [uiMessage], webSearch, reasoningLevel, contextId }`
77
+ - `GET apiUrl?runId=...&startIndex=...` (only if `enableResumableStreams` is enabled)
78
+
79
+ The server must respond with an `ai` SSE stream (`createUIMessageStreamResponse`).
80
+
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ekairos/story-react",
3
- "version": "1.21.91-beta.0",
3
+ "version": "1.21.100-beta.0",
4
4
  "description": "Ekairos Story React - useStory hook",
5
5
  "type": "commonjs",
6
6
  "main": "dist/index.js",
@@ -14,7 +14,7 @@
14
14
  "license": "MIT",
15
15
  "repository": {
16
16
  "type": "git",
17
- "url": "git+https://github.com/pulz-ar/pulzar-lib-core.git",
17
+ "url": "git+https://github.com/e-kairos/ekairos-public.git",
18
18
  "directory": "packages/story-react"
19
19
  },
20
20
  "exports": {