uidex 0.6.0 → 0.7.0

package/dist/cloud/index.d.ts

@@ -11,7 +11,10 @@ declare const DEFAULT_CLOUD_ENDPOINT = "https://app.uidex.dev";
 interface CloudOptions {
     projectKey: string;
     endpoint?: string;
+    /** @deprecated Unused — the adapter talks RPC over WebSocket. Kept for API compatibility. */
     fetch?: typeof fetch;
+    /** Optional WebSocket constructor override (tests, Node). Defaults to `globalThis.WebSocket`. */
+    WebSocketImpl?: typeof WebSocket;
     git?: {
         branch?: string;
         commit?: string;
@@ -44,6 +47,8 @@ interface RealtimeChannel {
     joinRoute(route: string): void;
     onPresence(cb: (users: RealtimePresenceUser[]) => void): () => void;
     onPin(cb: (pin: PinRecord) => void): () => void;
+    /** Optional so pre-existing channel stubs keep satisfying the interface. */
+    onPinArchived?(cb: (reportId: string) => void): () => void;
 }
 interface CloudAdapter<TPayload = ReportPayload, TResult = ReportResult, TIntegrations = {
     getConfig(): Promise<IngestConfig>;
@@ -65,18 +70,201 @@ interface CloudAdapter<TPayload = ReportPayload, TResult = ReportResult, TIntegr
             route?: string;
             entities?: string;
         }): Promise<PinRecord[]>;
-        archive(reportId: string, reason?: ArchiveReason): Promise<void>;
+        /**
+         * Pin records travel without their screenshot (kept out of `pins.list`
+         * so multi-MB frames don't stall the shared socket); the report detail
+         * view fetches it lazily through here. Optional for host-provided
+         * adapters that inline screenshots on the record instead.
+         */
+        screenshot?(reportId: string): Promise<string | null>;
+        close(reportId: string, reason?: ArchiveReason): Promise<void>;
     };
+    /** Closes the adapter's shared socket. Any later RPC call revives it. */
+    dispose?(): void;
 }
 
 declare function cloud(options: CloudOptions): CloudAdapter;
 
+/**
+ * WS RPC protocol shared by the SDK (`packages/sdk/src/cloud`) and the relay
+ * server (`apps/app/src/lib/relay-handler.ts`, type-only import from
+ * "uidex/cloud"). These frames ride the same socket as the existing
+ * fire-and-forget messages (`cursor`, `join`, `presence`, `pin`); peers that
+ * predate a frame type silently drop it.
+ */
+declare const RPC_METHODS: readonly ["reports.submit", "reports.list", "config.get", "pins.list", "pins.screenshot", "pins.archive", "screenshot.chunk"];
+type RpcMethod = (typeof RPC_METHODS)[number];
+/**
+ * Screenshots whose base64 data-URL length is at or below this ride inline in
+ * the `reports.submit` frame (the common case). Larger ones are streamed via
+ * `screenshot.chunk` so no single frame approaches the relay's 25 MiB WS
+ * `maxPayload` — an oversized frame is dropped server-side (close 1009), which
+ * the SDK surfaces as "Connection lost".
+ */
+declare const SCREENSHOT_INLINE_MAX_BYTES: number;
+/** Per-chunk size when a screenshot is streamed. Each `screenshot.chunk` frame stays well under `maxPayload`. */
+declare const SCREENSHOT_CHUNK_BYTES: number;
+/** One streamed screenshot fragment. Parts are keyed by `seq` and reassembled in order server-side. */
+type ScreenshotChunkParams = {
+    /** Client-generated id grouping a screenshot's chunks; referenced by `reports.submit` as `screenshotUploadId`. */
+    uploadId: string;
+    /** 0-based index of this part. */
+    seq: number;
+    /** Total number of parts in this upload. */
+    total: number;
+    /** A slice of the screenshot data URL. */
+    data: string;
+};
+/**
+ * `reports.submit` params. Either the screenshot rides inline (`screenshot`) or,
+ * for large captures, it is streamed via `screenshot.chunk` and referenced here
+ * by `screenshotUploadId` — the server reassembles it before persisting.
+ */
+type ReportSubmitParams = ReportPayload & {
+    screenshotUploadId?: string;
+};
+interface RpcParamsMap {
+    "reports.submit": ReportSubmitParams;
+    "reports.list": {
+        page?: number;
+        limit?: number;
+    };
+    "config.get": undefined;
+    "pins.list": {
+        route?: string;
+        entities?: string[];
+    };
+    "pins.screenshot": {
+        reportId: string;
+    };
+    "pins.archive": {
+        reportId: string;
+        reason?: ArchiveReason;
+    };
+    "screenshot.chunk": ScreenshotChunkParams;
+}
+interface RpcResultMap {
+    "reports.submit": ReportResult;
+    "reports.list": ReportListResponse;
+    "config.get": IngestConfig;
+    "pins.list": {
+        pins: PinRecord[];
+    };
+    "pins.screenshot": {
+        screenshot: string | null;
+    };
+    "pins.archive": {
+        ok: true;
+    };
+    /** Acks a stored chunk; `received` is how many distinct parts have arrived. */
+    "screenshot.chunk": {
+        received: number;
+    };
+}
+type RpcRequestFrame = {
+    type: "rpc";
+    id: string;
+    method: RpcMethod;
+    params?: unknown;
+};
+type RpcOkFrame = {
+    type: "rpc:res";
+    id: string;
+    ok: true;
+    data: unknown;
+};
+type RpcErrFrame = {
+    type: "rpc:res";
+    id: string;
+    ok: false;
+    /** HTTP-equivalent status so CloudError semantics survive the transport. */
+    status: number;
+    error: string;
+    /** Seconds, present on 429 responses (mirrors the Retry-After header). */
+    retryAfter?: number;
+    details?: unknown;
+};
+type RpcResponseFrame = RpcOkFrame | RpcErrFrame;
+/**
+ * Sent by the SDK after `realtime.connect(opts)` to attach a user identity to
+ * an initially anonymous connection. The server marks the connection visible
+ * in presence from this point on. Connections that never identify stay
+ * RPC-only: excluded from presence, no room auto-join.
+ */
+type IdentifyFrame = {
+    type: "identify";
+    userId: string;
+    name?: string;
+    avatar?: string;
+};
+/**
+ * Reverse of `IdentifyFrame`: sent when a realtime consumer disconnects
+ * (e.g. the uidex surface unmounts) while the adapter keeps using the socket
+ * for RPC. The server drops the connection from presence and its room but
+ * keeps the socket open.
+ */
+type LeaveFrame = {
+    type: "leave";
+};
+/**
+ * Server→client broadcast when a pin's report leaves the open statuses
+ * (closed via the SDK, the dashboard, or the REST route). Sent to the room of
+ * the report's route so live overlays drop the pin without a refresh.
+ */
+type PinArchivedFrame = {
+    type: "pin:archived";
+    reportId: string;
+};
+declare function isRpcMethod(value: unknown): value is RpcMethod;
+/** Client-side guard for inbound `rpc:res` frames (server validates inbound `rpc` frames itself). */
+declare function parseRpcResponseFrame(msg: unknown): RpcResponseFrame | null;
+
 type RealtimeChannelOptions = {
-    /** Builds the WebSocket URL on each (re)connect attempt. Allows the caller to refresh `route` query params. */
+    /** Builds the WebSocket URL on each (re)connect attempt. Only needs the project key — identity and route ride dedicated frames. */
     buildUrl: () => string;
     /** Optional WebSocket constructor override (testing). Defaults to `globalThis.WebSocket`. */
     WebSocketImpl?: typeof WebSocket;
 };
