uidex 0.4.0 → 0.5.1

package/dist/cloud/index.d.cts

@@ -0,0 +1,82 @@
+import { ReportPayload, ReportResult, IngestConfig, ReportListResponse, PinRecord, ArchiveReason } from '@uidex/api-client';
+export { ArchiveReason, IngestConfig, PinRecord, ReportListRecord, ReportListResponse, ReportPayload, ReportResult } from '@uidex/api-client';
+
+interface UserIdentity {
+    id: string;
+    name?: string;
+    avatar?: string;
+}
+
+declare const DEFAULT_CLOUD_ENDPOINT = "https://app.uidex.dev";
+interface CloudOptions {
+    projectKey: string;
+    endpoint?: string;
+    fetch?: typeof fetch;
+    git?: {
+        branch?: string;
+        commit?: string;
+    };
+}
+declare class CloudError extends Error {
+    readonly status: number;
+    readonly retryAfter?: number;
+    readonly details?: unknown;
+    constructor(message: string, options: {
+        status: number;
+        retryAfter?: number;
+        details?: unknown;
+    });
+}
+type RealtimePresenceUser = {
+    userId: string;
+    name: string;
+    avatar: string | null;
+};
+type RealtimeChannelState = "connecting" | "connected" | "disconnected";
+interface RealtimeConnectOpts {
+    user: UserIdentity;
+    route: string;
+}
+interface RealtimeChannel {
+    readonly state: RealtimeChannelState;
+    connect(): void;
+    disconnect(): void;
+    joinRoute(route: string): void;
+    onPresence(cb: (users: RealtimePresenceUser[]) => void): () => void;
+    onPin(cb: (pin: PinRecord) => void): () => void;
+}
+interface CloudAdapter<TPayload = ReportPayload, TResult = ReportResult, TIntegrations = {
+    getConfig(): Promise<IngestConfig>;
+    getCachedConfig(): IngestConfig | null;
+}> {
+    readonly reports: {
+        submit(payload: TPayload): Promise<TResult>;
+        list?(opts?: {
+            page?: number;
+            limit?: number;
+        }): Promise<ReportListResponse>;
+    };
+    readonly integrations: TIntegrations;
+    readonly realtime: {
+        connect(opts: RealtimeConnectOpts): RealtimeChannel;
+    };
+    readonly pins: {
+        list(params: {
+            route?: string;
+            entities?: string;
+        }): Promise<PinRecord[]>;
+        archive(reportId: string, reason?: ArchiveReason): Promise<void>;
+    };
+}
+
+declare function cloud(options: CloudOptions): CloudAdapter;
+
+type RealtimeChannelOptions = {
+    /** Builds the WebSocket URL on each (re)connect attempt. Allows the caller to refresh `route` query params. */
+    buildUrl: () => string;
+    /** Optional WebSocket constructor override (testing). Defaults to `globalThis.WebSocket`. */
+    WebSocketImpl?: typeof WebSocket;
+};
+declare function createRealtimeChannel(options: RealtimeChannelOptions): RealtimeChannel;
+
+export { type CloudAdapter, CloudError, type CloudOptions, DEFAULT_CLOUD_ENDPOINT, type RealtimeChannel, type RealtimeChannelState, type RealtimeConnectOpts, type RealtimePresenceUser, cloud, createRealtimeChannel };

package/dist/cloud/index.d.ts

