@usero/sdk 0.3.0 → 0.3.2

package/dist/plugins/user-test.d.cts

@@ -0,0 +1,61 @@
+type FeedbackRating = 1 | 2 | 3 | 4;
+interface ScreenshotData {
+    fileName: string;
+    url: string;
+    fileSize: number;
+    width?: number;
+    height?: number;
+    mimeType: string;
+}
+interface FeedbackSubmission {
+    clientId: string;
+    rating?: FeedbackRating;
+    comment?: string;
+    userEmail?: string;
+    pageUrl: string;
+    pageTitle: string;
+    referrer?: string;
+    environment?: string;
+    screenshots?: ScreenshotData[];
+    metadata?: Record<string, unknown>;
+    replayEvents?: string;
+}
+
+interface PluginLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+interface PluginContext {
+    clientId: string;
+    baseUrl: string;
+    getStore: <T>() => T | undefined;
+    setStore: <T>(value: T) => void;
+    logger: PluginLogger;
+}
+interface UseroPlugin {
+    name: string;
+    onInit?: (ctx: PluginContext) => void | Promise<void>;
+    onFeedbackSubmit?: (ctx: PluginContext, submission: FeedbackSubmission) => Promise<Partial<FeedbackSubmission> | undefined> | Partial<FeedbackSubmission> | undefined;
+    onDestroy?: (ctx: PluginContext) => void;
+}
+
+interface UserTestOptions {
+    queryParam?: string;
+    chunkSeconds?: number;
+    apiUrl?: string;
+    testerName?: string;
+    hideIndicator?: boolean;
+}
+declare function getTestSlug(queryParam: string): string | null;
+declare function isMediaRecorderSupported(): boolean;
+declare function pickMimeType(): string | undefined;
+declare function userTest(options?: UserTestOptions): UseroPlugin;
+declare const __test__: {
+    getTestSlug: typeof getTestSlug;
+    pickMimeType: typeof pickMimeType;
+    isMediaRecorderSupported: typeof isMediaRecorderSupported;
+};
+
+export { type UserTestOptions, __test__, userTest };

package/dist/plugins/user-test.d.ts

@@ -0,0 +1,61 @@
+type FeedbackRating = 1 | 2 | 3 | 4;
+interface ScreenshotData {
+    fileName: string;
+    url: string;
+    fileSize: number;
+    width?: number;
+    height?: number;
+    mimeType: string;
+}
+interface FeedbackSubmission {
+    clientId: string;
+    rating?: FeedbackRating;
+    comment?: string;
+    userEmail?: string;
+    pageUrl: string;
+    pageTitle: string;
+    referrer?: string;
+    environment?: string;
+    screenshots?: ScreenshotData[];
+    metadata?: Record<string, unknown>;
+    replayEvents?: string;
+}
+
+interface PluginLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+interface PluginContext {
+    clientId: string;
+    baseUrl: string;
+    getStore: <T>() => T | undefined;
+    setStore: <T>(value: T) => void;
+    logger: PluginLogger;
+}
+interface UseroPlugin {
+    name: string;
+    onInit?: (ctx: PluginContext) => void | Promise<void>;
+    onFeedbackSubmit?: (ctx: PluginContext, submission: FeedbackSubmission) => Promise<Partial<FeedbackSubmission> | undefined> | Partial<FeedbackSubmission> | undefined;
+    onDestroy?: (ctx: PluginContext) => void;
+}
+
+interface UserTestOptions {
+    queryParam?: string;
+    chunkSeconds?: number;
+    apiUrl?: string;
+    testerName?: string;
+    hideIndicator?: boolean;
+}
+declare function getTestSlug(queryParam: string): string | null;
+declare function isMediaRecorderSupported(): boolean;
+declare function pickMimeType(): string | undefined;
+declare function userTest(options?: UserTestOptions): UseroPlugin;
+declare const __test__: {
+    getTestSlug: typeof getTestSlug;
+    pickMimeType: typeof pickMimeType;
+    isMediaRecorderSupported: typeof isMediaRecorderSupported;
+};
+
+export { type UserTestOptions, __test__, userTest };