-declare function createRealtimeChannel(options: RealtimeChannelOptions): RealtimeChannel;
+/**
+ * Superset of the public `RealtimeChannel` used internally by the cloud
+ * adapter: the RPC client (`./rpc`) shares the same socket and needs raw
+ * frame access plus open/close notifications.
+ */
+interface InternalRealtimeChannel extends RealtimeChannel {
+    /** Required here (optional on the public interface only for channel stubs). */
+    onPinArchived(cb: (reportId: string) => void): () => void;
+    /** Stores the identity and (re)sends the `identify` frame on every open. */
+    identify(user: UserIdentity): void;
+    /** Drops the stored identity/route without touching the socket (soft leave). */
+    clearSession(): void;
+    /** Sends a JSON frame if the socket is OPEN. Returns false otherwise. */
+    sendFrame(frame: object): boolean;
+    /** Fires after the channel finished its identify/join replay on (re)open. */
+    onOpen(cb: () => void): () => void;
+    /**
+     * Fires with the close code (or `CLOSE_CODE_SYNTHETIC`) whenever the socket
+     * goes away. `willReconnect` is false for terminal closes (`disconnect()`,
+     * auth failure, no WebSocket implementation): queued work must reject
+     * instead of riding a reconnect that will never come.
+     */
+    onClose(cb: (code: number, willReconnect: boolean) => void): () => void;
+    onRpcResponse(cb: (frame: RpcResponseFrame) => void): () => void;
+}
+declare function createRealtimeChannel(options: RealtimeChannelOptions): InternalRealtimeChannel;
+
+declare const DEFAULT_RPC_TIMEOUT_MS = 30000;
+interface RpcClient {
+    call<M extends RpcMethod>(method: M, params: RpcParamsMap[M], opts?: {
+        timeoutMs?: number;
+    }): Promise<RpcResultMap[M]>;
+}
+/**
+ * Request/response RPC over the realtime channel's socket. Requests made
+ * while the socket is closed are queued and flushed on (re)open — after the
+ * channel's identify/join replay, because the channel emits `onOpen` last.
+ */
+declare function createRpcClient(channel: InternalRealtimeChannel, options?: {
+    timeoutMs?: number;
+}): RpcClient;
 
-export { type CloudAdapter, CloudError, type CloudOptions, DEFAULT_CLOUD_ENDPOINT, type RealtimeChannel, type RealtimeChannelState, type RealtimeConnectOpts, type RealtimePresenceUser, cloud, createRealtimeChannel };
+export { type CloudAdapter, CloudError, type CloudOptions, DEFAULT_CLOUD_ENDPOINT, DEFAULT_RPC_TIMEOUT_MS, type IdentifyFrame, type InternalRealtimeChannel, type LeaveFrame, type PinArchivedFrame, RPC_METHODS, type RealtimeChannel, type RealtimeChannelState, type RealtimeConnectOpts, type RealtimePresenceUser, type ReportSubmitParams, type RpcClient, type RpcErrFrame, type RpcMethod, type RpcOkFrame, type RpcParamsMap, type RpcRequestFrame, type RpcResponseFrame, type RpcResultMap, SCREENSHOT_CHUNK_BYTES, SCREENSHOT_INLINE_MAX_BYTES, type ScreenshotChunkParams, cloud, createRealtimeChannel, createRpcClient, isRpcMethod, parseRpcResponseFrame };