@starcite/sdk 0.0.1 → 0.0.3

package/README.md

@@ -151,13 +151,51 @@ setTimeout(() => controller.abort(), 5000);
 for await (const event of session.tail({
   cursor: 0,
   agent: "drafter",
+  reconnect: true,
+  reconnectDelayMs: 3000,
   signal: controller.signal,
 })) {
   console.log(event);
 }
 ```
 
-`tail()` replays `seq > cursor` and then streams live events on the same connection.
+`tail()` replays `seq > cursor`, streams live events, and automatically reconnects
+on transport failures while resuming from the last observed `seq`.
+
+- Set `reconnect: false` to disable automatic reconnect behavior.
+- By default, reconnect retries continue until the stream is aborted or closes gracefully.
+- Use `reconnectDelayMs` to control retry cadence for spotty networks.
+
+## Browser Restart Resilience
+
+`tail()` reconnects robustly for transport failures, but browser refresh/crash
+resets in-memory state. Persist your last processed `seq` and restart from it.
+
+```ts
+const sessionId = "ses_demo";
+const cursorKey = `starcite:${sessionId}:lastSeq`;
+
+const rawCursor = localStorage.getItem(cursorKey) ?? "0";
+let lastSeq = Number.parseInt(rawCursor, 10);
+
+if (!Number.isInteger(lastSeq) || lastSeq < 0) {
+  lastSeq = 0;
+}
+
+for await (const event of client.session(sessionId).tail({
+  cursor: lastSeq,
+  reconnect: true,
+  reconnectDelayMs: 3000,
+})) {
+  // Process event first, then persist cursor when your side effects succeed.
+  await renderOrStore(event);
+  lastSeq = event.seq;
+  localStorage.setItem(cursorKey, `${lastSeq}`);
+}
+```
+
+This pattern protects against missed events across browser restarts. Design your
+event handler to be idempotent by `seq` to safely tolerate replays.
 
 ## Error Handling
 
@@ -212,6 +250,12 @@ bun run --cwd packages/typescript-sdk build
 bun run --cwd packages/typescript-sdk test
 ```
 
+Optional reconnect soak test (runs ~40s, disabled by default):
+
+```bash
+STARCITE_SDK_RUN_SOAK=1 bun run --cwd packages/typescript-sdk test -- test/client.reconnect.integration.test.ts
+```
+
 ## Links
 
 - Product docs and examples: https://starcite.ai

package/dist/index.cjs

