@butlerbot/sdk 0.0.27 → 0.0.28

package/dist/modules/stream_accumulator.d.ts

@@ -12,9 +12,14 @@
  *     { messageId, message: "Good day to you", completed }   // the whole value: replace
  *     { messageId, delta: " to you", completed: false }      // what was added: append
  *
- * Callers should not have to care. This puts the message back together, so
- * `payload.message` is the whole message so far exactly as it always was, and keeps
- * `payload.delta` for anyone who would rather append than re-render.
+ * Deltas are also sent bare: no metadata block, since it is the same on every frame of a
+ * message and several times the size of the few characters a delta carries. The frame that
+ * opens a message brings it, and the one that finishes it brings it again.
+ *
+ * Callers should not have to care about any of that. This puts the message back together,
+ * so `payload.message` is the whole message so far exactly as it always was, restores the
+ * metadata onto every event, and keeps `payload.delta` for anyone who would rather append
+ * than re-render.
  *
  * Whole values arrive for the last event of a message and for anything replaying after a
  * reconnect, and they replace rather than extend. That is what makes a reconnect cheap and
@@ -23,7 +28,7 @@
 /**
  * Rebuilds whole values from a stream of pieces.
  *
- * Stateful, and one per stream: it holds the text of every message the stream is still
- * writing, so a turn and a progress stream never see each other's.
+ * Stateful, and one per stream: it holds what every message the stream is still writing
+ * has said so far, so a turn and a progress stream never see each other's.
  */
 export declare function createStreamAccumulator(): (payload: unknown) => unknown;

package/dist/modules/stream_accumulator.js

@@ -13,9 +13,14 @@
  *     { messageId, message: "Good day to you", completed }   // the whole value: replace
  *     { messageId, delta: " to you", completed: false }      // what was added: append
  *
- * Callers should not have to care. This puts the message back together, so
- * `payload.message` is the whole message so far exactly as it always was, and keeps
- * `payload.delta` for anyone who would rather append than re-render.
+ * Deltas are also sent bare: no metadata block, since it is the same on every frame of a
+ * message and several times the size of the few characters a delta carries. The frame that
+ * opens a message brings it, and the one that finishes it brings it again.
+ *
+ * Callers should not have to care about any of that. This puts the message back together,
+ * so `payload.message` is the whole message so far exactly as it always was, restores the
+ * metadata onto every event, and keeps `payload.delta` for anyone who would rather append
+ * than re-render.
  *
  * Whole values arrive for the last event of a message and for anything replaying after a
  * reconnect, and they replace rather than extend. That is what makes a reconnect cheap and
@@ -31,10 +36,11 @@ const STREAMED_FIELDS = {
 /**
  * Rebuilds whole values from a stream of pieces.
  *
- * Stateful, and one per stream: it holds the text of every message the stream is still
- * writing, so a turn and a progress stream never see each other's.
+ * Stateful, and one per stream: it holds what every message the stream is still writing
+ * has said so far, so a turn and a progress stream never see each other's.
  */
 function createStreamAccumulator() {
+    /** Text so far and the metadata it was opened with, per streamed id. */
     const values = new Map();
     return (payload) => {
         const response = payload;
@@ -52,19 +58,26 @@ function createStreamAccumulator() {
         const whole = event.payload[fields.text];
         if (typeof delta !== "string" && typeof whole !== "string")
             return payload;
-        const text = typeof delta === "string" ? (values.get(id) ?? "") + delta : whole;
+        const held = values.get(id);
+        const text = typeof delta === "string" ? (held?.text ?? "") + delta : whole;
+        // Deltas are sent without metadata, because it is identical on every frame of a
+        // message and many times the size of the text. The frame that opened the message
+        // carried it, so it is remembered here and handed back on every event — a caller
+        // sees it throughout, exactly as when the server repeated it a thousand times.
+        const metadata = event.metadata ?? held?.metadata;
         // A finished value is the last anyone will hear of that id. Holding it would only
         // leak, and ids are reused across the steps of a turn.
         if (event.payload.completed)
             values.delete(id);
         else
-            values.set(id, text);
+            values.set(id, { text, metadata });
         return {
             ...response,
             data: {
                 ...response.data,
                 response: {
                     ...event,
+                    ...(metadata !== undefined ? { metadata } : {}),
                     payload: {
                         ...event.payload,
                         [fields.text]: text,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@butlerbot/sdk",
-	"version": "0.0.27",
+	"version": "0.0.28",
 	"description": "The official ButlerBot SDK",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

package/readme.md

@@ -41,15 +41,19 @@ const { text } = await convo.ask("Hey there Alfred!");
 
 ### Streaming
 
-Alfred streams a reply as it writes it. Each event carries either the whole message so far
-or just the piece it added, never both:
+Alfred streams a reply as it writes it. A message opens with a whole value, is extended a
+piece at a time, and finishes whole again. No event carries both:
 
 ```jsonc
-{ "messageId": "m1", "message": "Good day to you", "completed": false }  // whole: replace
-{ "messageId": "m1", "delta": " to you", "completed": false }            // added: append
+{ "messageId": "m1", "message": "Good day", "completed": false, "metadata": {...} }
+{ "messageId": "m1", "delta": " to you", "completed": false }
+{ "messageId": "m1", "message": "Good day to you", "completed": true, "metadata": {...} }
 ```
 
-The SDK puts them back together, so `payload.message` is always the whole message:
+Deltas travel bare — no metadata block, since it is identical on every frame of a message
+and many times the size of the few characters a delta carries. The SDK remembers it from
+the frame that opened the message and puts it back, so **every event you receive has both
+the whole message and its metadata**, exactly as it always did:
 
 ```typescript
 convo.send("Tell me a story", (res) => {
@@ -68,9 +72,9 @@ stuttering one — append it when it is there, and replace with `message` when i
 after a reconnect. Do not read `completed` to tell the two apart — a whole message arrives
 with `completed: false` whenever you are being caught up mid-answer.
 
-`accumulateStream: false` hands you the wire payloads untouched, where a piece arrives as
-`delta` with no `message` beside it. Only worth it if you are appending anyway and want
-nothing between you and the socket.
+`accumulateStream: false` hands you the wire payloads untouched: deltas with no `message`
+beside them and no metadata. Only worth it if you are appending anyway and want nothing
+between you and the socket.
 
 ## Link