@specific.dev/spectest 0.105.0 → 0.107.0

package/README.md

@@ -86,6 +86,48 @@ return annotate(turns, "chat", {
 The dashboard draws the chips on the bubble's lower corner, opposite the
 sender, and slides a new one in after the bubbles that arrived with it.
 
+## Read receipts and typing (0.106.0)
+
+A `chat` message can carry its delivery `status` (`delivered` or `read`)
+and an optional `statusAt` — free text such as `"23:14"` — drawn as the
+caption a messaging app shows under the bubble, on the bubble's own side.
+The annotation itself takes `typing: "self" | "other"`, drawn as the
+three-dot bubble at the end of the thread on that side. Both are the fake's
+to set, like `new`; typing is transient, so a step either shows it or not.
+
+```ts
+return annotate(turns, "chat", {
+  typing: state.agentTyping ? "other" : undefined,
+  messages: turns.map((t) => ({
+    side: t.fromCustomer ? "self" : "other",
+    text: t.body,
+    status: t.readAt ? "read" : "delivered",
+    statusAt: t.readAt,
+  })),
+});
+```
+
+## Inline replies (0.107.0)
+
+A `chat` message can carry an `id` — any non-empty string the fake chooses,
+the provider's message handle usually; it is never drawn — and a reply names
+an earlier message's `id` as `replyTo`. The dashboard draws the reply the
+way a messaging app threads one: an excerpt of the earlier message in a
+muted mini-bubble directly above the reply, on the reply's side, with a
+short connector between them. A `replyTo` that names no earlier message of
+the same call draws nothing extra; the bubble is an ordinary message.
+
+```ts
+return annotate(turns, "chat", {
+  messages: turns.map((t) => ({
+    id: t.id,
+    side: t.fromCustomer ? "self" : "other",
+    text: t.body,
+    replyTo: t.inReplyTo,
+  })),
+});
+```
+
 ## HTTP assertions
 
 `ctx.fetch()` returns a wrapped response. Status fields, header lookups, and

package/dist/annotate.d.ts

@@ -95,6 +95,14 @@ export interface ChatAnnotation {
      * reads fine without it.
      */
     title?: string;
+    /**
+     * Who is writing right now — `self` the end user, `other` whoever they
+     * are talking to — drawn as the three-dot bubble at the end of the
+     * thread on that side. It is the thread's present tense: a call either
+     * shows it or not, so there is no `new` to mark. Any other value is
+     * nobody typing.
+     */
+    typing?: "self" | "other";
 }
 /** One turn of a {@link ChatAnnotation}. */
 export interface ChatMessageAnnotation {
@@ -119,6 +127,34 @@ export interface ChatMessageAnnotation {
      * corner. A reaction that was removed simply stops being listed.
      */
     reactions?: readonly ChatReactionAnnotation[];
+    /**
+     * Delivery status, as the provider reported it: drawn as the small
+     * caption under the bubble ("Delivered", "Read"), on the bubble's own
+     * side. Any other value is left off — a caption, unlike a turn, can be
+     * dropped without the transcript lying.
+     */
+    status?: "delivered" | "read";
+    /**
+     * When, as the app would show it ("23:14"): free text drawn after the
+     * status ("Read 23:14"). Rides with `status`; alone it has nothing to
+     * qualify and is dropped.
+     */
+    statusAt?: string;
+    /**
+     * The author's handle for this message — the provider's message id,
+     * usually — so a later message can reply to it by name. Any non-empty
+     * string; the dashboard never draws it.
+     */
+    id?: string;
+    /**
+     * The `id` of an earlier message in this transcript that this one
+     * replies to, drawn the way a messaging app threads a reply: an excerpt
+     * of that message quoted above this bubble, on this bubble's side. One
+     * that names no earlier message of the same call — an unknown id, a
+     * later message, the message itself — draws nothing extra, and the
+     * bubble reads as an ordinary message.
+     */
+    replyTo?: string;
 }
 /** One reaction on a {@link ChatMessageAnnotation}. */
 export interface ChatReactionAnnotation {

package/dist/annotate.js

@@ -138,6 +138,7 @@ function lowerChat(options, value) {
     const source = deepUnwrap(options ?? value);
     let list;
     let title;
+    let typing;
     if (Array.isArray(source)) {
         list = source;
     }
@@ -145,6 +146,7 @@ function lowerChat(options, value) {
         const bag = fields(source);
         list = bag.messages;
         title = text(bag.title) || undefined;
+        typing = typingOf(bag.typing);
     }
     // An empty conversation is a real state (nothing said yet) and renders as
     // one; a value with no `messages` at all is the author's mistake.
@@ -157,7 +159,9 @@ function lowerChat(options, value) {
     return {
         kind: "chat",
         title,
-        blocks: [{ type: "chat", messages, ...(title ? { label: title } : {}) }],
+        blocks: [
+            { type: "chat", messages, ...(title ? { label: title } : {}), ...(typing ? { typing } : {}) },
+        ],
     };
 }
 function chatMessageOf(src) {
@@ -176,8 +180,35 @@ function chatMessageOf(src) {
     const reactions = reactionsOf(src.reactions);
     if (reactions.length > 0)
         msg.reactions = reactions;
+    // A status caption, unlike a turn, can be left off without the
+    // transcript lying, so one that isn't `delivered` or `read` is dropped
+    // rather than guessed at. Its time rides with it: free text, truncated
+    // like a body, and meaningless without a status to qualify.
+    const status = src.status;
+    if (status === "delivered" || status === "read") {
+        msg.status = status;
+        if (typeof src.statusAt === "string" && src.statusAt !== "") {
+            msg.statusAt = truncateUtf8(src.statusAt).value;
+        }
+    }
+    // A reply threads to an earlier message by the handle its author gave
+    // it, so both ride through as given — a non-empty string, cut like a
+    // body — and anything else is dropped. Whether `replyTo` names an
+    // earlier message of the transcript is the dashboard's to decide: it
+    // draws the quote when it can and an ordinary bubble when it cannot.
+    if (typeof src.id === "string" && src.id !== "")
+        msg.id = truncateUtf8(src.id).value;
+    if (typeof src.replyTo === "string" && src.replyTo !== "") {
+        msg.replyTo = truncateUtf8(src.replyTo).value;
+    }
     return msg;
 }
+/** The block's `typing`: `self` or `other`, else nobody. The thread's
+ *  present tense is a decoration, not a turn, so a value that isn't one of
+ *  the two draws nothing rather than guessing at who. */
+function typingOf(v) {
+    return v === "self" || v === "other" ? v : undefined;
+}
 /** Reactions get the tolerance `side` gets: an entry that isn't quite right
  *  is drawn rather than dropped — a `from` that is missing or misspelled is
  *  the other party's — and only one with nothing to draw (no string

package/dist/recorder.d.ts

@@ -631,6 +631,7 @@ export type StepBlock = {
     type: "chat";
     messages: ChatBlockMessage[];
     label?: string;
+    typing?: "self" | "other";
 } | {
     type: "details";
     summary: string;
@@ -651,6 +652,23 @@ export interface ChatBlockMessage {
      *  corner, on the side opposite the sender. Absent and empty read the
      *  same: nothing to draw. */
     reactions?: ChatBlockReaction[];
+    /** Delivery status — the caption a messaging app shows under a bubble
+     *  ("Delivered", "Read"), on the bubble's own side. Absent draws
+     *  nothing. */
+    status?: "delivered" | "read";
+    /** When the status happened, as the app would show it ("23:14"): free
+     *  text drawn after the status caption ("Read 23:14"). Rides with
+     *  `status`; alone it has nothing to qualify. */
+    statusAt?: string;
+    /** The author's handle for this message — the provider's message id,
+     *  usually — which a later message's `replyTo` names. Never drawn.
+     *  Absent when the author gave none. */
+    id?: string;
+    /** The `id` of an earlier message in the same block this one replies
+     *  to, drawn as a quoted excerpt of that message above the bubble, the
+     *  way a messaging app threads a reply. One that names no earlier
+     *  message draws nothing extra. */
+    replyTo?: string;
 }
 /** One reaction on a {@link ChatBlockMessage}. */
 export interface ChatBlockReaction {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.105.0",
+  "version": "0.107.0",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/annotate.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
-import { annotate, readAnnotation } from "./annotate.js";
+import { annotate, readAnnotation, type ChatMessageAnnotation } from "./annotate.js";
+import { truncateUtf8 } from "./recorder.js";
 
 /** Open a chat annotation: the messages its one block lowered to, and the
  *  value the test would receive. */
@@ -9,7 +10,7 @@ function chat(boxed: unknown) {
   if (!opened || opened.annotation.kind !== "chat") throw new Error("not a chat annotation");
   const block = opened.annotation.blocks[0];
   if (!block || block.type !== "chat") throw new Error("not a chat block");
-  return { messages: block.messages, value: opened.value };
+  return { messages: block.messages, typing: block.typing, block, value: opened.value };
 }
 
 describe("annotate chat", () => {
@@ -77,3 +78,127 @@ describe("annotate chat", () => {
     expect(messages[0]!.reactions).toEqual([{ emoji: "✅", from: "self", new: true }]);
   });
 });
+
+describe("annotate chat status and typing", () => {
+  test("captions a message with its delivery status and leaves the rest alone", () => {
+    const { messages } = chat(
+      annotate(
+        [
+          { side: "self", text: "where is my order?", status: "read", statusAt: "23:14" },
+          { side: "self", text: "hello?", status: "delivered" },
+          { side: "other", text: "It ships today.", new: true },
+        ],
+        "chat",
+      ),
+    );
+    expect(messages[0]).toEqual({ side: "self", text: "where is my order?", status: "read", statusAt: "23:14" });
+    // A status without a time carries no `statusAt`; a message without a
+    // status carries neither key.
+    expect(messages[1]).toEqual({ side: "self", text: "hello?", status: "delivered" });
+    expect(messages[2]).toEqual({ side: "other", text: "It ships today.", new: true });
+  });
+
+  // A caption, unlike a turn, can be left off without the transcript
+  // lying: a status that isn't one of the two is dropped, and so is a time
+  // that isn't text, is empty, or has no status to qualify.
+  test("drops a status it does not know and a time it cannot draw", () => {
+    const { messages } = chat(
+      annotate(
+        [
+          { side: "self", text: "a", status: "seen", statusAt: "23:14" },
+          { side: "self", text: "b", status: "read", statusAt: 2314 },
+          { side: "self", text: "c", statusAt: "23:14" },
+          { side: "self", text: "d", status: "read", statusAt: "" },
+        ],
+        "chat",
+      ),
+    );
+    expect(messages[0]).toEqual({ side: "self", text: "a" });
+    expect(messages[1]).toEqual({ side: "self", text: "b", status: "read" });
+    expect(messages[2]).toEqual({ side: "self", text: "c" });
+    expect(messages[3]).toEqual({ side: "self", text: "d", status: "read" });
+  });
+
+  test("a typing indicator rides on the block, and only for a side it knows", () => {
+    const messages: ChatMessageAnnotation[] = [{ side: "other", text: "Let me check." }];
+    expect(chat(annotate({ id: 7 }, "chat", { messages, typing: "other" })).typing).toBe("other");
+    expect(chat(annotate({ id: 7 }, "chat", { messages, typing: "self" })).typing).toBe("self");
+    // Nobody typing is no key at all: absent, misspelled, or a bare flag.
+    // (Read off the value, which skips the options' typing.)
+    expect(chat(annotate({ id: 7 }, "chat", { messages })).block).toEqual({
+      type: "chat",
+      messages: [{ side: "other", text: "Let me check." }],
+    });
+    for (const typing of ["agent", true, null, ""]) {
+      expect(chat(annotate({ messages, typing }, "chat")).typing).toBeUndefined();
+    }
+    // The messages-alone form has no block options to carry it.
+    expect(chat(annotate(messages, "chat")).typing).toBeUndefined();
+  });
+});
+
+describe("annotate chat inline replies", () => {
+  test("threads a reply to the earlier message it names and leaves the rest alone", () => {
+    const { messages } = chat(
+      annotate(
+        [
+          { id: "m1", side: "other", text: "Let me check." },
+          { id: "m2", side: "self", text: "where is my order?", replyTo: "m1", new: true },
+          { side: "other", text: "It ships today." },
+        ],
+        "chat",
+      ),
+    );
+    expect(messages[0]).toEqual({ id: "m1", side: "other", text: "Let me check." });
+    expect(messages[1]).toEqual({ id: "m2", side: "self", text: "where is my order?", replyTo: "m1", new: true });
+    // A message with neither carries neither key.
+    expect(messages[2]).toEqual({ side: "other", text: "It ships today." });
+  });
+
+  // Both are the author's handles, carried as given: the dashboard sees
+  // the whole transcript and decides whether a `replyTo` names an earlier
+  // message, drawing an ordinary bubble when it does not. Only a value
+  // that is not a non-empty string is dropped.
+  test("drops an id or a replyTo that is not a non-empty string and carries the rest as given", () => {
+    const { messages } = chat(
+      annotate(
+        [
+          { id: 42, side: "self", text: "a", replyTo: 7 },
+          { id: "", side: "self", text: "b", replyTo: "" },
+          { id: null, side: "self", text: "c", replyTo: true },
+          { id: "m4", side: "self", text: "d", replyTo: "nowhere" },
+        ],
+        "chat",
+      ),
+    );
+    expect(messages[0]).toEqual({ side: "self", text: "a" });
+    expect(messages[1]).toEqual({ side: "self", text: "b" });
+    expect(messages[2]).toEqual({ side: "self", text: "c" });
+    expect(messages[3]).toEqual({ id: "m4", side: "self", text: "d", replyTo: "nowhere" });
+  });
+
+  test("an id is cut like a body, and the replyTo that names it the same way", () => {
+    // Past the recorder's snippet cap, so the cut is visible.
+    const long = "m".repeat(300_000);
+    const { messages } = chat(
+      annotate(
+        [
+          { id: long, side: "other", text: "Let me check." },
+          { side: "self", text: "ok", replyTo: long },
+        ],
+        "chat",
+      ),
+    );
+    expect(messages[0]!.id).toBe(truncateUtf8(long).value);
+    expect(messages[0]!.id!.length).toBeLessThan(long.length);
+    expect(messages[1]!.replyTo).toBe(messages[0]!.id);
+  });
+
+  test("replies ride along when the messages are passed as options", () => {
+    const messages: ChatMessageAnnotation[] = [
+      { id: "m1", side: "other", text: "Done?" },
+      { id: "m2", side: "self", text: "Yes.", replyTo: "m1" },
+    ];
+    expect(chat(annotate({ id: 7 }, "chat", { title: "+46 70 123 45 67", messages })).messages).toEqual(messages);
+  });
+});

package/src/annotate.ts

@@ -153,6 +153,14 @@ export interface ChatAnnotation {
    * reads fine without it.
    */
   title?: string;
+  /**
+   * Who is writing right now — `self` the end user, `other` whoever they
+   * are talking to — drawn as the three-dot bubble at the end of the
+   * thread on that side. It is the thread's present tense: a call either
+   * shows it or not, so there is no `new` to mark. Any other value is
+   * nobody typing.
+   */
+  typing?: "self" | "other";
 }
 
 /** One turn of a {@link ChatAnnotation}. */
@@ -178,6 +186,34 @@ export interface ChatMessageAnnotation {
    * corner. A reaction that was removed simply stops being listed.
    */
   reactions?: readonly ChatReactionAnnotation[];
+  /**
+   * Delivery status, as the provider reported it: drawn as the small
+   * caption under the bubble ("Delivered", "Read"), on the bubble's own
+   * side. Any other value is left off — a caption, unlike a turn, can be
+   * dropped without the transcript lying.
+   */
+  status?: "delivered" | "read";
+  /**
+   * When, as the app would show it ("23:14"): free text drawn after the
+   * status ("Read 23:14"). Rides with `status`; alone it has nothing to
+   * qualify and is dropped.
+   */
+  statusAt?: string;
+  /**
+   * The author's handle for this message — the provider's message id,
+   * usually — so a later message can reply to it by name. Any non-empty
+   * string; the dashboard never draws it.
+   */
+  id?: string;
+  /**
+   * The `id` of an earlier message in this transcript that this one
+   * replies to, drawn the way a messaging app threads a reply: an excerpt
+   * of that message quoted above this bubble, on this bubble's side. One
+   * that names no earlier message of the same call — an unknown id, a
+   * later message, the message itself — draws nothing extra, and the
+   * bubble reads as an ordinary message.
+   */
+  replyTo?: string;
 }
 
 /** One reaction on a {@link ChatMessageAnnotation}. */
@@ -326,12 +362,14 @@ function lowerChat(
   const source: unknown = deepUnwrap(options ?? value);
   let list: unknown;
   let title: string | undefined;
+  let typing: "self" | "other" | undefined;
   if (Array.isArray(source)) {
     list = source;
   } else {
     const bag = fields(source);
     list = bag.messages;
     title = text(bag.title) || undefined;
+    typing = typingOf(bag.typing);
   }
   // An empty conversation is a real state (nothing said yet) and renders as
   // one; a value with no `messages` at all is the author's mistake.
@@ -343,7 +381,9 @@ function lowerChat(
   return {
     kind: "chat",
     title,
-    blocks: [{ type: "chat", messages, ...(title ? { label: title } : {}) }],
+    blocks: [
+      { type: "chat", messages, ...(title ? { label: title } : {}), ...(typing ? { typing } : {}) },
+    ],
   };
 }
 
@@ -358,9 +398,36 @@ function chatMessageOf(src: Record<string, unknown>): ChatBlockMessage {
   if (src.new === true) msg.new = true;
   const reactions = reactionsOf(src.reactions);
   if (reactions.length > 0) msg.reactions = reactions;
+  // A status caption, unlike a turn, can be left off without the
+  // transcript lying, so one that isn't `delivered` or `read` is dropped
+  // rather than guessed at. Its time rides with it: free text, truncated
+  // like a body, and meaningless without a status to qualify.
+  const status = src.status;
+  if (status === "delivered" || status === "read") {
+    msg.status = status;
+    if (typeof src.statusAt === "string" && src.statusAt !== "") {
+      msg.statusAt = truncateUtf8(src.statusAt).value;
+    }
+  }
+  // A reply threads to an earlier message by the handle its author gave
+  // it, so both ride through as given — a non-empty string, cut like a
+  // body — and anything else is dropped. Whether `replyTo` names an
+  // earlier message of the transcript is the dashboard's to decide: it
+  // draws the quote when it can and an ordinary bubble when it cannot.
+  if (typeof src.id === "string" && src.id !== "") msg.id = truncateUtf8(src.id).value;
+  if (typeof src.replyTo === "string" && src.replyTo !== "") {
+    msg.replyTo = truncateUtf8(src.replyTo).value;
+  }
   return msg;
 }
 
+/** The block's `typing`: `self` or `other`, else nobody. The thread's
+ *  present tense is a decoration, not a turn, so a value that isn't one of
+ *  the two draws nothing rather than guessing at who. */
+function typingOf(v: unknown): "self" | "other" | undefined {
+  return v === "self" || v === "other" ? v : undefined;
+}
+
 /** Reactions get the tolerance `side` gets: an entry that isn't quite right
  *  is drawn rather than dropped — a `from` that is missing or misspelled is
  *  the other party's — and only one with nothing to draw (no string

package/src/recorder.ts

@@ -882,7 +882,9 @@ export type StepBlock =
   | { type: "kv"; rows: { label: string; value?: string; error?: boolean }[]; label?: string }
   | { type: "table"; columns: string[]; rows: unknown[][] }
   | { type: "htmlSandbox"; html: string; label?: string }
-  | { type: "chat"; messages: ChatBlockMessage[]; label?: string }
+  // `typing` is the thread's present tense: whoever is writing right now
+  // gets the three-dot bubble at the end of the thread, on their side.
+  | { type: "chat"; messages: ChatBlockMessage[]; label?: string; typing?: "self" | "other" }
   // A disclosure. For what a step has but a reader does not want on every
   // step — a connection's protocol version, session id, redacted token.
   | { type: "details"; summary: string; blocks: StepBlock[] };
@@ -902,6 +904,23 @@ export interface ChatBlockMessage {
    *  corner, on the side opposite the sender. Absent and empty read the
    *  same: nothing to draw. */
   reactions?: ChatBlockReaction[];
+  /** Delivery status — the caption a messaging app shows under a bubble
+   *  ("Delivered", "Read"), on the bubble's own side. Absent draws
+   *  nothing. */
+  status?: "delivered" | "read";
+  /** When the status happened, as the app would show it ("23:14"): free
+   *  text drawn after the status caption ("Read 23:14"). Rides with
+   *  `status`; alone it has nothing to qualify. */
+  statusAt?: string;
+  /** The author's handle for this message — the provider's message id,
+   *  usually — which a later message's `replyTo` names. Never drawn.
+   *  Absent when the author gave none. */
+  id?: string;
+  /** The `id` of an earlier message in the same block this one replies
+   *  to, drawn as a quoted excerpt of that message above the bubble, the
+   *  way a messaging app threads a reply. One that names no earlier
+   *  message draws nothing extra. */
+  replyTo?: string;
 }
 
 /** One reaction on a {@link ChatBlockMessage}. */