@@ -66,10 +66,17 @@ var StarciteConnectionError = class extends StarciteError {
 // src/types.ts
 var import_zod = require("zod");
 var ArbitraryObjectSchema = import_zod.z.record(import_zod.z.unknown());
+var CreatorTypeSchema = import_zod.z.union([import_zod.z.literal("user"), import_zod.z.literal("agent")]);
+var SessionCreatorPrincipalSchema = import_zod.z.object({
+  tenant_id: import_zod.z.string().min(1),
+  id: import_zod.z.string().min(1),
+  type: CreatorTypeSchema
+});
 var CreateSessionInputSchema = import_zod.z.object({
   id: import_zod.z.string().optional(),
   title: import_zod.z.string().optional(),
-  metadata: ArbitraryObjectSchema.optional()
+  metadata: ArbitraryObjectSchema.optional(),
+  creator_principal: SessionCreatorPrincipalSchema.optional()
 });
 var SessionRecordSchema = import_zod.z.object({
   id: import_zod.z.string(),
@@ -147,6 +154,12 @@ var StarciteErrorPayloadSchema = import_zod.z.object({
 var DEFAULT_BASE_URL = typeof process !== "undefined" && process.env.STARCITE_BASE_URL ? process.env.STARCITE_BASE_URL : "http://localhost:4000";
 var TRAILING_SLASHES_REGEX = /\/+$/;
 var BEARER_PREFIX_REGEX = /^bearer\s+/i;
+var DEFAULT_TAIL_RECONNECT_DELAY_MS = 3e3;
+var CATCH_UP_IDLE_MS = 1e3;
+var NORMAL_WEBSOCKET_CLOSE_CODE = 1e3;
+var SERVICE_TOKEN_SUB_ORG_PREFIX = "org:";
+var SERVICE_TOKEN_SUB_AGENT_PREFIX = "agent:";
+var SERVICE_TOKEN_SUB_USER_PREFIX = "user:";
 var TailFrameSchema = import_zod2.z.string().transform((frame, context) => {
   try {
     return JSON.parse(frame);
@@ -267,6 +280,105 @@ function formatAuthorizationHeader(apiKey) {
   }
   return `Bearer ${normalized}`;
 }
+function firstNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+}
+function parseJwtSegment(segment) {
+  const base64 = segment.replace(/-/g, "+").replace(/_/g, "/").padEnd(segment.length + (4 - segment.length % 4) % 4, "=");
+  try {
+    if (typeof atob === "function") {
+      return atob(base64);
+    }
+    if (typeof Buffer !== "undefined") {
+      return Buffer.from(base64, "base64").toString("utf8");
+    }
+  } catch {
+    return void 0;
+  }
+  return void 0;
+}
+function parseJwtClaims(apiKey) {
+  const token = apiKey.replace(BEARER_PREFIX_REGEX, "").trim();
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return void 0;
+  }
+  const [, payloadSegment] = parts;
+  if (payloadSegment === void 0) {
+    return void 0;
+  }
+  const payload = parseJwtSegment(payloadSegment);
+  if (payload === void 0) {
+    return void 0;
+  }
+  try {
+    const decoded = JSON.parse(payload);
+    return decoded !== null && typeof decoded === "object" ? decoded : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function parseClaimStrings(source, keys) {
+  for (const key of keys) {
+    const value = firstNonEmptyString(source[key]);
+    if (value) {
+      return value;
+    }
+  }
+  return void 0;
+}
+function parseActorIdentityFromSubject(subject) {
+  if (subject.startsWith(SERVICE_TOKEN_SUB_AGENT_PREFIX)) {
+    return { id: subject, type: "agent" };
+  }
+  if (subject.startsWith(SERVICE_TOKEN_SUB_USER_PREFIX)) {
+    return { id: subject, type: "user" };
+  }
+  return void 0;
+}
+function parseTenantIdFromSubject(subject) {
+  const actorIdentity = parseActorIdentityFromSubject(subject);
+  if (actorIdentity !== void 0) {
+    return "";
+  }
+  if (subject.startsWith(SERVICE_TOKEN_SUB_ORG_PREFIX)) {
+    return subject.slice(SERVICE_TOKEN_SUB_ORG_PREFIX.length).trim();
+  }
+  return subject;
+}
+function parseCreatorPrincipalFromClaims(claims) {
+  const subject = firstNonEmptyString(claims.sub);
+  const explicitPrincipal = claims.principal && typeof claims.principal === "object" ? claims.principal : void 0;
+  const mergedClaims = explicitPrincipal ? { ...claims, ...explicitPrincipal } : claims;
+  const actorFromSubject = subject ? parseActorIdentityFromSubject(subject) : void 0;
+  const principalTypeFromClaims = parseClaimStrings(mergedClaims, [
+    "principal_type",
+    "principalType",
+    "type"
+  ]);
+  const tenantId = parseClaimStrings(mergedClaims, ["tenant_id", "tenantId"]);
+  const rawPrincipalId = parseClaimStrings(mergedClaims, [
+    "principal_id",
+    "principalId",
+    "id",
+    "sub"
+  ]);
+  const actorFromRawId = rawPrincipalId ? parseActorIdentityFromSubject(rawPrincipalId) : void 0;
+  const principal = {
+    tenant_id: tenantId ?? (subject ? parseTenantIdFromSubject(subject) : ""),
+    id: rawPrincipalId ?? actorFromSubject?.id ?? "",
+    type: principalTypeFromClaims === "agent" || principalTypeFromClaims === "user" ? principalTypeFromClaims : actorFromSubject?.type ?? actorFromRawId?.type ?? "user"
+  };
+  if (principal.tenant_id.length === 0 || principal.id.length === 0 || principal.type.length === 0) {
+    return void 0;
+  }
+  const result = SessionCreatorPrincipalSchema.safeParse(principal);
+  return result.success ? result.data : void 0;
+}
+function parseCreatorPrincipalFromClaimsSafe(apiKey) {
+  const claims = parseJwtClaims(apiKey);
+  return claims ? parseCreatorPrincipalFromClaims(claims) : void 0;
+}
 function parseEventFrame(data) {
   const result = TailFrameSchema.safeParse(data);
   if (!result.success) {
@@ -281,6 +393,58 @@ function getEventData(event) {
   }
   return void 0;
 }
+function getCloseCode(event) {
+  if (event && typeof event === "object" && "code" in event) {
+    const code = event.code;
+    return typeof code === "number" ? code : void 0;
+  }
+  return void 0;
+}
+function getCloseReason(event) {
+  if (event && typeof event === "object" && "reason" in event) {
+    const reason = event.reason;
+    return typeof reason === "string" && reason.length > 0 ? reason : void 0;
+  }
+  return void 0;
+}
+function describeClose(code, reason) {
+  const codeText = `code ${typeof code === "number" ? code : "unknown"}`;
+  return reason ? `${codeText}, reason '${reason}'` : codeText;
+}
+async function waitForDelay(ms, signal) {
+  if (ms <= 0) {
+    return;
+  }
+  await new Promise((resolve) => {
+    let settled = false;
+    const timeout = setTimeout(() => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (signal) {
+        signal.removeEventListener("abort", onAbort);
+      }
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    };
+    if (signal) {
+      if (signal.aborted) {
+        onAbort();
+        return;
+      }
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
 function agentFromActor(actor) {
   if (actor.startsWith("agent:")) {
     return actor.slice("agent:".length);
@@ -350,6 +514,7 @@ var StarciteSession = class {
 var StarciteClient = class {
   /** Normalized API base URL ending with `/v1`. */
   baseUrl;
+  inferredCreatorPrincipal;
   websocketBaseUrl;
   fetchFn;
   headers;
@@ -363,10 +528,9 @@ var StarciteClient = class {
     this.fetchFn = options.fetch ?? defaultFetch;
     this.headers = new Headers(options.headers);
     if (options.apiKey !== void 0) {
-      this.headers.set(
-        "authorization",
-        formatAuthorizationHeader(options.apiKey)
-      );
+      const authorization = formatAuthorizationHeader(options.apiKey);
+      this.headers.set("authorization", authorization);
+      this.inferredCreatorPrincipal = parseCreatorPrincipalFromClaimsSafe(authorization);
     }
     this.websocketFactory = options.websocketFactory ?? defaultWebSocketFactory;
   }
@@ -387,7 +551,10 @@ var StarciteClient = class {
    * Creates a new session and returns the raw session record.
    */
   createSession(input = {}) {
-    const payload = CreateSessionInputSchema.parse(input);
+    const payload = CreateSessionInputSchema.parse({
+      ...input,
+      creator_principal: input.creator_principal ?? this.inferredCreatorPrincipal
+    });
     return this.request(
       "/sessions",
       {
@@ -452,77 +619,161 @@ var StarciteClient = class {
   /**
    * Opens a WebSocket tail stream and yields raw events.
    */
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: single-loop reconnect state machine is intentionally explicit for stream correctness.
   async *tailRawEvents(sessionId, options = {}) {
-    const queue = new AsyncQueue();
-    const cursor = options.cursor ?? 0;
-    if (!Number.isInteger(cursor) || cursor < 0) {
+    const initialCursor = options.cursor ?? 0;
+    const follow = options.follow ?? true;
+    const reconnectEnabled = follow ? options.reconnect ?? true : false;
+    const reconnectDelayMs = options.reconnectDelayMs ?? DEFAULT_TAIL_RECONNECT_DELAY_MS;
+    if (!Number.isInteger(initialCursor) || initialCursor < 0) {
       throw new StarciteError("tail() cursor must be a non-negative integer");
     }
-    const wsUrl = `${this.websocketBaseUrl}/sessions/${encodeURIComponent(
-      sessionId
-    )}/tail?cursor=${cursor}`;
-    const websocketHeaders = new Headers();
-    const authorization = this.headers.get("authorization");
-    if (authorization) {
-      websocketHeaders.set("authorization", authorization);
+    if (!Number.isFinite(reconnectDelayMs) || reconnectDelayMs < 0) {
+      throw new StarciteError(
+        "tail() reconnectDelayMs must be a non-negative number"
+      );
     }
-    const socket = this.websocketFactory(
-      wsUrl,
-      hasAnyHeaders(websocketHeaders) ? {
-        headers: websocketHeaders
-      } : void 0
-    );
-    const onMessage = (event) => {
+    let cursor = initialCursor;
+    while (true) {
+      if (options.signal?.aborted) {
+        return;
+      }
+      const wsUrl = `${this.websocketBaseUrl}/sessions/${encodeURIComponent(
+        sessionId
+      )}/tail?cursor=${cursor}`;
+      const websocketHeaders = new Headers();
+      const authorization = this.headers.get("authorization");
+      if (authorization) {
+        websocketHeaders.set("authorization", authorization);
+      }
+      let socket;
       try {
-        const parsed = parseEventFrame(getEventData(event));
-        if (options.agent && agentFromActor(parsed.actor) !== options.agent) {
-          return;
-        }
-        queue.push(parsed);
+        socket = this.websocketFactory(
+          wsUrl,
+          hasAnyHeaders(websocketHeaders) ? {
+            headers: websocketHeaders
+          } : void 0
+        );
       } catch (error) {
-        queue.fail(error);
+        const rootCause = toError(error).message;
+        if (!reconnectEnabled || options.signal?.aborted) {
+          throw new StarciteConnectionError(
+            `Tail connection failed for session '${sessionId}': ${rootCause}`
+          );
+        }
+        await waitForDelay(reconnectDelayMs, options.signal);
+        continue;
       }
-    };
-    const onError = () => {
-      queue.fail(
-        new StarciteConnectionError(
-          `Tail connection failed for session '${sessionId}'`
-        )
-      );
-    };
-    const onClose = () => {
-      queue.close();
-    };
-    socket.addEventListener("message", onMessage);
-    socket.addEventListener("error", onError);
-    socket.addEventListener("close", onClose);
-    const onAbort = () => {
-      queue.close();
-      socket.close(1e3, "aborted");
-    };
-    if (options.signal) {
-      if (options.signal.aborted) {
-        onAbort();
-      } else {
-        options.signal.addEventListener("abort", onAbort, { once: true });
+      const queue = new AsyncQueue();
+      let sawTransportError = false;
+      let closeCode;
+      let closeReason;
+      let abortRequested = false;
+      let catchUpTimer = null;
+      const resetCatchUpTimer = () => {
+        if (!follow) {
+          if (catchUpTimer) {
+            clearTimeout(catchUpTimer);
+          }
+          catchUpTimer = setTimeout(() => {
+            queue.close();
+          }, CATCH_UP_IDLE_MS);
+        }
+      };
+      const onMessage = (event) => {
+        try {
+          const parsed = parseEventFrame(getEventData(event));
+          cursor = Math.max(cursor, parsed.seq);
+          if (options.agent && agentFromActor(parsed.actor) !== options.agent) {
+            resetCatchUpTimer();
+            return;
+          }
+          queue.push(parsed);
+          resetCatchUpTimer();
+        } catch (error) {
+          queue.fail(error);
+        }
+      };
+      const onError = () => {
+        sawTransportError = true;
+        if (catchUpTimer) {
+          clearTimeout(catchUpTimer);
+        }
+        queue.close();
+      };
+      const onClose = (event) => {
+        closeCode = getCloseCode(event);
+        closeReason = getCloseReason(event);
+        if (catchUpTimer) {
+          clearTimeout(catchUpTimer);
+        }
+        queue.close();
+      };
+      const onAbort = () => {
+        abortRequested = true;
+        if (catchUpTimer) {
+          clearTimeout(catchUpTimer);
+        }
+        queue.close();
+        socket.close(NORMAL_WEBSOCKET_CLOSE_CODE, "aborted");
+      };
+      const onOpen = () => {
+        resetCatchUpTimer();
+      };
+      socket.addEventListener("open", onOpen);
+      socket.addEventListener("message", onMessage);
+      socket.addEventListener("error", onError);
+      socket.addEventListener("close", onClose);
+      if (options.signal) {
+        if (options.signal.aborted) {
+          onAbort();
+        } else {
+          options.signal.addEventListener("abort", onAbort, { once: true });
+        }
       }
-    }
-    try {
-      while (true) {
-        const next = await queue.next();
-        if (next.done) {
-          break;
+      let iterationError = null;
+      try {
+        while (true) {
+          const next = await queue.next();
+          if (next.done) {
+            break;
+          }
+          yield next.value;
+        }
+      } catch (error) {
+        iterationError = toError(error);
+      } finally {
+        if (catchUpTimer) {
+          clearTimeout(catchUpTimer);
+        }
+        socket.removeEventListener("open", onOpen);
+        socket.removeEventListener("message", onMessage);
+        socket.removeEventListener("error", onError);
+        socket.removeEventListener("close", onClose);
+        if (options.signal) {
+          options.signal.removeEventListener("abort", onAbort);
         }
-        yield next.value;
+        socket.close(NORMAL_WEBSOCKET_CLOSE_CODE, "finished");
       }
-    } finally {
-      socket.removeEventListener("message", onMessage);
-      socket.removeEventListener("error", onError);
-      socket.removeEventListener("close", onClose);
-      if (options.signal) {
-        options.signal.removeEventListener("abort", onAbort);
+      if (iterationError) {
+        throw iterationError;
+      }
+      if (abortRequested || options.signal?.aborted || !follow) {
+        return;
+      }
+      const gracefullyClosed = !sawTransportError && closeCode === NORMAL_WEBSOCKET_CLOSE_CODE;
+      if (gracefullyClosed) {
+        return;
+      }
+      if (!reconnectEnabled) {
+        throw new StarciteConnectionError(
+          `Tail connection dropped for session '${sessionId}' (${describeClose(
+            closeCode,
+            closeReason
+          )})`
+        );
       }
-      socket.close(1e3, "finished");
+      await waitForDelay(reconnectDelayMs, options.signal);
     }
   }
   /**