durable-actors-observer 0.1.0 → 0.4.3

package/README.md

@@ -0,0 +1,33 @@
+# Durable Actors Observer
+
+React 19 components for embedding Durable Actors observability in a hosted app.
+
+```tsx
+import { HttpObserverClient, Overview, WebSocketObserver } from "durable-actors-observer"
+import "durable-actors-observer/styles.css"
+import "durable-actors-observer/theme.css"
+
+const projectId = "my-project"
+const client = new HttpObserverClient(`/api/projects/${encodeURIComponent(projectId)}/observe`)
+
+export function Observability() {
+    return (
+        <>
+            <Overview client={client} onSelectActor={actorName => console.log(actorName)} />
+            <WebSocketObserver client={client} />
+        </>
+    )
+}
+```
+
+Import `styles.css` once. The optional `theme.css` supplies light and dark theme tokens; omit it when the host supplies those tokens. Apply the `dark` class to an ancestor for dark mode.
+
+The package exports `ActorObserver`, `RequestObserver`, `Overview`, `WebSocketObserver`, `ConsoleApp`, `SocketTimeline`, `TimeRangePicker`, and `FilterCombobox`, along with their named props types. It also exports the shared badge, button, calendar, command, input, popover, sheet, and table components from the package root. Use React's `ComponentProps<typeof Button>` (and equivalent) for primitive props.
+
+Pass your own `ObserverClient` to connect these views to a hosted backend, or configure `HttpObserverClient` with your API prefix and fetch implementation. React remains a peer dependency. `ConsoleApp` provides the complete navigation shell and requires a `toggleTheme` callback; individual views can be placed inside your own navigation.
+
+Control-plane endpoints require a project in the path: `/v1/projects/{project_id}/observe/...`. The hosted backend should authorize access to that project and proxy the routes using its server-side admin credential. The CLI's `/api/observe` proxy uses its configured `DURABLE_ACTORS_PROJECT_ID`. Request traces include a required `projectId`; older stored traces without one are excluded from project results.
+
+The observer version follows the SDK and runtime version. Run `pnpm release:prepare <version>` at the repository root before publishing a GitHub release. Release preflight checks all versions, and the workflow publishes the observer before the SDK. The SDK's `workspace:*` dependency becomes the exact observer version when packed.
+
+The localhost-only `durable-actors dev` runtime allows observability requests without a secret, even when a secret is configured for application routes. Hosted runtimes retain their configured admin authentication.

package/dist/ConsoleApp.d.ts

@@ -1,5 +1,6 @@
 import type { ObserverClient } from "./client.js";
-export declare function ConsoleApp({ client, toggleTheme }: {
+export interface ConsoleAppProps {
     client: ObserverClient;
     toggleTheme: () => void;
-}): import("react").JSX.Element;
+}
+export declare function ConsoleApp({ client, toggleTheme }: ConsoleAppProps): import("react").JSX.Element;

package/dist/FilterCombobox.d.ts

@@ -3,7 +3,7 @@ export interface FilterSuggestion {
     value: string;
     hint?: string;
 }