package/dist/plugins/user-test.js

@@ -0,0 +1,525 @@
+// src/types.ts
+var DEFAULT_API_URL = "https://usero.io";
+
+// src/plugins/user-test.ts
+var DEFAULT_OPTIONS = {
+  queryParam: "usero_test",
+  chunkSeconds: 30,
+  apiUrl: DEFAULT_API_URL,
+  testerName: "",
+  hideIndicator: false
+};
+var TESTER_NAME_STORAGE_KEY = "usero:user-test:tester-name";
+var IDB_NAME = "usero-user-test";
+var IDB_STORE = "pending-chunks";
+function readTesterName(override) {
+  if (override) return override;
+  try {
+    const stored = window.localStorage?.getItem(TESTER_NAME_STORAGE_KEY);
+    if (stored && stored.trim()) return stored.trim().slice(0, 120);
+  } catch {
+  }
+  return void 0;
+}
+function getTestSlug(queryParam) {
+  if (typeof window === "undefined" || typeof window.location === "undefined") return null;
+  try {
+    const params = new URLSearchParams(window.location.search);
+    const slug = params.get(queryParam);
+    if (!slug) return null;
+    const cleaned = slug.trim().slice(0, 64);
+    if (!/^[a-z0-9-]+$/i.test(cleaned)) return null;
+    return cleaned;
+  } catch {
+    return null;
+  }
+}
+function isMediaRecorderSupported() {
+  return typeof window !== "undefined" && typeof window.MediaRecorder !== "undefined" && typeof navigator !== "undefined" && !!navigator.mediaDevices?.getUserMedia;
+}
+function pickMimeType() {
+  const candidates = ["audio/webm;codecs=opus", "audio/webm", "audio/ogg;codecs=opus", "audio/mp4"];
+  for (const candidate of candidates) {
+    if (typeof MediaRecorder !== "undefined" && MediaRecorder.isTypeSupported?.(candidate)) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function idbOpen() {
+  return new Promise((resolve) => {
+    if (typeof indexedDB === "undefined") {
+      resolve(null);
+      return;
+    }
+    try {
+      const req = indexedDB.open(IDB_NAME, 1);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains(IDB_STORE)) {
+          db.createObjectStore(IDB_STORE, { keyPath: "id" });
+        }
+      };
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => resolve(null);
+    } catch {
+      resolve(null);
+    }
+  });
+}
+async function idbStashChunk(chunk) {
+  const db = await idbOpen();
+  if (!db) return;
+  await new Promise((resolve) => {
+    try {
+      const tx = db.transaction(IDB_STORE, "readwrite");
+      tx.objectStore(IDB_STORE).put(chunk);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => resolve();
+      tx.onabort = () => resolve();
+    } catch {
+      resolve();
+    }
+  });
+  db.close();
+}
+async function idbDeleteChunk(id) {
+  const db = await idbOpen();
+  if (!db) return;
+  await new Promise((resolve) => {
+    try {
+      const tx = db.transaction(IDB_STORE, "readwrite");
+      tx.objectStore(IDB_STORE).delete(id);
+      tx.oncomplete = () => resolve();
+      tx.onerror = () => resolve();
+      tx.onabort = () => resolve();
+    } catch {
+      resolve();
+    }
+  });
+  db.close();
+}
+async function idbListChunks(sessionId) {
+  const db = await idbOpen();
+  if (!db) return [];
+  const items = await new Promise((resolve) => {
+    try {
+      const tx = db.transaction(IDB_STORE, "readonly");
+      const req = tx.objectStore(IDB_STORE).getAll();
+      req.onsuccess = () => {
+        const all = req.result ?? [];
+        resolve(all.filter((c) => c.sessionId === sessionId));
+      };
+      req.onerror = () => resolve([]);
+    } catch {
+      resolve([]);
+    }
+  });
+  db.close();
+  return items;
+}
+async function uploadChunkWithRetry(apiUrl, sessionId, index, blob, logger, maxAttempts = 5) {
+  const url = `${apiUrl.replace(/\/$/, "")}/api/user-test-sessions/${encodeURIComponent(sessionId)}/chunk?index=${index}`;
+  let attempt = 0;
+  while (attempt < maxAttempts) {
+    try {
+      const res = await fetch(url, {
+        method: "PUT",
+        body: blob,
+        headers: { "Content-Type": blob.type || "audio/webm" },
+        keepalive: blob.size <= 60 * 1024
+        // browsers cap keepalive bodies
+      });
+      if (res.ok) return true;
+      if (res.status >= 400 && res.status < 500 && res.status !== 408 && res.status !== 429) {
+        logger.error(`chunk ${index} rejected with ${res.status}`);
+        return false;
+      }
+    } catch (err) {
+      logger.warn(`chunk ${index} upload attempt ${attempt + 1} failed`, err);
+    }
+    attempt += 1;
+    const backoff = Math.min(15e3, 500 * 2 ** attempt) + Math.floor(Math.random() * 250);
+    await new Promise((resolve) => setTimeout(resolve, backoff));
+  }
+  return false;
+}
+function buildIndicator(host, store, onFinish) {
+  const root = host.attachShadow({ mode: "closed" });
+  const style = document.createElement("style");
+  style.textContent = `
+		:host { all: initial; }
+		.bar {
+			position: fixed;
+			bottom: calc(env(safe-area-inset-bottom, 0px) + 16px);
+			left: 50%;
+			transform: translateX(-50%);
+			display: inline-flex;
+			align-items: center;
+			gap: 10px;
+			padding: 8px 14px 8px 12px;
+			background: rgba(17, 17, 17, 0.78);
+			color: #fff;
+			border-radius: 999px;
+			font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+			font-size: 13px;
+			line-height: 1;
+			box-shadow: 0 8px 24px rgba(0, 0, 0, 0.18);
+			backdrop-filter: blur(8px);
+			-webkit-backdrop-filter: blur(8px);
+			z-index: 2147483646;
+			max-width: calc(100vw - 32px);
+		}
+		.dot {
+			width: 8px; height: 8px; border-radius: 50%;
+			background: #ef4444;
+			box-shadow: 0 0 0 0 rgba(239, 68, 68, 0.6);
+			animation: pulse 1.6s ease-out infinite;
+		}
+		.dot[data-state="no-audio"] { background: #fbbf24; animation: none; }
+		.dot[data-state="finishing"] { background: #fbbf24; animation: none; }
+		.dot[data-state="done"] { background: #10b981; animation: none; }
+		.dot[data-state="error"] { background: #ef4444; animation: none; }
+		.label { font-weight: 500; letter-spacing: 0.01em; }
+		.spacer { width: 1px; height: 16px; background: rgba(255,255,255,0.18); margin: 0 2px; }
+		.btn {
+			appearance: none; border: 0; background: rgba(255,255,255,0.12);
+			color: #fff; font: inherit; font-weight: 600;
+			padding: 6px 12px; border-radius: 999px; cursor: pointer;
+			transition: background 0.15s ease;
+		}
+		.btn:hover { background: rgba(255,255,255,0.22); }
+		.btn:focus-visible { outline: 2px solid #fff; outline-offset: 2px; }
+		.btn[disabled] { opacity: 0.5; cursor: progress; }
+		.thanks {
+			position: fixed; inset: 0;
+			display: grid; place-items: center;
+			background: rgba(15, 15, 17, 0.78);
+			backdrop-filter: blur(6px);
+			-webkit-backdrop-filter: blur(6px);
+			color: #fff;
+			font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+			z-index: 2147483647;
+			padding: 24px;
+			text-align: center;
+		}
+		.thanks-card {
+			background: #fff; color: #111;
+			border-radius: 16px; padding: 28px 24px;
+			max-width: 360px; width: 100%;
+			box-shadow: 0 20px 50px rgba(0,0,0,0.25);
+		}
+		.thanks h2 { margin: 0 0 8px; font-size: 20px; }
+		.thanks p { margin: 0; font-size: 14px; line-height: 1.45; color: #4b5563; }
+		.thanks .check {
+			width: 44px; height: 44px; border-radius: 50%;
+			background: #10b981; color: #fff;
+			display: grid; place-items: center;
+			margin: 0 auto 12px;
+			font-size: 22px;
+		}
+		@keyframes pulse {
+			0% { box-shadow: 0 0 0 0 rgba(239,68,68,0.55); }
+			70% { box-shadow: 0 0 0 10px rgba(239,68,68,0); }
+			100% { box-shadow: 0 0 0 0 rgba(239,68,68,0); }
+		}
+		@media (prefers-reduced-motion: reduce) {
+			.dot { animation: none; }
+		}
+	`;
+  const bar = document.createElement("div");
+  bar.className = "bar";
+  bar.setAttribute("role", "status");
+  bar.setAttribute("aria-live", "polite");
+  const dot = document.createElement("span");
+  dot.className = "dot";
+  dot.setAttribute("data-state", store.indicatorState);
+  const label = document.createElement("span");
+  label.className = "label";
+  label.textContent = "Recording";
+  const spacer = document.createElement("span");
+  spacer.className = "spacer";
+  const btn = document.createElement("button");
+  btn.type = "button";
+  btn.className = "btn";
+  btn.textContent = "Finish";
+  btn.addEventListener("click", onFinish);
+  bar.appendChild(dot);
+  bar.appendChild(label);
+  bar.appendChild(spacer);
+  bar.appendChild(btn);
+  root.appendChild(style);
+  root.appendChild(bar);
+  return root;
+}
+function renderIndicatorState(store) {
+  const root = store.indicatorRoot;
+  if (!root) return;
+  const dot = root.querySelector(".dot");
+  const label = root.querySelector(".label");
+  const btn = root.querySelector(".btn");
+  if (!(dot instanceof HTMLElement) || !(label instanceof HTMLElement) || !btn) return;
+  dot.setAttribute("data-state", store.indicatorState);
+  switch (store.indicatorState) {
+    case "recording":
+      label.textContent = "Recording";
+      btn.textContent = "Finish";
+      btn.disabled = false;
+      break;
+    case "no-audio":
+      label.textContent = "No mic, replay only";
+      btn.textContent = "Finish";
+      btn.disabled = false;
+      break;
+    case "finishing":
+      label.textContent = "Saving";
+      btn.textContent = "Saving";
+      btn.disabled = true;
+      break;
+    case "done":
+      label.textContent = "Saved";
+      btn.textContent = "Done";
+      btn.disabled = true;
+      break;
+    case "error":
+      label.textContent = "Save failed";
+      btn.textContent = "Retry";
+      btn.disabled = false;
+      break;
+  }
+}
+function showThanksScreen(root) {
+  const overlay = document.createElement("div");
+  overlay.className = "thanks";
+  overlay.innerHTML = `
+		<div class="thanks-card">
+			<div class="check" aria-hidden="true">&#10003;</div>
+			<h2>Thanks for testing</h2>
+			<p>Your session was saved. You can close this tab.</p>
+		</div>
+	`;
+  root.appendChild(overlay);
+}
+async function createSession(apiUrl, slug, testerName) {
+  try {
+    const res = await fetch(`${apiUrl.replace(/\/$/, "")}/api/user-test-sessions`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ slug, ...testerName ? { testerName } : {} })
+    });
+    if (!res.ok) return null;
+    const json = await res.json();
+    if (typeof json.sessionId !== "string" || typeof json.clientId !== "string") return null;
+    return { sessionId: json.sessionId, clientId: json.clientId };
+  } catch {
+    return null;
+  }
+}
+async function finaliseSession(apiUrl, sessionId, durationSeconds) {
+  try {
+    const res = await fetch(`${apiUrl.replace(/\/$/, "")}/api/user-test-sessions/${encodeURIComponent(sessionId)}/finalise`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ durationSeconds: Math.max(0, Math.round(durationSeconds)) }),
+      keepalive: true
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+async function flushPendingFromIdb(store, ctx) {
+  if (!store.sessionId) return;
+  const pending = await idbListChunks(store.sessionId);
+  for (const chunk of pending) {
+    const ok = await uploadChunkWithRetry(chunk.apiUrl, chunk.sessionId, chunk.chunkIndex, chunk.blob, ctx.logger, 3);
+    if (ok) await idbDeleteChunk(chunk.id);
+  }
+}
+function enqueueChunk(store, ctx, blob) {
+  if (store.cancelled || !store.sessionId || blob.size === 0) return;
+  const index = store.chunkIndex;
+  store.chunkIndex += 1;
+  store.pendingUploads += 1;
+  const sessionId = store.sessionId;
+  const apiUrl = store.options.apiUrl;
+  store.uploadQueue = store.uploadQueue.then(async () => {
+    const ok = await uploadChunkWithRetry(apiUrl, sessionId, index, blob, ctx.logger);
+    if (!ok) {
+      ctx.logger.warn(`chunk ${index} stashed for offline retry`);
+      await idbStashChunk({
+        id: `${sessionId}:${index}:${Date.now()}`,
+        sessionId,
+        apiUrl,
+        chunkIndex: index,
+        blob,
+        createdAt: Date.now()
+      });
+    }
+    store.pendingUploads -= 1;
+  });
+}
+async function startRecording(store, ctx) {
+  if (!isMediaRecorderSupported()) {
+    ctx.logger.warn("MediaRecorder not supported, continuing without audio");
+    store.indicatorState = "no-audio";
+    renderIndicatorState(store);
+    return;
+  }
+  let stream;
+  try {
+    stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+  } catch (err) {
+    ctx.logger.warn("mic permission denied or unavailable", err);
+    store.indicatorState = "no-audio";
+    renderIndicatorState(store);
+    return;
+  }
+  store.stream = stream;
+  const mimeType = pickMimeType();
+  let recorder;
+  try {
+    recorder = mimeType ? new MediaRecorder(stream, { mimeType }) : new MediaRecorder(stream);
+  } catch (err) {
+    ctx.logger.error("MediaRecorder construction failed", err);
+    stream.getTracks().forEach((t) => t.stop());
+    store.stream = null;
+    store.indicatorState = "no-audio";
+    renderIndicatorState(store);
+    return;
+  }
+  store.recorder = recorder;
+  recorder.addEventListener("dataavailable", (event) => {
+    if (event.data && event.data.size > 0) {
+      enqueueChunk(store, ctx, event.data);
+    }
+  });
+  recorder.addEventListener("error", (event) => {
+    ctx.logger.error("MediaRecorder error", event);
+  });
+  recorder.start(store.options.chunkSeconds * 1e3);
+}
+function stopRecording(store) {
+  const recorder = store.recorder;
+  if (recorder && recorder.state !== "inactive") {
+    try {
+      recorder.requestData();
+    } catch {
+    }
+    try {
+      recorder.stop();
+    } catch {
+    }
+  }
+  store.recorder = null;
+  if (store.stream) {
+    store.stream.getTracks().forEach((t) => t.stop());
+    store.stream = null;
+  }
+}
+async function finishFlow(store, ctx, opts) {
+  if (store.cancelled) return;
+  if (store.indicatorState === "finishing" || store.indicatorState === "done") return;
+  store.indicatorState = "finishing";
+  renderIndicatorState(store);
+  stopRecording(store);
+  await store.uploadQueue;
+  await flushPendingFromIdb(store, ctx);
+  const durationSeconds = (Date.now() - store.startedAt) / 1e3;
+  if (store.sessionId) {
+    const ok = await finaliseSession(store.options.apiUrl, store.sessionId, durationSeconds);
+    store.indicatorState = ok ? "done" : "error";
+  } else {
+    store.indicatorState = "error";
+  }
+  renderIndicatorState(store);
+  if (opts.showThanks && store.indicatorRoot && store.indicatorState === "done") {
+    showThanksScreen(store.indicatorRoot);
+  }
+}
+function userTest(options = {}) {
+  const merged = {
+    queryParam: options.queryParam ?? DEFAULT_OPTIONS.queryParam,
+    chunkSeconds: options.chunkSeconds ?? DEFAULT_OPTIONS.chunkSeconds,
+    apiUrl: options.apiUrl ?? DEFAULT_OPTIONS.apiUrl,
+    testerName: options.testerName ?? DEFAULT_OPTIONS.testerName,
+    hideIndicator: options.hideIndicator ?? DEFAULT_OPTIONS.hideIndicator
+  };
+  return {
+    name: "user-test",
+    onInit(ctx) {
+      if (typeof window === "undefined" || typeof document === "undefined") return;
+      const slug = getTestSlug(merged.queryParam);
+      if (!slug) return;
+      const apiUrl = merged.apiUrl || ctx.baseUrl || DEFAULT_API_URL;
+      const store = {
+        cancelled: false,
+        slug,
+        sessionId: null,
+        clientId: null,
+        recorder: null,
+        stream: null,
+        chunkIndex: 0,
+        uploadQueue: Promise.resolve(),
+        pendingUploads: 0,
+        startedAt: Date.now(),
+        indicator: null,
+        indicatorRoot: null,
+        indicatorState: "recording",
+        pageHideHandler: null,
+        options: { ...merged, apiUrl }
+      };
+      ctx.setStore(store);
+      const onFinish = () => {
+        void finishFlow(store, ctx, { showThanks: true });
+      };
+      if (!merged.hideIndicator) {
+        const host = document.createElement("div");
+        host.setAttribute("data-usero-user-test", "true");
+        document.body.appendChild(host);
+        store.indicator = host;
+        store.indicatorRoot = buildIndicator(host, store, onFinish);
+        renderIndicatorState(store);
+      }
+      const pageHide = () => {
+        void finishFlow(store, ctx, { showThanks: false });
+      };
+      store.pageHideHandler = pageHide;
+      window.addEventListener("pagehide", pageHide);
+      void (async () => {
+        const created = await createSession(apiUrl, slug, readTesterName(merged.testerName));
+        if (store.cancelled) return;
+        if (!created) {
+          ctx.logger.error("failed to create user-test session");
+          store.indicatorState = "error";
+          renderIndicatorState(store);
+          return;
+        }
+        store.sessionId = created.sessionId;
+        store.clientId = created.clientId;
+        await startRecording(store, ctx);
+        renderIndicatorState(store);
+      })();
+    },
+    onDestroy(ctx) {
+      const store = ctx.getStore();
+      if (!store) return;
+      store.cancelled = true;
+      if (store.pageHideHandler) {
+        window.removeEventListener("pagehide", store.pageHideHandler);
+        store.pageHideHandler = null;
+      }
+      stopRecording(store);
+      if (store.indicator && store.indicator.parentNode) {
+        store.indicator.parentNode.removeChild(store.indicator);
+      }
+      store.indicator = null;
+      store.indicatorRoot = null;
+    }
+  };
+}
+var __test__ = { getTestSlug, pickMimeType, isMediaRecorderSupported };
+
+export { __test__, userTest };
+//# sourceMappingURL=user-test.js.map
+//# sourceMappingURL=user-test.js.map