@@ -0,0 +1,82 @@
+import { ReportPayload, ReportResult, IngestConfig, ReportListResponse, PinRecord, ArchiveReason } from '@uidex/api-client';
+export { ArchiveReason, IngestConfig, PinRecord, ReportListRecord, ReportListResponse, ReportPayload, ReportResult } from '@uidex/api-client';
+
+interface UserIdentity {
+    id: string;
+    name?: string;
+    avatar?: string;
+}
+
+declare const DEFAULT_CLOUD_ENDPOINT = "https://app.uidex.dev";
+interface CloudOptions {
+    projectKey: string;
+    endpoint?: string;
+    fetch?: typeof fetch;
+    git?: {
+        branch?: string;
+        commit?: string;
+    };
+}
+declare class CloudError extends Error {
+    readonly status: number;
+    readonly retryAfter?: number;
+    readonly details?: unknown;
+    constructor(message: string, options: {
+        status: number;
+        retryAfter?: number;
+        details?: unknown;
+    });
+}
+type RealtimePresenceUser = {
+    userId: string;
+    name: string;
+    avatar: string | null;
+};
+type RealtimeChannelState = "connecting" | "connected" | "disconnected";
+interface RealtimeConnectOpts {
+    user: UserIdentity;
+    route: string;
+}
+interface RealtimeChannel {
+    readonly state: RealtimeChannelState;
+    connect(): void;
+    disconnect(): void;
+    joinRoute(route: string): void;
+    onPresence(cb: (users: RealtimePresenceUser[]) => void): () => void;
+    onPin(cb: (pin: PinRecord) => void): () => void;
+}
+interface CloudAdapter<TPayload = ReportPayload, TResult = ReportResult, TIntegrations = {
+    getConfig(): Promise<IngestConfig>;
+    getCachedConfig(): IngestConfig | null;
+}> {
+    readonly reports: {
+        submit(payload: TPayload): Promise<TResult>;
+        list?(opts?: {
+            page?: number;
+            limit?: number;
+        }): Promise<ReportListResponse>;
+    };
+    readonly integrations: TIntegrations;
+    readonly realtime: {
+        connect(opts: RealtimeConnectOpts): RealtimeChannel;
+    };
+    readonly pins: {
+        list(params: {
+            route?: string;
+            entities?: string;
+        }): Promise<PinRecord[]>;
+        archive(reportId: string, reason?: ArchiveReason): Promise<void>;
+    };
+}
+
+declare function cloud(options: CloudOptions): CloudAdapter;
+
+type RealtimeChannelOptions = {
+    /** Builds the WebSocket URL on each (re)connect attempt. Allows the caller to refresh `route` query params. */
+    buildUrl: () => string;
+    /** Optional WebSocket constructor override (testing). Defaults to `globalThis.WebSocket`. */
+    WebSocketImpl?: typeof WebSocket;
+};
+declare function createRealtimeChannel(options: RealtimeChannelOptions): RealtimeChannel;
+
+export { type CloudAdapter, CloudError, type CloudOptions, DEFAULT_CLOUD_ENDPOINT, type RealtimeChannel, type RealtimeChannelState, type RealtimeConnectOpts, type RealtimePresenceUser, cloud, createRealtimeChannel };

package/dist/cloud/index.js