-interface FilterComboboxProps {
+export interface FilterComboboxProps {
     label: string;
     placeholder: string;
     value: string;
@@ -13,4 +13,3 @@ interface FilterComboboxProps {
 }
 export declare function FilterCombobox({ label, placeholder, value, onChange, suggestions, limit }: FilterComboboxProps): import("react").JSX.Element;
 export declare function matchSuggestions(suggestions: FilterSuggestion[], value: string, limit: number): FilterSuggestion[];
-export {};

package/dist/Overview.d.ts

@@ -1,10 +1,9 @@
 import type { ObserverClient } from "./client.js";
 import type { TimeRange } from "./time-range.js";
-interface OverviewProps {
+export interface OverviewProps {
     client: ObserverClient;
     onSelectActor: (actorName: string) => void;
     timeRange?: TimeRange;
     onTimeRangeChange?: (range: TimeRange) => void;
 }
 export declare function Overview({ client, onSelectActor, timeRange, onTimeRangeChange }: OverviewProps): import("react").JSX.Element;
-export {};

package/dist/RequestObserver.d.ts

@@ -1,7 +1,7 @@
 import type { ObserverClient, RequestTrace } from "./client.js";
 import type { TimeRange } from "./time-range.js";
 interface RequestObserverProps {
-    client: Pick<ObserverClient, "watchRequests" | "query">;
+    client: Pick<ObserverClient, "watchRequests" | "listRequests">;
     actor?: Pick<RequestTrace, "actorName" | "actorId">;
     timeRange?: TimeRange;
     onTimeRangeChange?: (range: TimeRange) => void;

package/dist/SocketTimeline.d.ts

@@ -1,5 +1,5 @@
 import type { SocketSession } from "./socket-sessions.js";
-interface SocketTimelineProps {
+export interface SocketTimelineProps {
     sessions: SocketSession[];
     start: number;
     end: number;

package/dist/TimeRangePicker.d.ts

@@ -1,5 +1,5 @@
 import type { TimeRange } from "./time-range.js";
-interface TimeRangePickerProps {
+export interface TimeRangePickerProps {
     value: TimeRange;
     onChange: (range: TimeRange) => void;
     allowAll?: boolean;
@@ -7,4 +7,3 @@ interface TimeRangePickerProps {
     align?: "start" | "end";
 }
 export declare function TimeRangePicker({ value, onChange, allowAll, className, align }: TimeRangePickerProps): import("react").JSX.Element;
-export {};

package/dist/WebSocketObserver.d.ts

@@ -1,10 +1,9 @@
 import type { ObserverClient } from "./client.js";
 import type { TimeRange } from "./time-range.js";
-interface WebSocketObserverProps {
+export interface WebSocketObserverProps {
     client: ObserverClient;
     onSelectActor?: (actorName: string) => void;
     timeRange?: TimeRange;
     onTimeRangeChange?: (range: TimeRange) => void;
 }
 export declare function WebSocketObserver({ client, onSelectActor, timeRange, onTimeRangeChange }: WebSocketObserverProps): import("react").JSX.Element;
-export {};

package/dist/client.d.ts

@@ -1,3 +1,7 @@
+import { type OverviewMetrics } from "./overview-metrics.js";
+import { type QueueWaitRow } from "./queue-wait.js";
+import { type SocketSessionRow } from "./socket-sessions.js";
+import type { ResolvedRange } from "./time-range.js";
 type ActorResidency = "live" | "dormant" | "unknown";
 interface ActorInstance {
     actorId: string;
@@ -22,7 +26,12 @@ interface ActorInventory {
     }[];
 }
 interface ObserverClient {
-    query?(query: ObserverQuery, signal?: AbortSignal): Promise<ObserverQueryResult>;
+    getMetrics?(range: ResolvedRange, signal?: AbortSignal): Promise<OverviewMetrics>;
+    listQueueWaits?(query: ResolvedRange & {
+        actorName?: string;
+    }, signal?: AbortSignal): Promise<QueueWaitRow[]>;
+    listWebSockets?(range: ResolvedRange, signal?: AbortSignal): Promise<SocketSessionRow[]>;
+    listRequests?(query: RequestHistoryQuery, signal?: AbortSignal): Promise<RequestTracePage>;
     watchRequests?(onPage: (page: RequestTracePage) => void, signal: AbortSignal, after?: string): Promise<void>;
     watchActors?(onInventory: (inventory: ActorInventory) => void, signal: AbortSignal): Promise<void>;
     listActors(signal?: AbortSignal): Promise<ActorInventory>;
@@ -32,10 +41,15 @@ declare class HttpObserverClient implements ObserverClient {
     private readonly baseUrl;
     private readonly request;
     constructor(baseUrl?: string, request?: typeof fetch);
+    getMetrics(range: ResolvedRange, signal?: AbortSignal): Promise<OverviewMetrics>;
+    listQueueWaits(query: ResolvedRange & {
+        actorName?: string;
+    }, signal?: AbortSignal): Promise<QueueWaitRow[]>;
+    listWebSockets(range: ResolvedRange, signal?: AbortSignal): Promise<SocketSessionRow[]>;
     listActors(signal?: AbortSignal): Promise<ActorInventory>;
     watchActors(onInventory: (inventory: ActorInventory) => void, signal: AbortSignal): Promise<void>;
     watchRequests(onPage: (page: RequestTracePage) => void, signal: AbortSignal, after?: string): Promise<void>;
-    query(query: ObserverQuery, signal?: AbortSignal): Promise<ObserverQueryResult>;
+    listRequests(query: RequestHistoryQuery, signal?: AbortSignal): Promise<RequestTracePage>;
     private watch;
     checkConnection(signal?: AbortSignal): Promise<void>;
     private get;
@@ -43,6 +57,8 @@ declare class HttpObserverClient implements ObserverClient {
 export { HttpObserverClient };
 export type { ActorConnection, ActorInstance, ActorInventory, ActorResidency, ObserverClient };
 export interface RequestTrace {
+    projectId: string;
+    metadata?: unknown;
     eventId?: string;
     sequence: number;
     requestId: string;
@@ -58,14 +74,14 @@ export interface RequestTrace {
     queueWaitMs: number | null;
     outcome: "completed" | "failed" | "rejected" | "rerouted" | "interrupted";
 }
-export type SqlValue = string | number | boolean | null;
-export interface ObserverQuery {
-    sql: string;
-    params: SqlValue[];
-}
-export interface ObserverQueryResult {
-    rows: Record<string, SqlValue>[];
-    truncated: boolean;
+export interface RequestHistoryQuery {
+    actorName?: string;
+    actorId?: string;
+    outcome?: RequestTrace["outcome"];
+    fromMs?: number;
+    toMs?: number;
+    limit?: number;
+    cursor?: string;
 }
 export interface RequestTracePage {
     nextCursor?: string | null;

package/dist/index.d.ts

@@ -1,10 +1,31 @@
 export { ActorObserver } from "./ActorObserver.js";
+export type { ActorObserverProps } from "./ActorObserver.js";
+export { ConsoleApp } from "./ConsoleApp.js";
+export type { ConsoleAppProps } from "./ConsoleApp.js";
+export { FilterCombobox } from "./FilterCombobox.js";
+export type { FilterComboboxProps, FilterSuggestion } from "./FilterCombobox.js";
+export { Overview } from "./Overview.js";
+export type { OverviewProps } from "./Overview.js";
 export { RequestObserver } from "./RequestObserver.js";
 export type { RequestObserverProps } from "./RequestObserver.js";
-export type { RequestTrace, RequestTracePage, ObserverQuery, ObserverQueryResult } from "./client.js";
-export type { ActorObserverProps } from "./ActorObserver.js";
-export { HttpObserverClient } from "./client.js";
-export type { ActorInventory, ObserverClient } from "./client.js";
+export { SocketTimeline } from "./SocketTimeline.js";
+export type { SocketTimelineProps } from "./SocketTimeline.js";
 export { TimeRangePicker } from "./TimeRangePicker.js";
+export type { TimeRangePickerProps } from "./TimeRangePicker.js";
+export { WebSocketObserver } from "./WebSocketObserver.js";
+export type { WebSocketObserverProps } from "./WebSocketObserver.js";
+export { Badge, badgeVariants } from "./components/ui/badge.js";
+export { Button, buttonVariants } from "./components/ui/button.js";
+export { Calendar, CalendarDayButton } from "./components/ui/calendar.js";
+export { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandShortcut, CommandSeparator } from "./components/ui/command.js";
+export { Input } from "./components/ui/input.js";
+export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor, PopoverHeader, PopoverTitle, PopoverDescription } from "./components/ui/popover.js";
+export { Sheet, SheetContent, SheetTitle, SheetDescription } from "./components/ui/sheet.js";
+export { Table, TableHeader, TableBody, TableFooter, TableHead, TableRow, TableCell, TableCaption } from "./components/ui/table.js";
+export { HttpObserverClient } from "./client.js";
+export type { ActorConnection, ActorInstance, ActorInventory, ActorResidency, ObserverClient, RequestTrace, RequestTracePage, RequestHistoryQuery } from "./client.js";
 export { defaultTimeRange, rangeLabel, resolveRange } from "./time-range.js";
 export type { TimeRange, ResolvedRange } from "./time-range.js";
+export type { OverviewMetrics, ClassMetrics } from "./overview-metrics.js";
+export type { QueueWaitRow, QueueWaitStats } from "./queue-wait.js";
+export type { SocketSession, SocketSessionRow, SocketSessionStatus } from "./socket-sessions.js";