The Open Standard for Generative UI
Add cloud observability pkg (#950)
abhithesys44ffc981c564
diff --git a/.github/workflows/publish-npm-package.yml b/.github/workflows/publish-npm-package.ymlindex c79c08dba..bce42ebd9 100644--- a/.github/workflows/publish-npm-package.yml+++ b/.github/workflows/publish-npm-package.yml@@ -24,6 +24,7 @@ on:- vue-lang- browser-bundle- observability+ - observability-cloud- devtoolsjobs:diff --git a/packages/observability-cloud/README.md b/packages/observability-cloud/README.mdnew file mode 100644index 000000000..9092cf5bc--- /dev/null+++ b/packages/observability-cloud/README.md@@ -0,0 +1,43 @@+# @openuidev/observability-cloud++Official SDK for OpenUI observability. Sends render events from your app to the Thesys console so you can track request volume, errors and reliability.++## Install++```bash+npm i @openuidev/observability-cloud+```++## Setup++Generate a publishable API key at [console.thesys.dev/client-api-keys](https://console.thesys.dev/client-api-keys), then initialise the SDK once at your app's entry point:++```ts+import * as Observability from "@openuidev/observability-cloud";++Observability.init({ apiKey: "pk-th-…" });+```++`init` is safe to call from shared client/server code — it is a no-op when `window` is not defined.++## API reference++### `Observability.init(options)`++| option | type | default | description |+| ------------ | ----------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| `apiKey` | `string` | — | Your publishable API key (`pk-th-…`). Required. |+| `capture` | `"full"` \| `"minimal"` | `"full"` | `"full"` logs complete event data for the richest debugging in the console. `"minimal"` is a privacy-first mode that strips event data that may include PII. |+| `sampleRate` | `number` | `1` | Fraction of renders to send, `0`–`1`. Sampling is deterministic per render, so all events for one render are kept or dropped together. |+| `endpoint` | `string` | `https://ingest.thesys.dev/v1/events` | Override the ingest URL (testing). |+| `debug` | `boolean` | `false` | Log SDK diagnostics to the console. |++Calling `init` again with the same options is a no-op; calling it with different options replaces the previous configuration.++### `Observability.flush(timeoutMs?)`++Events are batched and sent in the background. Call `flush` to send everything queued now — for example before a hard navigation. Resolves to `true` once the batch is accepted, or `false` if it could not be sent within `timeoutMs` (default 10 s).++### `Observability.close()`++Flushes queued events and stops sending. Call `init` again to resume.diff --git a/packages/observability-cloud/eslint.config.cjs b/packages/observability-cloud/eslint.config.cjsnew file mode 100644index 000000000..413c49627--- /dev/null+++ b/packages/observability-cloud/eslint.config.cjs@@ -0,0 +1,73 @@+const tseslint = require("@typescript-eslint/eslint-plugin");+const typescript = require("@typescript-eslint/parser");+const prettier = require("eslint-config-prettier");+const unusedImports = require("eslint-plugin-unused-imports");+const eslintPluginPrettier = require("eslint-plugin-prettier");++module.exports = [+ {+ files: ["**/__tests__/**/*.{ts,tsx}", "**/*.test.{ts,tsx}", "**/*.spec.{ts,tsx}"],+ languageOptions: {+ parser: typescript,+ parserOptions: {+ project: "./tsconfig.test.json",+ sourceType: "module",+ },+ },+ },+ {+ files: ["**/*.{ts,tsx}"],+ ignores: [+ "**/*.stories.tsx",+ "**/__tests__/**/*.{ts,tsx}",+ "**/*.test.{ts,tsx}",+ "**/*.spec.{ts,tsx}",+ "*.config.ts",+ ],+ languageOptions: {+ parser: typescript,+ parserOptions: {+ project: "./tsconfig.json",+ sourceType: "module",+ },+ },+ plugins: {+ "@typescript-eslint": tseslint,+ "unused-imports": unusedImports,+ prettier: eslintPluginPrettier,+ },+ rules: {+ "@typescript-eslint/interface-name-prefix": "off",+ "@typescript-eslint/explicit-function-return-type": "off",+ "@typescript-eslint/explicit-module-boundary-types": "off",+ "@typescript-eslint/no-explicit-any": "off",+ "no-undefined": "off",+ "@typescript-eslint/no-unused-vars": [+ "error",+ {+ vars: "all",+ varsIgnorePattern: "^_",+ args: "after-used",+ argsIgnorePattern: "^_",+ },+ ],+ "@typescript-eslint/no-use-before-define": [+ "error",+ {+ functions: false,+ classes: false,+ variables: false,+ },+ ],+ "unused-imports/no-unused-imports": "error",+ "no-console": [+ "error",+ {+ allow: ["error", "warn", "info"],+ },+ ],+ ...eslintPluginPrettier.configs.recommended.rules,+ },+ },+ prettier,+];diff --git a/packages/observability-cloud/package.json b/packages/observability-cloud/package.jsonnew file mode 100644index 000000000..f7baa584e--- /dev/null+++ b/packages/observability-cloud/package.json@@ -0,0 +1,66 @@+{+ "name": "@openuidev/observability-cloud",+ "version": "0.0.1",+ "description": "Cloud sink for @openuidev/observability: batches OpenUI events and ships them to Thesys ingest",+ "license": "MIT",+ "type": "module",+ "main": "dist/index.cjs",+ "module": "dist/index.mjs",+ "types": "dist/index.d.cts",+ "sideEffects": false,+ "files": [+ "dist",+ "README.md"+ ],+ "exports": {+ ".": {+ "import": {+ "types": "./dist/index.d.mts",+ "default": "./dist/index.mjs"+ },+ "require": {+ "types": "./dist/index.d.cts",+ "default": "./dist/index.cjs"+ }+ }+ },+ "scripts": {+ "test": "vitest run --passWithNoTests",+ "build": "tsdown",+ "watch": "tsdown --watch",+ "typecheck": "tsc --noEmit",+ "lint:check": "eslint ./src",+ "lint:fix": "eslint ./src --fix",+ "format:fix": "prettier --write ./src",+ "format:check": "prettier --check ./src",+ "check:publint": "publint",+ "check:attw": "attw --pack .",+ "prepare": "pnpm run build",+ "prepublishOnly": "pnpm run check:publint && pnpm run check:attw",+ "ci": "pnpm run lint:check && pnpm run format:check"+ },+ "keywords": [+ "openui",+ "observability",+ "telemetry",+ "ingest",+ "errors"+ ],+ "homepage": "https://openui.com",+ "repository": {+ "type": "git",+ "url": "https://github.com/thesysdev/openui.git",+ "directory": "packages/observability-cloud"+ },+ "bugs": {+ "url": "https://github.com/thesysdev/openui/issues"+ },+ "author": "[email protected]",+ "dependencies": {+ "@openuidev/observability": "workspace:^"+ },+ "devDependencies": {+ "jsdom": "catalog:",+ "vitest": "^4.1.0"+ }+}diff --git a/packages/observability-cloud/src/core/batcher.test.ts b/packages/observability-cloud/src/core/batcher.test.tsnew file mode 100644index 000000000..71585c65b--- /dev/null+++ b/packages/observability-cloud/src/core/batcher.test.ts@@ -0,0 +1,236 @@+// @vitest-environment jsdom+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { Batcher } from "./batcher";+import * as transport from "./transport";+import type { WireEvent } from "./wire";++const transportConfig = {+ endpoint: "https://ingest.example.com/v1/events",+ apiKey: "test-key",+ debug: false,+ capture: "full" as const,+};++function wireEvent(index: number): WireEvent {+ return {+ id: `event-${index}`,+ kind: "react-lang:stream",+ level: "info",+ timestamp: index,+ updateIndex: index,+ errorCount: 0,+ };+}++describe("Batcher", () => {+ beforeEach(() => {+ vi.spyOn(transport, "sendEnvelope").mockResolvedValue(true);+ vi.spyOn(transport, "sendEnvelopeBeacon").mockImplementation(() => {});+ });++ afterEach(() => {+ vi.useRealTimers();+ vi.restoreAllMocks();+ });++ it("flushes on interval when the queue is non-empty", async () => {+ vi.useFakeTimers();+ const batcher = new Batcher(transportConfig);+ batcher.enqueue(wireEvent(1));++ await vi.advanceTimersByTimeAsync(5000);++ expect(transport.sendEnvelope).toHaveBeenCalledTimes(1);+ await batcher.close();+ });++ it("flushes when the queue reaches 50 events", async () => {+ const batcher = new Batcher(transportConfig);+ for (let index = 0; index < 50; index++) {+ batcher.enqueue(wireEvent(index));+ }++ await Promise.resolve();+ expect(transport.sendEnvelope).toHaveBeenCalledTimes(1);+ const envelope = vi.mocked(transport.sendEnvelope).mock.calls[0]?.[0];+ expect(envelope?.events).toHaveLength(50);+ expect(envelope?.capture).toBe("full");+ await batcher.close();+ });++ it("stamps the client's capture mode on every envelope", async () => {+ const batcher = new Batcher({ ...transportConfig, capture: "minimal" });+ batcher.enqueue(wireEvent(0));+ await batcher.flush();+ const envelope = vi.mocked(transport.sendEnvelope).mock.calls[0]?.[0];+ expect(envelope?.capture).toBe("minimal");+ await batcher.close();+ });++ it("explicit flush resolves true when transport accepts every batch", async () => {+ const batcher = new Batcher(transportConfig);+ batcher.enqueue(wireEvent(1));+ batcher.enqueue(wireEvent(2));++ await expect(batcher.flush()).resolves.toBe(true);+ expect(transport.sendEnvelope).toHaveBeenCalledTimes(1);+ await batcher.close();+ });++ it("explicit flush resolves false when transport drops a batch", async () => {+ vi.mocked(transport.sendEnvelope).mockResolvedValue(false);+ const batcher = new Batcher(transportConfig);+ batcher.enqueue(wireEvent(1));++ await expect(batcher.flush()).resolves.toBe(false);+ await batcher.close();+ });++ it("close resolves false when transport drops during final flush", async () => {+ vi.mocked(transport.sendEnvelope).mockResolvedValue(false);+ const batcher = new Batcher(transportConfig);+ batcher.enqueue(wireEvent(1));++ await expect(batcher.close()).resolves.toBe(false);+ });++ it("flush resolves false within timeoutMs while send is in retry backoff", async () => {+ vi.useFakeTimers();+ vi.restoreAllMocks();+ vi.spyOn(transport, "sendEnvelopeBeacon").mockImplementation(() => {});++ const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 500 }));+ vi.stubGlobal("fetch", fetchMock);++ const batcher = new Batcher(transportConfig);+ batcher.enqueue(wireEvent(1));++ const flushPromise = batcher.flush(100);+ await vi.advanceTimersByTimeAsync(100);++ await expect(flushPromise).resolves.toBe(false);+ await vi.runAllTimersAsync();+ await batcher.close();+ });++ it("stamps droppedEvents from queue overflow on the next envelope", async () => {+ const flushSpy = vi.spyOn(Batcher.prototype, "flushNextBatch").mockResolvedValue({+ accepted: true,+ timedOut: false,+ });+ const batcher = new Batcher(transportConfig);++ for (let index = 0; index < 501; index++) {+ batcher.enqueue(wireEvent(index));+ }++ flushSpy.mockRestore();+ await batcher.flush();++ const envelopes = vi.mocked(transport.sendEnvelope).mock.calls.map(([payload]) => payload);+ expect(envelopes.some((payload) => payload.droppedEvents === 1)).toBe(true);+ await batcher.close();+ });++ it("flush awaits a threshold-initiated in-flight send and reflects its failure", async () => {+ let resolveSend!: (accepted: boolean) => void;+ vi.mocked(transport.sendEnvelope).mockImplementation(+ () => new Promise<boolean>((resolve) => (resolveSend = resolve)),+ );+ const batcher = new Batcher(transportConfig);+ for (let index = 0; index < 50; index++) {+ batcher.enqueue(wireEvent(index));+ }+ expect(transport.sendEnvelope).toHaveBeenCalledTimes(1);++ let settled = false;+ const flushPromise = batcher.flush();+ void flushPromise.then(() => {+ settled = true;+ });+ await Promise.resolve();+ await Promise.resolve();+ expect(settled).toBe(false);++ resolveSend(false);+ await expect(flushPromise).resolves.toBe(false);+ vi.mocked(transport.sendEnvelope).mockResolvedValue(true);+ await batcher.close();+ });++ it("flush resolves false within timeoutMs when the in-flight send is stuck", async () => {+ vi.useFakeTimers();+ vi.mocked(transport.sendEnvelope).mockImplementation(() => new Promise<boolean>(() => {}));+ const batcher = new Batcher(transportConfig);+ for (let index = 0; index < 50; index++) {+ batcher.enqueue(wireEvent(index));+ }++ const flushPromise = batcher.flush(100);+ await vi.advanceTimersByTimeAsync(100);+ await expect(flushPromise).resolves.toBe(false);++ const closePromise = batcher.close();+ await vi.runAllTimersAsync();+ await expect(closePromise).resolves.toBe(false);+ });++ it("stamps droppedEvents from a transport-dropped batch on the next accepted envelope", async () => {+ vi.mocked(transport.sendEnvelope).mockResolvedValueOnce(false);+ const batcher = new Batcher(transportConfig);+ batcher.enqueue(wireEvent(1));+ batcher.enqueue(wireEvent(2));+ await expect(batcher.flush()).resolves.toBe(false);++ batcher.enqueue(wireEvent(3));+ await expect(batcher.flush()).resolves.toBe(true);++ const envelopes = vi.mocked(transport.sendEnvelope).mock.calls.map(([payload]) => payload);+ expect(envelopes[0]?.droppedEvents).toBeUndefined();+ expect(envelopes[1]?.droppedEvents).toBe(2);+ await batcher.close();+ });++ it("re-stamps queue-overflow drops carried by a failed envelope on the next accepted one", async () => {+ const flushSpy = vi.spyOn(Batcher.prototype, "flushNextBatch").mockResolvedValue({+ accepted: true,+ timedOut: false,+ });+ const batcher = new Batcher(transportConfig);+ for (let index = 0; index < 501; index++) {+ batcher.enqueue(wireEvent(index));+ }+ flushSpy.mockRestore();++ vi.mocked(transport.sendEnvelope).mockResolvedValueOnce(false);+ await expect(batcher.flush()).resolves.toBe(false);++ const envelopes = vi.mocked(transport.sendEnvelope).mock.calls.map(([payload]) => payload);+ expect(envelopes[0]?.droppedEvents).toBe(1);+ expect(envelopes[1]?.droppedEvents).toBe(51);+ await batcher.close();+ });++ it("pagehide flushes through the beacon path", () => {+ const batcher = new Batcher(transportConfig);+ batcher.enqueue(wireEvent(1));++ window.dispatchEvent(new Event("pagehide"));++ expect(transport.sendEnvelopeBeacon).toHaveBeenCalledTimes(1);+ expect(transport.sendEnvelope).not.toHaveBeenCalled();+ });++ it("visibilitychange to hidden flushes through the beacon path", () => {+ const batcher = new Batcher(transportConfig);+ batcher.enqueue(wireEvent(1));++ Object.defineProperty(document, "visibilityState", {+ configurable: true,+ get: () => "hidden",+ });+ document.dispatchEvent(new Event("visibilitychange"));++ expect(transport.sendEnvelopeBeacon).toHaveBeenCalledTimes(1);+ });+});diff --git a/packages/observability-cloud/src/core/batcher.ts b/packages/observability-cloud/src/core/batcher.tsnew file mode 100644index 000000000..3165fadc6--- /dev/null+++ b/packages/observability-cloud/src/core/batcher.ts@@ -0,0 +1,197 @@+import { EventQueue } from "./queue";+import { sendEnvelope, sendEnvelopeBeacon, type TransportConfig } from "./transport";+import { SDK_VERSION, type WireEnvelope, type WireEvent } from "./wire";++const FLUSH_INTERVAL_MS = 5000;+const BATCH_SIZE = 50;+const DEFAULT_FLUSH_TIMEOUT_MS = 10_000;++function buildEnvelope(+ events: WireEvent[],+ droppedEvents: number,+ capture: "full" | "minimal",+): WireEnvelope {+ return {+ v: 1,+ sentAt: Date.now(),+ sdk: { name: "observability-cloud", version: SDK_VERSION },+ capture,+ ...(droppedEvents > 0 ? { droppedEvents } : {}),+ events,+ };+}++export interface BatcherOptions extends TransportConfig {+ capture: "full" | "minimal";+}++type BatchSendResult = { accepted: boolean; timedOut: boolean };++export class Batcher {+ private readonly queue = new EventQueue();+ private readonly inFlight = new Set<Promise<BatchSendResult>>();+ private droppedEvents = 0;+ private intervalId: ReturnType<typeof setInterval> | null = null;+ private closed = false;+ private readonly onPageHide: () => void;+ private readonly onVisibilityChange: () => void;++ private readonly transport: TransportConfig;+ private readonly capture: "full" | "minimal";++ constructor(options: BatcherOptions) {+ this.transport = { endpoint: options.endpoint, apiKey: options.apiKey, debug: options.debug };+ this.capture = options.capture;+ this.onPageHide = () => {+ this.flushBeaconSync();+ };+ this.onVisibilityChange = () => {+ if (document.visibilityState === "hidden") {+ this.flushBeaconSync();+ }+ };++ if (typeof window !== "undefined" && typeof document !== "undefined") {+ window.addEventListener("pagehide", this.onPageHide);+ document.addEventListener("visibilitychange", this.onVisibilityChange);+ }+ }++ enqueue(event: WireEvent): void {+ if (this.closed) return;+ this.queue.enqueue(event);+ if (this.queue.size >= BATCH_SIZE) {+ void this.flushNextBatch();+ }+ this.ensureInterval();+ }++ async flush(timeoutMs = DEFAULT_FLUSH_TIMEOUT_MS): Promise<boolean> {+ if (this.closed && this.queue.size === 0 && this.inFlight.size === 0) return true;++ const deadline = Date.now() + timeoutMs;+ let allAccepted = true;++ while (this.queue.size > 0) {+ if (Date.now() >= deadline) return false;++ const result = await this.flushNextBatch(deadline);+ if (result.timedOut) return false;+ if (!result.accepted) allAccepted = false;+ }++ while (this.inFlight.size > 0) {+ if (Date.now() >= deadline) return false;++ const pending = Promise.all([...this.inFlight]).then((results): BatchSendResult => ({+ accepted: results.every((result) => result.accepted),+ timedOut: false,+ }));+ const result = await this.raceDeadline(pending, deadline);+ if (result.timedOut) return false;+ if (!result.accepted) allAccepted = false;+ }++ this.stopInterval();+ return allAccepted;+ }++ close(): Promise<boolean> {+ this.closed = true;+ this.detachPageListeners();+ this.stopInterval();+ return this.flush();+ }++ private ensureInterval(): void {+ if (this.intervalId !== null || this.closed) return;+ this.intervalId = setInterval(() => {+ if (this.queue.size === 0) {+ this.stopInterval();+ return;+ }+ void this.flushNextBatch();+ }, FLUSH_INTERVAL_MS);+ }++ private stopInterval(): void {+ if (this.intervalId === null) return;+ clearInterval(this.intervalId);+ this.intervalId = null;+ }++ private detachPageListeners(): void {+ if (typeof window === "undefined" || typeof document === "undefined") return;+ window.removeEventListener("pagehide", this.onPageHide);+ document.removeEventListener("visibilitychange", this.onVisibilityChange);+ }++ private flushBeaconSync(): void {+ while (this.queue.size > 0) {+ const droppedEvents = this.takeDroppedEvents();+ const events = this.queue.drain(BATCH_SIZE);+ if (events.length === 0) break;+ sendEnvelopeBeacon(buildEnvelope(events, droppedEvents, this.capture), this.transport);+ }+ this.stopInterval();+ }++ private takeDroppedEvents(): number {+ const count = this.droppedEvents + this.queue.readAndResetDropped();+ this.droppedEvents = 0;+ return count;+ }++ private async flushNextBatch(deadline?: number): Promise<BatchSendResult> {+ if (this.queue.size === 0) return { accepted: true, timedOut: false };++ const droppedEvents = this.takeDroppedEvents();+ const events = this.queue.drain(BATCH_SIZE);+ if (events.length === 0) {+ this.droppedEvents += droppedEvents;+ return { accepted: true, timedOut: false };+ }++ const sendPromise = sendEnvelope(+ buildEnvelope(events, droppedEvents, this.capture),+ this.transport,+ )+ .catch(() => false)+ .then((accepted): BatchSendResult => {+ if (!accepted) this.droppedEvents += events.length + droppedEvents;+ return { accepted, timedOut: false };+ });++ this.inFlight.add(sendPromise);+ void sendPromise.then(() => {+ this.inFlight.delete(sendPromise);+ });++ return this.raceDeadline(sendPromise, deadline);+ }++ private async raceDeadline(+ sendPromise: Promise<BatchSendResult>,+ deadline?: number,+ ): Promise<BatchSendResult> {+ if (deadline === undefined) {+ return sendPromise;+ }++ const remainingMs = deadline - Date.now();+ if (remainingMs <= 0) {+ return { accepted: false, timedOut: true };+ }++ let timeoutId: ReturnType<typeof setTimeout> | undefined;+ const timeoutPromise = new Promise<BatchSendResult>((resolve) => {+ timeoutId = setTimeout(() => resolve({ accepted: false, timedOut: true }), remainingMs);+ });++ try {+ return await Promise.race([sendPromise, timeoutPromise]);+ } finally {+ if (timeoutId !== undefined) clearTimeout(timeoutId);+ }+ }+}diff --git a/packages/observability-cloud/src/core/client.test.ts b/packages/observability-cloud/src/core/client.test.tsnew file mode 100644index 000000000..1ab295fad--- /dev/null+++ b/packages/observability-cloud/src/core/client.test.ts@@ -0,0 +1,60 @@+// @vitest-environment jsdom+import type { Observability, ObservabilityEvent } from "@openuidev/observability";+import { afterEach, describe, expect, it, vi } from "vitest";+import { CloudObservabilityClient } from "./client";+import * as transport from "./transport";++function createFakeBus() {+ const handlers: Array<(event: ObservabilityEvent) => void> = [];+ const remove = vi.fn();+ const bus = {+ listenAll: (handler: (event: ObservabilityEvent) => void) => {+ handlers.push(handler);+ return remove;+ },+ } as unknown as Observability;+ return { bus, handlers, remove };+}++const options = {+ endpoint: "https://ingest.example.com/v1/events",+ apiKey: "test-key",+ capture: "full" as const,+ sampleRate: 1,+ debug: false,+};++afterEach(() => {+ vi.restoreAllMocks();+});++describe("CloudObservabilityClient bus injection", () => {+ it("listens on the injected bus and detaches on close", async () => {+ vi.spyOn(transport, "sendEnvelope").mockResolvedValue(true);+ const { bus, handlers, remove } = createFakeBus();++ const client = new CloudObservabilityClient(options, bus);+ expect(handlers).toHaveLength(1);++ handlers[0]!({+ level: "info",+ timestamp: 1_700_000_000_000,+ detail: {+ id: "stream-1",+ kind: "react-lang:stream",+ phase: "settled",+ updateIndex: 1,+ errorCount: 0,+ },+ });++ await client.flush();+ expect(transport.sendEnvelope).toHaveBeenCalledTimes(1);+ expect(vi.mocked(transport.sendEnvelope).mock.calls[0]?.[0]?.events).toEqual([+ expect.objectContaining({ id: "stream-1", kind: "react-lang:stream" }),+ ]);++ await client.close();+ expect(remove).toHaveBeenCalledOnce();+ });+});diff --git a/packages/observability-cloud/src/core/client.ts b/packages/observability-cloud/src/core/client.tsnew file mode 100644index 000000000..591cf5de6--- /dev/null+++ b/packages/observability-cloud/src/core/client.ts@@ -0,0 +1,40 @@+import { observability, type Observability, type Remove } from "@openuidev/observability";+import { Batcher } from "./batcher";+import { selectEvent, type SelectorOptions } from "./selector";+import type { TransportConfig } from "./transport";++export interface CloudClientOptions extends SelectorOptions, TransportConfig {}++export class CloudObservabilityClient {+ private readonly removeListener: Remove;+ private readonly batcher: Batcher;++ constructor(options: CloudClientOptions, bus: Observability = observability) {+ this.batcher = new Batcher({+ endpoint: options.endpoint,+ apiKey: options.apiKey,+ debug: options.debug,+ capture: options.capture,+ });++ this.removeListener = bus.listenAll((event) => {+ try {+ const wireEvent = selectEvent(event, options);+ if (wireEvent) this.batcher.enqueue(wireEvent);+ } catch (error) {+ if (options.debug) {+ console.warn("[@openuidev/observability-cloud]", "listener threw; dropping event", error);+ }+ }+ });+ }++ flush(timeoutMs?: number): Promise<boolean> {+ return this.batcher.flush(timeoutMs);+ }++ close(): Promise<boolean> {+ this.removeListener();+ return this.batcher.close();+ }+}diff --git a/packages/observability-cloud/src/core/queue.test.ts b/packages/observability-cloud/src/core/queue.test.tsnew file mode 100644index 000000000..f682fef02--- /dev/null+++ b/packages/observability-cloud/src/core/queue.test.ts@@ -0,0 +1,38 @@+import { describe, expect, it } from "vitest";+import { EventQueue } from "./queue";+import type { WireEvent } from "./wire";++function wireEvent(id: string): WireEvent {+ return {+ id,+ kind: "react-lang:stream",+ level: "info",+ timestamp: 1,+ updateIndex: 1,+ errorCount: 0,+ };+}++describe("EventQueue", () => {+ it("preserves FIFO order", () => {+ const queue = new EventQueue(10);+ queue.enqueue(wireEvent("a"));+ queue.enqueue(wireEvent("b"));+ queue.enqueue(wireEvent("c"));++ expect(queue.drain(2).map((event) => event.id)).toEqual(["a", "b"]);+ expect(queue.drain(10).map((event) => event.id)).toEqual(["c"]);+ });++ it("drops the oldest event on overflow and counts drops", () => {+ const queue = new EventQueue(2);+ queue.enqueue(wireEvent("a"));+ queue.enqueue(wireEvent("b"));+ queue.enqueue(wireEvent("c"));++ expect(queue.size).toBe(2);+ expect(queue.drain(10).map((event) => event.id)).toEqual(["b", "c"]);+ expect(queue.readAndResetDropped()).toBe(1);+ expect(queue.readAndResetDropped()).toBe(0);+ });+});diff --git a/packages/observability-cloud/src/core/queue.ts b/packages/observability-cloud/src/core/queue.tsnew file mode 100644index 000000000..258a6f385--- /dev/null+++ b/packages/observability-cloud/src/core/queue.ts@@ -0,0 +1,35 @@+import type { WireEvent } from "./wire";++const DEFAULT_CAPACITY = 500;++export class EventQueue {+ private readonly items: WireEvent[] = [];+ private dropped = 0;++ constructor(private readonly capacity = DEFAULT_CAPACITY) {}++ get size(): number {+ return this.items.length;+ }++ enqueue(event: WireEvent): void {+ if (this.items.length >= this.capacity) {+ this.items.shift();+ this.dropped += 1;+ }+ this.items.push(event);+ }++ /** Removes and returns up to `limit` events in FIFO order. */+ drain(limit: number): WireEvent[] {+ if (limit <= 0 || this.items.length === 0) return [];+ return this.items.splice(0, Math.min(limit, this.items.length));+ }++ /** Returns the overflow drop count since the last read and resets it to zero. */+ readAndResetDropped(): number {+ const count = this.dropped;+ this.dropped = 0;+ return count;+ }+}diff --git a/packages/observability-cloud/src/core/selector.test.ts b/packages/observability-cloud/src/core/selector.test.tsnew file mode 100644index 000000000..816c7a0e4--- /dev/null+++ b/packages/observability-cloud/src/core/selector.test.ts@@ -0,0 +1,83 @@+import type { ObservabilityEvent } from "@openuidev/observability";+import { describe, expect, it, vi } from "vitest";+import { selectEvent } from "./selector";++function settledEvent(overrides: Record<string, unknown> = {}): ObservabilityEvent {+ return {+ level: "info",+ timestamp: 1_700_000_000_000,+ detail: {+ id: "stream-1",+ kind: "react-lang:stream",+ phase: "settled",+ updateIndex: 2,+ errorCount: 0,+ response: "hello",+ message: "OpenUI Lang settled",+ errors: [],+ parser: {+ incomplete: false,+ unresolved: [],+ orphaned: [],+ statementCount: 1,+ },+ ...overrides,+ },+ };+}++describe("selectEvent", () => {+ it("samples deterministically per id and respects rate 0 and 1", () => {+ const id = "deterministic-id-a";+ const options = { capture: "full" as const, sampleRate: 0.5, debug: false };++ const first = selectEvent(settledEvent({ id }), options);+ const second = selectEvent(settledEvent({ id }), options);+ expect(Boolean(first)).toBe(Boolean(second));++ const decisions = Array.from({ length: 100 }, (_, index) =>+ Boolean(selectEvent(settledEvent({ id: `sample-id-${index}` }), options)),+ );+ expect(decisions.some(Boolean)).toBe(true);+ expect(decisions.some((kept) => !kept)).toBe(true);++ expect(selectEvent(settledEvent({ id }), { ...options, sampleRate: 1 })).not.toBeNull();+ expect(selectEvent(settledEvent({ id }), { ...options, sampleRate: 0 })).toBeNull();+ });++ it("beforeSend can mutate or drop events", () => {+ const mutated = selectEvent(settledEvent(), {+ capture: "full",+ sampleRate: 1,+ debug: false,+ beforeSend: (event) => ({ ...event, message: "mutated" }),+ });+ const dropped = selectEvent(settledEvent(), {+ capture: "full",+ sampleRate: 1,+ debug: false,+ beforeSend: () => null,+ });++ expect(mutated?.message).toBe("mutated");+ expect(dropped).toBeNull();+ });++ it("drops when beforeSend throws without propagating", () => {+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});++ expect(+ selectEvent(settledEvent(), {+ capture: "full",+ sampleRate: 1,+ debug: true,+ beforeSend: () => {+ throw new Error("boom");+ },+ }),+ ).toBeNull();++ expect(warn).toHaveBeenCalled();+ warn.mockRestore();+ });+});diff --git a/packages/observability-cloud/src/core/selector.ts b/packages/observability-cloud/src/core/selector.tsnew file mode 100644index 000000000..16b7e71a9--- /dev/null+++ b/packages/observability-cloud/src/core/selector.ts@@ -0,0 +1,61 @@+import type { ObservabilityEvent } from "@openuidev/observability";+import { selectStreamEvent } from "../events/stream";+import type { WireEvent } from "./wire";++export interface SelectorOptions {+ capture: "full" | "minimal";+ sampleRate: number;+ beforeSend?: (event: WireEvent) => WireEvent | null;+ debug: boolean;+}++/** Kind-specific selectors. Add a new event by appending its select* function. */+const eventSelectors = [selectStreamEvent] as const;++function hashToUnitInterval(input: string): number {+ let hash = 2166136261;+ for (let i = 0; i < input.length; i++) {+ hash ^= input.charCodeAt(i);+ hash = Math.imul(hash, 16777619);+ }+ return (hash >>> 0) / 4294967296;+}++function debugWarn(debug: boolean, message: string, error?: unknown): void {+ if (!debug) return;+ if (error === undefined) {+ console.warn("[@openuidev/observability-cloud]", message);+ return;+ }+ console.warn("[@openuidev/observability-cloud]", message, error);+}++function shapeEvent(+ event: ObservabilityEvent,+ capture: SelectorOptions["capture"],+): WireEvent | null {+ for (const select of eventSelectors) {+ const shaped = select(event, capture);+ if (shaped) return shaped;+ }+ return null;+}++/** Shared pipeline: kind-specific selection, then sampling and beforeSend. */+export function selectEvent(event: ObservabilityEvent, options: SelectorOptions): WireEvent | null {+ const shaped = shapeEvent(event, options.capture);+ if (!shaped) return null;++ if (options.sampleRate < 1 && hashToUnitInterval(shaped.id) >= options.sampleRate) {+ return null;+ }++ if (!options.beforeSend) return shaped;++ try {+ return options.beforeSend(shaped);+ } catch (error) {+ debugWarn(options.debug, "beforeSend threw; dropping event", error);+ return null;+ }+}diff --git a/packages/observability-cloud/src/core/transport.test.ts b/packages/observability-cloud/src/core/transport.test.tsnew file mode 100644index 000000000..8086ad802--- /dev/null+++ b/packages/observability-cloud/src/core/transport.test.ts@@ -0,0 +1,149 @@+import { afterEach, describe, expect, it, vi } from "vitest";+import { sendEnvelope, sendEnvelopeBeacon } from "./transport";+import { SDK_VERSION, type WireEnvelope } from "./wire";++const config = {+ endpoint: "https://ingest.example.com/v1/events",+ apiKey: "test-key",+ debug: false,+};++function envelope(events = 1): WireEnvelope {+ return {+ v: 1,+ sentAt: Date.now(),+ sdk: { name: "observability-cloud", version: SDK_VERSION },+ capture: "full",+ events: Array.from({ length: events }, (_, index) => ({+ id: `event-${index}`,+ kind: "react-lang:stream" as const,+ level: "info" as const,+ timestamp: 1,+ updateIndex: 1,+ errorCount: 0,+ })),+ };+}++afterEach(() => {+ vi.unstubAllGlobals();+ vi.restoreAllMocks();+});++describe("sendEnvelope", () => {+ it("sends the expected envelope shape with auth header", async () => {+ const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 200 }));+ vi.stubGlobal("fetch", fetchMock);++ const payload = envelope(2);+ await expect(sendEnvelope(payload, config)).resolves.toBe(true);++ expect(fetchMock).toHaveBeenCalledTimes(1);+ const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];+ expect(url).toBe(config.endpoint);+ expect(init.method).toBe("POST");+ expect(init.keepalive).toBe(true);+ expect(init.headers).toMatchObject({+ "content-type": "application/json",+ authorization: "Bearer test-key",+ });+ expect(JSON.parse(String(init.body))).toEqual(payload);+ });++ it("retries 5xx responses then drops", async () => {+ vi.useFakeTimers();+ const fetchMock = vi+ .fn()+ .mockResolvedValueOnce(new Response(null, { status: 500 }))+ .mockResolvedValueOnce(new Response(null, { status: 502 }))+ .mockResolvedValueOnce(new Response(null, { status: 503 }));+ vi.stubGlobal("fetch", fetchMock);++ const promise = sendEnvelope(envelope(), config);+ await vi.runAllTimersAsync();+ await expect(promise).resolves.toBe(false);+ expect(fetchMock).toHaveBeenCalledTimes(3);+ vi.useRealTimers();+ });++ it("drops 4xx responses without retry", async () => {+ const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 400 }));+ vi.stubGlobal("fetch", fetchMock);++ await expect(sendEnvelope(envelope(), config)).resolves.toBe(false);+ expect(fetchMock).toHaveBeenCalledTimes(1);+ });++ it("retries 429 responses", async () => {+ vi.useFakeTimers();+ const fetchMock = vi+ .fn()+ .mockResolvedValueOnce(+ new Response(null, {+ status: 429,+ headers: { "Retry-After": "1" },+ }),+ )+ .mockResolvedValue(new Response(null, { status: 200 }));+ vi.stubGlobal("fetch", fetchMock);++ const promise = sendEnvelope(envelope(), config);+ await vi.runAllTimersAsync();+ await expect(promise).resolves.toBe(true);+ expect(fetchMock).toHaveBeenCalledTimes(2);+ vi.useRealTimers();+ });++ it("retries network errors", async () => {+ vi.useFakeTimers();+ const fetchMock = vi+ .fn()+ .mockRejectedValueOnce(new Error("offline"))+ .mockResolvedValue(new Response(null, { status: 200 }));+ vi.stubGlobal("fetch", fetchMock);++ const promise = sendEnvelope(envelope(), config);+ await vi.runAllTimersAsync();+ await expect(promise).resolves.toBe(true);+ expect(fetchMock).toHaveBeenCalledTimes(2);+ vi.useRealTimers();+ });+});++describe("sendEnvelopeBeacon", () => {+ it("appends apiKey as a query param when sendBeacon succeeds", () => {+ const sendBeacon = vi.fn().mockReturnValue(true);+ vi.stubGlobal("navigator", { sendBeacon });++ sendEnvelopeBeacon(envelope(), config);++ expect(sendBeacon).toHaveBeenCalledTimes(1);+ const [url] = sendBeacon.mock.calls[0] as [string, Blob];+ expect(url).toContain("apiKey=test-key");+ });++ it("falls back to fetch keepalive when sendBeacon returns false", () => {+ const sendBeacon = vi.fn().mockReturnValue(false);+ const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 200 }));+ vi.stubGlobal("navigator", { sendBeacon });+ vi.stubGlobal("fetch", fetchMock);++ sendEnvelopeBeacon(envelope(), config);++ expect(fetchMock).toHaveBeenCalledTimes(1);+ const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];+ expect(url).toContain("apiKey=test-key");+ expect(init.keepalive).toBe(true);+ });++ it("falls back to fetch keepalive when sendBeacon is unavailable", () => {+ const fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 200 }));+ vi.stubGlobal("navigator", {});+ vi.stubGlobal("fetch", fetchMock);++ sendEnvelopeBeacon(envelope(), config);++ expect(fetchMock).toHaveBeenCalledTimes(1);+ expect(fetchMock.mock.calls[0]?.[0]).toContain("apiKey=test-key");+ });+});diff --git a/packages/observability-cloud/src/core/transport.ts b/packages/observability-cloud/src/core/transport.tsnew file mode 100644index 000000000..243232c6f--- /dev/null+++ b/packages/observability-cloud/src/core/transport.ts@@ -0,0 +1,131 @@+import type { WireEnvelope } from "./wire";++const MAX_BACKOFF_MS = 5000;+const BACKOFF_MS = [500, 2000] as const;++export interface TransportConfig {+ endpoint: string;+ apiKey: string;+ debug: boolean;+}++function debugLog(debug: boolean, message: string, detail?: unknown): void {+ if (!debug) return;+ // eslint-disable-next-line no-console -- gated debug diagnostics for cloud sink+ if (detail === undefined) console.debug("[@openuidev/observability-cloud]", message);+ // eslint-disable-next-line no-console -- gated debug diagnostics for cloud sink+ else console.debug("[@openuidev/observability-cloud]", message, detail);+}++function sleep(ms: number): Promise<void> {+ return new Promise((resolve) => setTimeout(resolve, ms));+}++function beaconUrl(endpoint: string, apiKey: string): string {+ const url = new URL(endpoint);+ url.searchParams.set("apiKey", apiKey);+ return url.toString();+}++function envelopeBody(envelope: WireEnvelope): string {+ return JSON.stringify(envelope);+}++function retryAfterMs(response: Response): number {+ // Retry-After may also be an HTTP-date; parseInt fails on those, which+ // intentionally falls through to the default backoff.+ const header = response.headers.get("Retry-After");+ if (!header) return BACKOFF_MS[0];+ const seconds = Number.parseInt(header, 10);+ if (!Number.isFinite(seconds) || seconds <= 0) return BACKOFF_MS[0];+ return Math.min(seconds * 1000, MAX_BACKOFF_MS);+}++async function postEnvelope(+ envelope: WireEnvelope,+ config: TransportConfig,+ attempt: number,+): Promise<{ ok: true } | { ok: false; retryable: boolean; retryDelayMs: number }> {+ try {+ const response = await fetch(config.endpoint, {+ method: "POST",+ headers: {+ "content-type": "application/json",+ authorization: `Bearer ${config.apiKey}`,+ },+ body: envelopeBody(envelope),+ keepalive: true,+ });++ if (response.ok) return { ok: true };++ if (response.status === 429) {+ return {+ ok: false,+ retryable: true,+ retryDelayMs: retryAfterMs(response),+ };+ }++ if (response.status >= 400 && response.status < 500) {+ debugLog(config.debug, `Dropped batch after HTTP ${response.status} (non-retryable)`);+ return { ok: false, retryable: false, retryDelayMs: 0 };+ }++ debugLog(config.debug, `HTTP ${response.status} on attempt ${attempt + 1}`);+ return {+ ok: false,+ retryable: true,+ retryDelayMs: BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)] ?? MAX_BACKOFF_MS,+ };+ } catch (error) {+ debugLog(config.debug, `Network error on attempt ${attempt + 1}`, error);+ return {+ ok: false,+ retryable: true,+ retryDelayMs: BACKOFF_MS[Math.min(attempt, BACKOFF_MS.length - 1)] ?? MAX_BACKOFF_MS,+ };+ }+}++/** Sends an envelope with retry policy. Returns true when accepted by the server. */+export async function sendEnvelope(+ envelope: WireEnvelope,+ config: TransportConfig,+): Promise<boolean> {+ const maxAttempts = 3;+ for (let attempt = 0; attempt < maxAttempts; attempt++) {+ const result = await postEnvelope(envelope, config, attempt);+ if (result.ok) return true;+ if (!result.retryable) return false;+ if (attempt >= maxAttempts - 1) break;+ await sleep(Math.min(result.retryDelayMs, MAX_BACKOFF_MS));+ }++ debugLog(+ config.debug,+ `Dropped batch of ${envelope.events.length} event(s) after ${maxAttempts} attempts`,+ );+ return false;+}++/** Best-effort synchronous send for page hide; no retries. */+export function sendEnvelopeBeacon(envelope: WireEnvelope, config: TransportConfig): void {+ const body = envelopeBody(envelope);+ const blob = new Blob([body], { type: "application/json" });++ if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {+ const accepted = navigator.sendBeacon(beaconUrl(config.endpoint, config.apiKey), blob);+ if (accepted) return;+ debugLog(config.debug, "sendBeacon returned false; falling back to fetch keepalive");+ }++ void fetch(beaconUrl(config.endpoint, config.apiKey), {+ method: "POST",+ headers: { "content-type": "application/json" },+ body,+ keepalive: true,+ }).catch((error) => {+ debugLog(config.debug, "Beacon fallback fetch failed", error);+ });+}diff --git a/packages/observability-cloud/src/core/wire.test.ts b/packages/observability-cloud/src/core/wire.test.tsnew file mode 100644index 000000000..8ee76213f--- /dev/null+++ b/packages/observability-cloud/src/core/wire.test.ts@@ -0,0 +1,13 @@+import { readFileSync } from "node:fs";+import { dirname, join } from "node:path";+import { fileURLToPath } from "node:url";+import { describe, expect, it } from "vitest";+import { SDK_VERSION } from "./wire";++describe("SDK_VERSION", () => {+ it("matches packages/observability-cloud/package.json version", () => {+ const packageJsonPath = join(dirname(fileURLToPath(import.meta.url)), "../../package.json");+ const { version } = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { version: string };+ expect(SDK_VERSION).toBe(version);+ });+});diff --git a/packages/observability-cloud/src/core/wire.ts b/packages/observability-cloud/src/core/wire.tsnew file mode 100644index 000000000..e43beb6f7--- /dev/null+++ b/packages/observability-cloud/src/core/wire.ts@@ -0,0 +1,27 @@+import type { ObservabilityLevel } from "@openuidev/observability";+import type { StreamWireEvent } from "../events/stream";++/** Must be kept in sync with packages/observability-cloud/package.json on release. */+export const SDK_VERSION = "0.0.1";++export interface WireEventBase {+ id: string;+ kind: string;+ level: ObservabilityLevel;+ timestamp: number;+}++/** Currently a single member; will widen to a union as more kinds ship. */+export type WireEvent = StreamWireEvent;++export type { StreamWireEvent, WireErrorEntry } from "../events/stream";++export interface WireEnvelope {+ v: 1;+ sentAt: number;+ sdk: { name: "observability-cloud"; version: string };+ /** The client's capture mode; every event in the batch was shaped by it. */+ capture: "full" | "minimal";+ droppedEvents?: number;+ events: WireEvent[];+}diff --git a/packages/observability-cloud/src/events/stream.test.ts b/packages/observability-cloud/src/events/stream.test.tsnew file mode 100644index 000000000..d324939c1--- /dev/null+++ b/packages/observability-cloud/src/events/stream.test.ts@@ -0,0 +1,148 @@+import type { ObservabilityEvent } from "@openuidev/observability";+import { describe, expect, it } from "vitest";+import { selectStreamEvent } from "./stream";++function settledEvent(overrides: Record<string, unknown> = {}): ObservabilityEvent {+ return {+ level: "info",+ timestamp: 1_700_000_000_000,+ detail: {+ id: "stream-1",+ kind: "react-lang:stream",+ phase: "settled",+ updateIndex: 2,+ errorCount: 0,+ response: "hello",+ message: "OpenUI Lang settled",+ errors: [],+ parser: {+ incomplete: false,+ unresolved: [],+ orphaned: [],+ statementCount: 1,+ },+ ...overrides,+ },+ };+}++describe("selectStreamEvent", () => {+ it("accepts settled react-lang:stream events only", () => {+ expect(selectStreamEvent(settledEvent(), "full")).toMatchObject({+ id: "stream-1",+ kind: "react-lang:stream",+ level: "info",+ timestamp: 1_700_000_000_000,+ updateIndex: 2,+ errorCount: 0,+ response: "hello",+ message: "OpenUI Lang settled",+ });+ expect(selectStreamEvent(settledEvent(), "full")).not.toHaveProperty("errors");+ });++ it("rejects streaming and other kinds", () => {+ expect(selectStreamEvent(settledEvent({ phase: "streaming" }), "full")).toBeNull();+ expect(selectStreamEvent(settledEvent({ kind: "other", phase: "settled" }), "full")).toBeNull();+ });++ it("truncates full-mode response and sets responseTruncated", () => {+ const selected = selectStreamEvent(settledEvent({ response: "x".repeat(16_385) }), "full");++ expect(selected?.response).toHaveLength(16_384);+ expect(selected?.responseTruncated).toBe(true);+ });++ it("minimal mode contains only allowed keys", () => {+ const selected = selectStreamEvent(settledEvent(), "minimal");++ expect(selected).toEqual({+ id: "stream-1",+ kind: "react-lang:stream",+ level: "info",+ timestamp: 1_700_000_000_000,+ updateIndex: 2,+ errorCount: 0,+ parser: {+ incomplete: false,+ unresolved: [],+ orphaned: [],+ statementCount: 1,+ },+ });+ expect(selected).not.toHaveProperty("response");+ expect(selected).not.toHaveProperty("responseTruncated");+ expect(selected).not.toHaveProperty("message");+ expect(selected).not.toHaveProperty("errors");+ });++ const twoErrors = [+ {+ code: "unknown-component",+ source: "materialize",+ component: "Fancy",+ statementId: "card",+ message: "Unknown component Fancy",+ extra: "ignored",+ },+ { code: "unknown-tool", source: "tool", toolName: "search", message: "No tool search" },+ ];++ it("full mode ships typed error entries with messages", () => {+ const selected = selectStreamEvent(+ settledEvent({ level: "error", errors: twoErrors, errorCount: 2 }),+ "full",+ );++ expect(selected?.errorCount).toBe(2);+ expect(selected?.errors).toEqual([+ {+ code: "unknown-component",+ source: "materialize",+ component: "Fancy",+ statementId: "card",+ message: "Unknown component Fancy",+ },+ { code: "unknown-tool", source: "tool", toolName: "search", message: "No tool search" },+ ]);+ });++ it("minimal mode keeps error codes and identifiers but strips messages", () => {+ const selected = selectStreamEvent(+ settledEvent({ errors: twoErrors, errorCount: 2 }),+ "minimal",+ );++ expect(selected?.errorCount).toBe(2);+ expect(selected?.errors).toEqual([+ { code: "unknown-component", source: "materialize", component: "Fancy", statementId: "card" },+ { code: "unknown-tool", source: "tool", toolName: "search" },+ ]);+ expect(selected).not.toHaveProperty("message");+ expect(selected).not.toHaveProperty("response");+ });++ it("drops malformed error entries and reports the shipped count", () => {+ const selected = selectStreamEvent(+ settledEvent({+ errors: [{ code: "incomplete", source: "parser" }, { code: "no-source" }, "junk", null],+ errorCount: 4,+ }),+ "full",+ );++ expect(selected?.errorCount).toBe(1);+ expect(selected?.errors).toEqual([{ code: "incomplete", source: "parser" }]);+ });++ it("drops parser metadata whose identifier lists are not arrays", () => {+ const selected = selectStreamEvent(+ settledEvent({+ parser: { incomplete: false, unresolved: "a", orphaned: [], statementCount: 1 },+ }),+ "full",+ );++ expect(selected).not.toHaveProperty("parser");+ });+});diff --git a/packages/observability-cloud/src/events/stream.ts b/packages/observability-cloud/src/events/stream.tsnew file mode 100644index 000000000..df504c201--- /dev/null+++ b/packages/observability-cloud/src/events/stream.ts@@ -0,0 +1,164 @@+import type { ObservabilityEvent } from "@openuidev/observability";+import type { WireEventBase } from "../core/wire";++/**+ * Shared producer↔sink contract for stream lifecycle events. The hook+ * (src/hooks/useStreamingObservability.ts) builds event details against this+ * module, and selectStreamEvent filters against the same constants, so the two+ * sides cannot silently drift.+ */+export const STREAM_EVENT_KIND = "react-lang:stream" as const;+export type StreamEventKind = typeof STREAM_EVENT_KIND;++export const STREAM_PHASE_STREAMING = "streaming" as const;+export const STREAM_PHASE_SETTLED = "settled" as const;+export type StreamPhase = typeof STREAM_PHASE_STREAMING | typeof STREAM_PHASE_SETTLED;++const MAX_RESPONSE_LENGTH = 16_384;++export interface StreamParserMetadata {+ incomplete: boolean;+ /** Identifiers referenced but never defined in the generated program. */+ unresolved: string[];+ /** Identifiers defined but not reachable from root. */+ orphaned: string[];+ statementCount: number;+}++/**+ * One error from a settled render, as shipped to ingest. `code`/`source` are+ * required and enum-like; the rest are optional identifiers. `message` is+ * free text and is stripped in minimal capture.+ */+export interface WireErrorEntry {+ code: string;+ source: string;+ component?: string;+ statementId?: string;+ toolName?: string;+ message?: string;+}++/** Detail payload the producer emits when a stream settles. */+export interface SettledStreamEventDetail {+ id: string;+ kind: StreamEventKind;+ phase: typeof STREAM_PHASE_SETTLED;+ updateIndex: number;+ response: string | null;+ responseLength: number;+ parser?: StreamParserMetadata;+ errors: unknown[];+ errorCount: number;+ message: string;+}++/** Wire shape for settled stream events sent to cloud ingest. */+export interface StreamWireEvent extends WireEventBase {+ kind: StreamEventKind;+ updateIndex: number;+ errorCount: number;+ parser?: StreamParserMetadata;+ response?: string;+ responseTruncated?: true;+ message?: string;+ errors?: WireErrorEntry[];+}++function isStreamParserMetadata(value: unknown): value is StreamParserMetadata {+ if (!value || typeof value !== "object") return false;+ const record = value as Record<string, unknown>;+ return (+ typeof record["incomplete"] === "boolean" &&+ Array.isArray(record["unresolved"]) &&+ Array.isArray(record["orphaned"]) &&+ typeof record["statementCount"] === "number"+ );+}++const OPTIONAL_ERROR_KEYS = ["component", "statementId", "toolName"] as const;++/**+ * Projects the producer's error list onto the wire shape. Entries without a+ * string `code` and `source` are dropped; `errorCount` on the wire is the+ * length of the result, so the count always matches the list.+ */+function projectErrors(raw: unknown, capture: "full" | "minimal"): WireErrorEntry[] {+ if (!Array.isArray(raw)) return [];+ const projected: WireErrorEntry[] = [];+ for (const entry of raw) {+ if (!entry || typeof entry !== "object") continue;+ const record = entry as Record<string, unknown>;+ const code = record["code"];+ const source = record["source"];+ if (typeof code !== "string" || typeof source !== "string") continue;+ const wire: WireErrorEntry = { code, source };+ for (const key of OPTIONAL_ERROR_KEYS) {+ const value = record[key];+ if (typeof value === "string") wire[key] = value;+ }+ if (capture === "full" && typeof record["message"] === "string") {+ wire.message = record["message"];+ }+ projected.push(wire);+ }+ return projected;+}++/**+ * Returns a wire event when `event` is a settled stream event the cloud sink+ * should keep; otherwise null. Kind filtering, validation, and capture shaping+ * all live here so the shared selector stays kind-agnostic.+ */+export function selectStreamEvent(+ event: ObservabilityEvent,+ capture: "full" | "minimal",+): StreamWireEvent | null {+ const { detail } = event;+ if (detail["kind"] !== STREAM_EVENT_KIND || detail["phase"] !== STREAM_PHASE_SETTLED) return null;++ const id = detail["id"];+ if (typeof id !== "string") return null;++ const updateIndex = detail["updateIndex"];+ if (typeof updateIndex !== "number" || typeof detail["errorCount"] !== "number") return null;++ const parser = isStreamParserMetadata(detail["parser"]) ? detail["parser"] : undefined;+ const errors = projectErrors(detail["errors"], capture);+ const errorCount = errors.length;++ if (capture === "minimal") {+ return {+ id,+ kind: STREAM_EVENT_KIND,+ level: event.level,+ timestamp: event.timestamp,+ updateIndex,+ errorCount,+ ...(parser ? { parser } : {}),+ ...(errors.length > 0 ? { errors } : {}),+ };+ }++ const response = typeof detail["response"] === "string" ? detail["response"] : undefined;+ let responseTruncated: true | undefined;+ let truncatedResponse = response;+ if (response && response.length > MAX_RESPONSE_LENGTH) {+ truncatedResponse = response.slice(0, MAX_RESPONSE_LENGTH);+ responseTruncated = true;+ }++ return {+ id,+ kind: STREAM_EVENT_KIND,+ level: event.level,+ timestamp: event.timestamp,+ updateIndex,+ errorCount,+ ...(parser ? { parser } : {}),+ ...(truncatedResponse !== undefined ? { response: truncatedResponse } : {}),+ ...(responseTruncated ? { responseTruncated } : {}),+ ...(typeof detail["message"] === "string" ? { message: detail["message"] } : {}),+ ...(errors.length > 0 ? { errors } : {}),+ };+}diff --git a/packages/observability-cloud/src/index.ssr.test.ts b/packages/observability-cloud/src/index.ssr.test.tsnew file mode 100644index 000000000..fb2066c38--- /dev/null+++ b/packages/observability-cloud/src/index.ssr.test.ts@@ -0,0 +1,50 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import * as cloud from "./index";++const GLOBAL_KEY = Symbol.for("openui.cloudObservability");++function resetGlobalState(): void {+ const root = globalThis as Record<symbol, { client: unknown; options: unknown } | undefined>;+ root[GLOBAL_KEY] = { client: null, options: null };+}++const baseOptions = {+ apiKey: "test-key",+ debug: true,+} as const;++describe("cloud observability SSR guard", () => {+ beforeEach(async () => {+ await cloud.close();+ resetGlobalState();+ });++ afterEach(async () => {+ vi.restoreAllMocks();+ await cloud.close();+ resetGlobalState();+ });++ it("init no-ops when window is undefined", () => {+ const originalWindow = globalThis.window;+ const debug = vi.spyOn(console, "debug").mockImplementation(() => {});++ Object.defineProperty(globalThis, "window", {+ configurable: true,+ value: undefined,+ });++ cloud.init(baseOptions);++ expect(debug).toHaveBeenCalledWith(+ "[@openuidev/observability-cloud]",+ "init skipped in non-browser environment",+ );+ expect((globalThis as Record<symbol, { client: unknown }>)[GLOBAL_KEY]?.client).toBeNull();++ Object.defineProperty(globalThis, "window", {+ configurable: true,+ value: originalWindow,+ });+ });+});diff --git a/packages/observability-cloud/src/index.test.ts b/packages/observability-cloud/src/index.test.tsnew file mode 100644index 000000000..e264bb6df--- /dev/null+++ b/packages/observability-cloud/src/index.test.ts@@ -0,0 +1,138 @@+// @vitest-environment jsdom+import { observability } from "@openuidev/observability";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import * as transport from "./core/transport";++const mockState = vi.hoisted(() => ({ failConstruction: false }));++vi.mock("./core/client", async (importOriginal) => {+ const actual = await importOriginal<typeof import("./core/client")>();+ class CloudObservabilityClient extends actual.CloudObservabilityClient {+ constructor(options: ConstructorParameters<typeof actual.CloudObservabilityClient>[0]) {+ if (mockState.failConstruction) {+ throw new Error("construction failed");+ }+ super(options);+ }+ }+ return { ...actual, CloudObservabilityClient };+});++import { CloudObservabilityClient } from "./core/client";+import * as cloud from "./index";++const GLOBAL_KEY = Symbol.for("openui.cloudObservability");++function getGlobalState(): { client: CloudObservabilityClient | null; options: unknown } {+ return (globalThis as Record<symbol, typeof cloud> & Record<symbol, unknown>)[GLOBAL_KEY] as {+ client: CloudObservabilityClient | null;+ options: unknown;+ };+}++function resetGlobalState(): void {+ const root = globalThis as Record<symbol, { client: unknown; options: unknown } | undefined>;+ root[GLOBAL_KEY] = { client: null, options: null };+}++const baseOptions = {+ apiKey: "test-key",+ endpoint: "https://ingest.example.com/v1/events",+ debug: false,+} as const;++beforeEach(async () => {+ mockState.failConstruction = false;+ await cloud.close();+ resetGlobalState();+});++afterEach(async () => {+ mockState.failConstruction = false;+ vi.restoreAllMocks();+ await cloud.close();+ resetGlobalState();+});++describe("cloud observability lifecycle", () => {+ it("no-ops flush and close before init", async () => {+ await expect(cloud.flush()).resolves.toBe(true);+ await expect(cloud.close()).resolves.toBeUndefined();+ });++ it("init is idempotent for equivalent options", () => {+ const debug = vi.spyOn(console, "debug").mockImplementation(() => {});++ cloud.init({ ...baseOptions, debug: true });+ cloud.init({ ...baseOptions, debug: true });++ expect(debug).toHaveBeenCalledWith(+ "[@openuidev/observability-cloud]",+ "init skipped; already initialized with equivalent options",+ );+ });++ it("replaces the client when init is called with different options", async () => {+ const closeSpy = vi.spyOn(CloudObservabilityClient.prototype, "close");++ cloud.init(baseOptions);+ const firstClient = getGlobalState().client;+ cloud.init({ ...baseOptions, capture: "minimal" });+ const secondClient = getGlobalState().client;++ expect(secondClient).not.toBe(firstClient);+ expect(closeSpy).toHaveBeenCalledTimes(1);+ await cloud.close();+ });++ it("failed init leaves prior singleton state intact", () => {+ cloud.init(baseOptions);+ const priorClient = getGlobalState().client;+ const priorOptions = getGlobalState().options;++ mockState.failConstruction = true;+ cloud.init({ ...baseOptions, capture: "minimal" });++ expect(getGlobalState().client).toBe(priorClient);+ expect(getGlobalState().options).toBe(priorOptions);+ });++ it("close detaches the observability bus listener", async () => {+ let removeListener: (() => void) | undefined;+ vi.spyOn(observability, "listenAll").mockImplementation(() => {+ removeListener = vi.fn();+ return removeListener;+ });++ cloud.init(baseOptions);+ await cloud.close();++ expect(removeListener).toHaveBeenCalledOnce();+ });++ it("flush resolves false when transport drops batches", async () => {+ vi.spyOn(transport, "sendEnvelope").mockResolvedValue(false);+ cloud.init(baseOptions);++ observability.info({+ id: "stream-1",+ kind: "react-lang:stream",+ phase: "settled",+ updateIndex: 1,+ errorCount: 0,+ });++ await expect(cloud.flush()).resolves.toBe(false);+ });++ it("warns and clamps sampleRate outside [0, 1] when debug is enabled", () => {+ const warn = vi.spyOn(console, "warn").mockImplementation(() => {});++ cloud.init({ ...baseOptions, debug: true, sampleRate: 1.5 });++ expect(warn).toHaveBeenCalledWith(+ "[@openuidev/observability-cloud]",+ "sampleRate 1.5 is outside [0, 1] and was clamped to 1",+ );+ });+});diff --git a/packages/observability-cloud/src/index.ts b/packages/observability-cloud/src/index.tsnew file mode 100644index 000000000..9d7414cc9--- /dev/null+++ b/packages/observability-cloud/src/index.ts@@ -0,0 +1,152 @@+import { CloudObservabilityClient } from "./core/client";+import type { WireEvent } from "./core/wire";++export type { StreamWireEvent, WireEnvelope, WireErrorEntry, WireEvent } from "./core/wire";++const DEFAULT_ENDPOINT = "https://ingest.thesys.dev/v1/events";+const GLOBAL_KEY = Symbol.for("openui.cloudObservability");++export interface CloudObservabilityOptions {+ /** Your publishable API key from the Thesys console (`pk-th-…`). */+ apiKey: string;+ endpoint?: string;+ capture?: "full" | "minimal";+ sampleRate?: number;+ beforeSend?: (event: WireEvent) => WireEvent | null;+ debug?: boolean;+}++interface CloudObservabilityGlobal {+ client: CloudObservabilityClient | null;+ options: CloudObservabilityOptions | null;+}++function getGlobalState(): CloudObservabilityGlobal {+ const root = globalThis as Record<symbol, CloudObservabilityGlobal | undefined>;+ if (!root[GLOBAL_KEY]) {+ root[GLOBAL_KEY] = { client: null, options: null };+ }+ return root[GLOBAL_KEY]!;+}++function debugLog(options: CloudObservabilityOptions | null | undefined, message: string): void {+ if (!options?.debug) return;+ // eslint-disable-next-line no-console -- gated debug diagnostics for cloud sink+ console.debug("[@openuidev/observability-cloud]", message);+}++function debugWarn(options: CloudObservabilityOptions, message: string): void {+ if (!options.debug) return;+ console.warn("[@openuidev/observability-cloud]", message);+}++function resolvedEndpoint(options: CloudObservabilityOptions): string {+ return options.endpoint ?? DEFAULT_ENDPOINT;+}++function resolvedCapture(options: CloudObservabilityOptions): "full" | "minimal" {+ return options.capture ?? "full";+}++function resolvedSampleRate(options: CloudObservabilityOptions): number {+ const raw = options.sampleRate ?? 1;+ const clamped = Math.min(1, Math.max(0, raw));+ if (clamped !== raw) {+ debugWarn(options, `sampleRate ${raw} is outside [0, 1] and was clamped to ${clamped}`);+ }+ return clamped;+}++function resolvedDebug(options: CloudObservabilityOptions): boolean {+ return options.debug ?? false;+}++function optionsEqual(a: CloudObservabilityOptions, b: CloudObservabilityOptions): boolean {+ return (+ a.apiKey === b.apiKey &&+ resolvedEndpoint(a) === resolvedEndpoint(b) &&+ resolvedCapture(a) === resolvedCapture(b) &&+ resolvedSampleRate(a) === resolvedSampleRate(b) &&+ resolvedDebug(a) === resolvedDebug(b) &&+ a.beforeSend === b.beforeSend+ );+}++function createClient(options: CloudObservabilityOptions): CloudObservabilityClient {+ return new CloudObservabilityClient({+ apiKey: options.apiKey,+ endpoint: resolvedEndpoint(options),+ capture: resolvedCapture(options),+ sampleRate: resolvedSampleRate(options),+ beforeSend: options.beforeSend,+ debug: resolvedDebug(options),+ });+}++export function init(options: CloudObservabilityOptions): void {+ try {+ if (typeof window === "undefined") {+ debugLog(options, "init skipped in non-browser environment");+ return;+ }++ const state = getGlobalState();+ if (state.client && state.options && optionsEqual(state.options, options)) {+ debugLog(options, "init skipped; already initialized with equivalent options");+ return;+ }++ const priorClient = state.client;+ const priorOptions = state.options;++ try {+ const client = createClient(options);+ if (priorClient) {+ void priorClient.close().catch(() => {});+ }+ state.client = client;+ state.options = options;+ } catch (error) {+ state.client = priorClient;+ state.options = priorOptions;+ if (options.debug) {+ console.warn("[@openuidev/observability-cloud]", "init failed", error);+ }+ }+ } catch (error) {+ if (options.debug) {+ console.warn("[@openuidev/observability-cloud]", "init failed", error);+ }+ }+}++export async function flush(timeoutMs?: number): Promise<boolean> {+ try {+ const client = getGlobalState().client;+ if (!client) return true;+ return await client.flush(timeoutMs);+ } catch (error) {+ const options = getGlobalState().options;+ if (options?.debug) {+ console.warn("[@openuidev/observability-cloud]", "flush failed", error);+ }+ return false;+ }+}++export async function close(): Promise<void> {+ try {+ const state = getGlobalState();+ if (!state.client) return;+ await state.client.close();+ state.client = null;+ state.options = null;+ } catch (error) {+ const options = getGlobalState().options;+ if (options?.debug) {+ console.warn("[@openuidev/observability-cloud]", "close failed", error);+ }+ getGlobalState().client = null;+ getGlobalState().options = null;+ }+}diff --git a/packages/observability-cloud/src/integration.test.ts b/packages/observability-cloud/src/integration.test.tsnew file mode 100644index 000000000..092e3ae93--- /dev/null+++ b/packages/observability-cloud/src/integration.test.ts@@ -0,0 +1,79 @@+// @vitest-environment jsdom+import { observability } from "@openuidev/observability";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import * as transport from "./core/transport";+import * as cloud from "./index";++const GLOBAL_KEY = Symbol.for("openui.cloudObservability");++function resetGlobalState(): void {+ const root = globalThis as Record<symbol, { client: unknown; options: unknown } | undefined>;+ root[GLOBAL_KEY] = { client: null, options: null };+}++const baseOptions = {+ apiKey: "test-key",+ endpoint: "https://ingest.example.com/v1/events",+ debug: false,+} as const;++function settledDetail(id: string, updateIndex = 1) {+ return {+ id,+ kind: "react-lang:stream" as const,+ phase: "settled" as const,+ updateIndex,+ errorCount: 0,+ response: "done",+ responseLength: 4,+ };+}++beforeEach(async () => {+ await cloud.close();+ resetGlobalState();+ vi.spyOn(transport, "sendEnvelope").mockResolvedValue(true);+ vi.spyOn(transport, "sendEnvelopeBeacon").mockImplementation(() => {});+});++afterEach(async () => {+ vi.restoreAllMocks();+ await cloud.close();+ resetGlobalState();+});++describe("cloud observability integration", () => {+ it("forwards settled react-lang:stream events from the observability bus", async () => {+ cloud.init(baseOptions);++ observability.info(settledDetail("stream-a"));++ await cloud.flush();++ expect(transport.sendEnvelope).toHaveBeenCalledTimes(1);+ const envelope = vi.mocked(transport.sendEnvelope).mock.calls[0]?.[0];+ expect(envelope?.events).toEqual([+ expect.objectContaining({ id: "stream-a", kind: "react-lang:stream" }),+ ]);+ });++ it("forwards republished settled events with the same id as separate wire events", async () => {+ cloud.init(baseOptions);++ observability.info(settledDetail("stream-a", 1));+ observability.error({+ ...settledDetail("stream-a", 2),+ errorCount: 1,+ errors: [{ source: "query", code: "x", message: "failed" }],+ });++ await cloud.flush();++ const envelopes = vi+ .mocked(transport.sendEnvelope)+ .mock.calls.flatMap(([payload]) => payload.events);+ expect(envelopes).toHaveLength(2);+ expect(envelopes[0]).toMatchObject({ id: "stream-a", updateIndex: 1 });+ expect(envelopes[1]).toMatchObject({ id: "stream-a", updateIndex: 2, errorCount: 1 });+ });+});diff --git a/packages/observability-cloud/tsconfig.json b/packages/observability-cloud/tsconfig.jsonnew file mode 100644index 000000000..050ddeb9a--- /dev/null+++ b/packages/observability-cloud/tsconfig.json@@ -0,0 +1,13 @@+{+ "$schema": "https://json.schemastore.org/tsconfig",+ "extends": "../../tsconfig.json",+ "include": ["src/**/*"],+ "exclude": ["src/**/__tests__/**", "src/**/*.test.ts"],+ "compilerOptions": {+ "moduleResolution": "bundler",+ "module": "ESNext",+ "outDir": "./dist",+ "rootDir": "./src",+ "noEmit": true+ }+}diff --git a/packages/observability-cloud/tsconfig.test.json b/packages/observability-cloud/tsconfig.test.jsonnew file mode 100644index 000000000..60b3001d5--- /dev/null+++ b/packages/observability-cloud/tsconfig.test.json@@ -0,0 +1,9 @@+{+ "$schema": "https://json.schemastore.org/tsconfig",+ "extends": "./tsconfig.json",+ "compilerOptions": {+ "noEmit": true+ },+ "include": ["src/**/*"],+ "exclude": ["dist", "node_modules"]+}diff --git a/packages/observability-cloud/tsdown.config.ts b/packages/observability-cloud/tsdown.config.tsnew file mode 100644index 000000000..bd5f1a3e1--- /dev/null+++ b/packages/observability-cloud/tsdown.config.ts@@ -0,0 +1,14 @@+import { defineConfig } from "tsdown";++export default defineConfig({+ entry: ["src/index.ts"],+ format: ["esm", "cjs"],+ dts: true,+ sourcemap: true,+ target: "es2022",+ outDir: "dist",+ clean: true,+ deps: {+ neverBundle: [/^(?![./]|[A-Za-z]:[/\\])/],+ },+});diff --git a/packages/react-lang/src/hooks/streamEvent.ts b/packages/react-lang/src/hooks/streamEvent.tsnew file mode 100644index 000000000..5dd439b4a--- /dev/null+++ b/packages/react-lang/src/hooks/streamEvent.ts@@ -0,0 +1,34 @@+/**+ * Producer-side contract for the stream lifecycle events this package emits on+ * `@openuidev/observability`. Intentionally duplicated (not imported) in+ * `@openuidev/observability-cloud` (src/events/stream.ts), which consumes these+ * events; the two packages have no dependency on each other. Keep the string+ * constants and the settled detail shape in sync when changing either side.+ */+export const STREAM_EVENT_KIND = "react-lang:stream" as const;+export type StreamEventKind = typeof STREAM_EVENT_KIND;++export const STREAM_PHASE_STREAMING = "streaming" as const;+export const STREAM_PHASE_SETTLED = "settled" as const;+export type StreamPhase = typeof STREAM_PHASE_STREAMING | typeof STREAM_PHASE_SETTLED;++export interface StreamParserMetadata {+ incomplete: boolean;+ unresolved: unknown;+ orphaned: unknown;+ statementCount: number;+}++/** Detail payload emitted when a stream settles. */+export interface SettledStreamEventDetail {+ id: string;+ kind: StreamEventKind;+ phase: typeof STREAM_PHASE_SETTLED;+ updateIndex: number;+ response: string | null;+ responseLength: number;+ parser?: StreamParserMetadata;+ errors: unknown[];+ errorCount: number;+ message: string;+}diff --git a/packages/react-lang/src/hooks/useStreamingObservability.test.ts b/packages/react-lang/src/hooks/useStreamingObservability.test.tsindex ce5b369be..10a982358 100644--- a/packages/react-lang/src/hooks/useStreamingObservability.test.ts+++ b/packages/react-lang/src/hooks/useStreamingObservability.test.ts@@ -36,7 +36,7 @@ describe("streaming observability lifecycle", () => {).toEqual({id: "stream-1",phase: "settled",- updateIndex: 2,+ updateIndex: 3,});expect(idFactory).toHaveBeenCalledOnce();});@@ -70,7 +70,7 @@ describe("streaming observability lifecycle", () => {expect(advanceStreamingObservability(state, false, "first", "[]", idFactory)).toEqual({id: "stream-1",phase: "settled",- updateIndex: 1,+ updateIndex: 2,});expect(advanceStreamingObservability(state, true, "second", null, idFactory)).toEqual({id: "stream-2",@@ -80,12 +80,12 @@ describe("streaming observability lifecycle", () => {expect(advanceStreamingObservability(state, false, "second", "[]", idFactory)).toEqual({id: "stream-2",phase: "settled",- updateIndex: 1,+ updateIndex: 2,});expect(idFactory).toHaveBeenCalledTimes(2);});- it("republishes settled when the error snapshot changes", () => {+ it("republishes settled with a new updateIndex when the error snapshot changes", () => {const state = createStreamingObservabilityState();const idFactory = () => "stream-1";@@ -103,7 +103,7 @@ describe("streaming observability lifecycle", () => {).toEqual({id: "stream-1",phase: "settled",- updateIndex: 1,+ updateIndex: 3,});expect(advanceStreamingObservability(@@ -114,5 +114,14 @@ describe("streaming observability lifecycle", () => {idFactory,),).toBeNull();+ expect(+ advanceStreamingObservability(+ state,+ false,+ "root = Card()",+ '[{"code":"query-error"},{"code":"tool-failed"}]',+ idFactory,+ ),+ ).toEqual({ id: "stream-1", phase: "settled", updateIndex: 4 });});});diff --git a/packages/react-lang/src/hooks/useStreamingObservability.ts b/packages/react-lang/src/hooks/useStreamingObservability.tsindex 3c2bd4013..5509631b9 100644--- a/packages/react-lang/src/hooks/useStreamingObservability.ts+++ b/packages/react-lang/src/hooks/useStreamingObservability.ts@@ -1,6 +1,13 @@import type { OpenUIError, ParseResult } from "@openuidev/lang-core";import { observability } from "@openuidev/observability";import { useEffect, useRef } from "react";+import {+ STREAM_EVENT_KIND,+ STREAM_PHASE_SETTLED,+ STREAM_PHASE_STREAMING,+ type SettledStreamEventDetail,+ type StreamPhase,+} from "./streamEvent";type CurrentRef<T> = { current: T };@@ -23,7 +30,7 @@ export interface StreamingObservabilityState {export interface StreamingObservabilityUpdate {id: string;- phase: "streaming" | "settled";+ phase: StreamPhase;updateIndex: number;}@@ -67,7 +74,7 @@ export function advanceStreamingObservability(state.hasPublishedStreamingSnapshot = true;state.lastResponse = response;state.updateIndex += 1;- return { id: state.id, phase: "streaming", updateIndex: state.updateIndex };+ return { id: state.id, phase: STREAM_PHASE_STREAMING, updateIndex: state.updateIndex };}// A Renderer mounted only for static or historical content never starts a stream.@@ -79,9 +86,10 @@ export function advanceStreamingObservability(return null;}+ state.updateIndex += 1;state.settled = true;state.lastSettledErrorKey = settledErrorKey;- return { id: state.id, phase: "settled", updateIndex: state.updateIndex };+ return { id: state.id, phase: STREAM_PHASE_SETTLED, updateIndex: state.updateIndex };}function parserMetadata(result: ParseResult | null) {@@ -121,7 +129,7 @@ export function useStreamingObservability({if (update) {observability.info({id: update.id,- kind: "react-lang:stream",+ kind: STREAM_EVENT_KIND,phase: update.phase,updateIndex: update.updateIndex,response,@@ -133,11 +141,11 @@ export function useStreamingObservability({return;}- if (update?.phase === "settled") {+ if (update?.phase === STREAM_PHASE_SETTLED) {observability(errors.length > 0 ? "error" : "info", {id: update.id,- kind: "react-lang:stream",- phase: update.phase,+ kind: STREAM_EVENT_KIND,+ phase: STREAM_PHASE_SETTLED,updateIndex: update.updateIndex,response,responseLength: response?.length ?? 0,@@ -148,7 +156,7 @@ export function useStreamingObservability({errors.length > 0? `OpenUI Lang settled with ${errors.length} error${errors.length === 1 ? "" : "s"}`: "OpenUI Lang settled",- });+ } satisfies SettledStreamEventDetail);}}, [isStreaming, response, result, errorsRef, errorRevision]);}diff --git a/packages/react-lang/tsdown.config.ts b/packages/react-lang/tsdown.config.tsindex e2715120b..fdb9d33cc 100644--- a/packages/react-lang/tsdown.config.ts+++ b/packages/react-lang/tsdown.config.ts@@ -1,7 +1,10 @@import { defineConfig } from "tsdown";export default defineConfig({- entry: ["src/index.ts", "src/index.native.ts"],+ entry: {+ index: "src/index.ts",+ "index.native": "src/index.native.ts",+ },format: ["esm", "cjs"],dts: true,sourcemap: true,diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 5b236e986..47949c0c5 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -1818,6 +1818,19 @@ importers:specifier: ^4.1.0version: 4.1.10(@opentelemetry/[email protected])(@types/[email protected])([email protected])([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected])([email protected]))+ packages/observability-cloud:+ dependencies:+ '@openuidev/observability':+ specifier: workspace:^+ version: link:../observability+ devDependencies:+ jsdom:+ specifier: 'catalog:'+ version: 26.1.0+ vitest:+ specifier: ^4.1.0+ version: 4.1.10(@opentelemetry/[email protected])(@types/[email protected])([email protected])([email protected](@types/[email protected])([email protected])([email protected])([email protected])([email protected])([email protected])([email protected]))+packages/openui-cli:dependencies:'@inquirer/core':