@@ -1,3 +1,283 @@
+// src/cloud/client.ts
+import { createClient as createClient2, createConfig as createConfig2 } from "@hey-api/client-fetch";
+
+// ../api-client/src/client.gen.ts
+import {
+  createClient,
+  createConfig
+} from "@hey-api/client-fetch";
+var client = createClient(
+  createConfig({
+    baseUrl: "https://app.uidex.dev"
+  })
+);
+
+// ../api-client/src/sdk.gen.ts
+var submitReport = (options) => {
+  return (options.client ?? client).post({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/ingest",
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options?.headers
+    }
+  });
+};
+var getIngestConfig = (options) => {
+  return (options?.client ?? client).get({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/ingest/config",
+    ...options
+  });
+};
+var listIngestReports = (options) => {
+  return (options?.client ?? client).get({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/ingest/reports",
+    ...options
+  });
+};
+var listPins = (options) => {
+  return (options?.client ?? client).get({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/ingest/pins",
+    ...options
+  });
+};
+var archivePin = (options) => {
+  return (options.client ?? client).post({
+    security: [
+      {
+        scheme: "bearer",
+        type: "http"
+      }
+    ],
+    url: "/api/ingest/pins/archive",
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options?.headers
+    }
+  });
+};
+
+// src/cloud/realtime.ts
+var RECONNECT_INITIAL_MS = 1e3;
+var RECONNECT_MAX_MS = 3e4;
+var CLOSE_CODE_AUTH_FAILED = 4001;
+function emit(listeners, value) {
+  for (const cb of listeners) {
+    try {
+      cb(value);
+    } catch {
+    }
+  }
+}
+function resolveWebSocket(override) {
+  if (override) return override;
+  if (typeof globalThis !== "undefined" && typeof globalThis.WebSocket === "function") {
+    return globalThis.WebSocket;
+  }
+  throw new Error(
+    "uidex/cloud: global WebSocket is not available; pass a `WebSocketImpl` override"
+  );
+}
+function createRealtimeChannel(options) {
+  const WS = resolveWebSocket(options.WebSocketImpl);
+  const presenceListeners = /* @__PURE__ */ new Set();
+  const pinListeners = /* @__PURE__ */ new Set();
+  let ws = null;
+  let state = "disconnected";
+  let disposed = false;
+  let reconnectAttempts = 0;
+  let reconnectTimer = null;
+  function clearReconnectTimer() {
+    if (reconnectTimer !== null) {
+      clearTimeout(reconnectTimer);
+      reconnectTimer = null;
+    }
+  }
+  function scheduleReconnect() {
+    if (disposed) return;
+    const delay = Math.min(
+      RECONNECT_INITIAL_MS * 2 ** reconnectAttempts,
+      RECONNECT_MAX_MS
+    );
+    reconnectAttempts += 1;
+    state = "connecting";
+    clearReconnectTimer();
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null;
+      openSocket();
+    }, delay);
+  }
+  function handleMessage(event) {
+    if (typeof event.data !== "string") return;
+    let parsed;
+    try {
+      parsed = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+    if (!parsed || typeof parsed !== "object") return;
+    const msg = parsed;
+    if (msg.type === "presence") {
+      const p = msg;
+      if (!Array.isArray(p.users)) return;
+      const users = [];
+      for (const raw of p.users) {
+        if (!raw || typeof raw !== "object") continue;
+        const u = raw;
+        if (typeof u.userId !== "string" || typeof u.name !== "string") continue;
+        users.push({
+          userId: u.userId,
+          name: u.name,
+          avatar: typeof u.avatar === "string" ? u.avatar : null
+        });
+      }
+      emit(presenceListeners, users);
+      return;
+    }
+    if (msg.type === "pin") {
+      const p = msg;
+      if (typeof p.feedbackId !== "string" || !p.elementRef || typeof p.elementRef !== "object" || typeof p.elementRef.kind !== "string" || typeof p.elementRef.id !== "string" || !p.author || typeof p.author !== "object" || typeof p.body !== "string" || typeof p.reportType !== "string" || typeof p.reportSeverity !== "string" || typeof p.createdAt !== "string") {
+        return;
+      }
+      const author = p.author;
+      const elRef = p.elementRef;
+      const pin = {
+        id: p.feedbackId,
+        entity: `${elRef.kind}:${elRef.id}`,
+        reporter: {
+          name: typeof author.name === "string" ? author.name : void 0,
+          email: typeof author.email === "string" ? author.email : void 0
+        },
+        body: p.body,
+        type: p.reportType,
+        severity: p.reportSeverity,
+        status: "open",
+        createdAt: p.createdAt,
+        url: ""
+      };
+      emit(pinListeners, pin);
+      return;
+    }
+  }
+  function openSocket() {
+    if (disposed) return;
+    state = "connecting";
+    let url;
+    try {
+      url = options.buildUrl();
+    } catch {
+      state = "disconnected";
+      return;
+    }
+    let socket;
+    try {
+      socket = new WS(url);
+    } catch {
+      scheduleReconnect();
+      return;
+    }
+    ws = socket;
+    socket.addEventListener("open", () => {
+      if (ws !== socket) return;
+      state = "connected";
+      reconnectAttempts = 0;
+    });
+    socket.addEventListener("message", (event) => {
+      if (ws !== socket) return;
+      handleMessage(event);
+    });
+    socket.addEventListener("close", (event) => {
+      if (ws !== socket) return;
+      ws = null;
+      const code = event.code;
+      if (disposed || code === CLOSE_CODE_AUTH_FAILED) {
+        state = "disconnected";
+        return;
+      }
+      scheduleReconnect();
+    });
+    socket.addEventListener("error", () => {
+    });
+  }
+  function connect() {
+    if (disposed) {
+      disposed = false;
+    }
+    if (ws) return;
+    if (state === "connecting") return;
+    reconnectAttempts = 0;
+    openSocket();
+  }
+  function disconnect() {
+    disposed = true;
+    clearReconnectTimer();
+    state = "disconnected";
+    if (ws) {
+      try {
+        ws.close(1e3);
+      } catch {
+      }
+      ws = null;
+    }
+  }
+  function joinRoute(route) {
+    emit(presenceListeners, []);
+    if (ws && ws.readyState === WS.OPEN) {
+      try {
+        ws.send(JSON.stringify({ type: "join", route }));
+      } catch {
+      }
+    }
+  }
+  function onPresence(cb) {
+    presenceListeners.add(cb);
+    return () => {
+      presenceListeners.delete(cb);
+    };
+  }
+  function onPin(cb) {
+    pinListeners.add(cb);
+    return () => {
+      pinListeners.delete(cb);
+    };
+  }
+  return {
+    get state() {
+      return state;
+    },
+    connect,
+    disconnect,
+    joinRoute,
+    onPresence,
+    onPin
+  };
+}
+
 // src/cloud/types.ts
 var DEFAULT_CLOUD_ENDPOINT = "https://app.uidex.dev";
 var CloudError = class extends Error {
@@ -14,18 +294,18 @@ var CloudError = class extends Error {
 };
 
 // src/cloud/client.ts
-function resolveFetch(override) {
-  if (override) return override;
-  if (typeof globalThis !== "undefined" && typeof globalThis.fetch === "function") {
-    return globalThis.fetch.bind(globalThis);
-  }
-  throw new Error(
-    "uidex/cloud: global fetch is not available; pass a `fetch` override"
-  );
-}
 function trimEndpoint(endpoint) {
   return endpoint.endsWith("/") ? endpoint.slice(0, -1) : endpoint;
 }
+function unwrap(result) {
+  if (result.error !== void 0 || !result.data) {
+    const status = result.response.status;
+    const retryAfter = status === 429 ? parseRetryAfter(result.response.headers.get("Retry-After")) : void 0;
+    const msg = result.error && typeof result.error === "object" && "error" in result.error && typeof result.error.error === "string" ? result.error.error : `Request failed (${status})`;
+    throw new CloudError(msg, { status, retryAfter, details: result.error });
+  }
+  return result.data;
+}
 function parseRetryAfter(header) {
   if (!header) return void 0;
   const seconds = Number(header);
@@ -37,21 +317,6 @@ function parseRetryAfter(header) {
   }
   return void 0;
 }
-async function readBody(response) {
-  const text = await response.text();
-  if (!text) return void 0;
-  try {
-    return JSON.parse(text);
-  } catch {
-    return text;
-  }
-}
-function errorMessage(body, fallback) {
-  if (body && typeof body === "object" && "error" in body && typeof body.error === "string") {
-    return body.error;
-  }
-  return fallback;
-}
 function cloud(options) {
   let cachedConfig = null;
   let resolvedConfig = null;
@@ -60,54 +325,34 @@ function cloud(options) {
     throw new Error("uidex/cloud: `projectKey` is required");
   }
   const endpoint = trimEndpoint(options.endpoint ?? DEFAULT_CLOUD_ENDPOINT);
-  const fetchImpl = resolveFetch(options.fetch);
-  const authHeader = `Bearer ${projectKey}`;
+  const git = options.git;
+  const apiClient = createClient2(
+    createConfig2({
+      baseUrl: endpoint,
+      ...options.fetch ? { fetch: options.fetch } : {},
+      headers: { Authorization: `Bearer ${projectKey}` }
+    })
+  );
   async function submit(payload) {
-    const response = await fetchImpl(`${endpoint}/api/ingest`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: authHeader
-      },
-      body: JSON.stringify(payload)
+    const enriched = git?.branch || git?.commit ? {
+      ...payload,
+      context: {
+        ...payload.context,
+        git: payload.context?.git ?? {
+          branch: git.branch,
+          commit: git.commit
+        }
+      }
+    } : payload;
+    const result = await submitReport({
+      client: apiClient,
+      body: enriched
     });
-    const body = await readBody(response);
-    if (!response.ok) {
-      const retryAfter = response.status === 429 ? parseRetryAfter(response.headers.get("Retry-After")) : void 0;
-      throw new CloudError(
-        errorMessage(body, `Feedback submission failed (${response.status})`),
-        { status: response.status, retryAfter, details: body }
-      );
-    }
-    if (!body || typeof body !== "object") {
-      throw new CloudError("Feedback submission returned an empty response", {
-        status: response.status
-      });
-    }
-    return body;
+    return unwrap(result);
   }
   async function fetchConfig() {
-    const response = await fetchImpl(`${endpoint}/api/ingest/config`, {
-      method: "GET",
-      headers: {
-        Accept: "application/json",
-        Authorization: authHeader
-      }
-    });
-    const body = await readBody(response);
-    if (!response.ok) {
-      const retryAfter = response.status === 429 ? parseRetryAfter(response.headers.get("Retry-After")) : void 0;
-      throw new CloudError(
-        errorMessage(body, `Ingest config request failed (${response.status})`),
-        { status: response.status, retryAfter, details: body }
-      );
-    }
-    if (!body || typeof body !== "object") {
-      throw new CloudError("Ingest config returned an empty response", {
-        status: response.status
-      });
-    }
-    return body;
+    const result = await getIngestConfig({ client: apiClient });
+    return unwrap(result);
   }
   function startFetch() {
     const promise = fetchConfig();
@@ -127,14 +372,74 @@ function cloud(options) {
   function getCachedConfig() {
     return resolvedConfig;
   }
+  function realtimeUrl(route, user) {
+    const httpToWs = endpoint.replace(/^http:/, "ws:").replace(/^https:/, "wss:");
+    const params = new URLSearchParams();
+    params.set("key", projectKey);
+    params.set("route", route);
+    params.set("userId", user.id);
+    if (user.name) params.set("name", user.name);
+    if (user.avatar) params.set("avatar", user.avatar);
+    return `${httpToWs}/ws?${params.toString()}`;
+  }
+  function connectRealtime(opts) {
+    if (!opts || !opts.user || typeof opts.user.id !== "string") {
+      throw new TypeError("uidex/cloud: realtime.connect requires `user.id`");
+    }
+    let currentRoute = opts.route;
+    const channel = createRealtimeChannel({
+      buildUrl: () => realtimeUrl(currentRoute, opts.user)
+    });
+    const originalJoinRoute = channel.joinRoute;
+    const wrapped = {
+      get state() {
+        return channel.state;
+      },
+      connect: () => channel.connect(),
+      disconnect: () => channel.disconnect(),
+      joinRoute: (route) => {
+        currentRoute = route;
+        originalJoinRoute(route);
+      },
+      onPresence: (cb) => channel.onPresence(cb),
+      onPin: (cb) => channel.onPin(cb)
+    };
+    channel.connect();
+    return wrapped;
+  }
+  async function listPins2(params) {
+    const result = await listPins({
+      client: apiClient,
+      query: params
+    });
+    const data = unwrap(result);
+    return data.pins;
+  }
+  async function archivePin2(reportId, reason) {
+    const result = await archivePin({
+      client: apiClient,
+      body: { reportId, ...reason ? { reason } : {} }
+    });
+    unwrap(result);
+  }
+  async function listReports(opts) {
+    const result = await listIngestReports({
+      client: apiClient,
+      query: opts
+    });
+    return unwrap(result);
+  }
   return {
-    feedback: { submit },
-    integrations: { getConfig, getCachedConfig }
+    reports: { submit, list: listReports },
+    integrations: { getConfig, getCachedConfig },
+    realtime: { connect: connectRealtime },
+    pins: { list: listPins2, archive: archivePin2 }
   };
 }
 export {
   CloudError,
   DEFAULT_CLOUD_ENDPOINT,
-  cloud
+  cloud,
+  createRealtimeChannel
 };
 //# sourceMappingURL=index.js.map