@getdevteam/analytics-web 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,42 @@
+# @getdevteam/analytics-web
+
+Browser SDK for the [DevTeam Analytics & Logging Platform](https://github.com/getdevteam-ai/analytics).
+Drop it into any browser app - plain JS, Astro, Vue, Svelte, or React without the hooks - to send analytics events and logs.
+Building with React and want a `useAnalytics()` hook? Pair this with [`@getdevteam/analytics-react`](https://www.npmjs.com/package/@getdevteam/analytics-react).
+
+## Install
+
+```sh
+npm install @getdevteam/analytics-web
+```
+
+## Use
+
+```ts
+import { createAnalytics } from "@getdevteam/analytics-web";
+
+const analytics = createAnalytics({
+  key: "dtp_your_public_key",
+  host: "https://ingest.analytics.getdevteam.ai",
+  trackPageviews: true,   // auto-send a pageview on every route change
+});
+
+analytics.identify("user_123", { plan: "pro" });          // who the user is
+analytics.track("checkout_completed", { amount: 4200 });  // something that happened
+analytics.log.error("payment gateway timed out", { gateway: "stripe" });
+```
+
+Auto-captures uncaught errors and unhandled promise rejections (turn off with `autoCaptureErrors: false`), and flushes queued events when the page is hidden or closed so nothing is lost on navigation.
+
+## User feedback
+
+Set `allowUserFeedback: true` to render a floating feedback button (isolated in a Shadow DOM host, loaded lazily): the user gets a screenshot of the page, drawing tools, and a comment box, and the result lands in the platform's feedback inbox.
+`analytics.showFeedback()` opens the overlay programmatically; it is a no-op while the feature is off or unavailable.
+Customize with `feedback: { colors, accentColor, buttonLabel, title, submitLabel, commentPlaceholder, successMessage, position, zIndex, pixelRatio }`.
+
+The screenshot is a DOM-to-canvas render: cross-origin iframes, tainted canvases, and video frames come out blank or make the capture fail, and a failed capture falls back to comment-only feedback instead of breaking the app.
+See the [SDK README](https://github.com/getdevteam-ai/analytics/tree/main/src/sdk#user-feedback) for the full option table and capture boundary.
+
+You need a public ingest key (`dtp_...`) and the ingest host URL for your environment - see [Getting a key](https://github.com/getdevteam-ai/analytics/tree/main/src/sdk#getting-a-key) in the full SDK docs.
+
+Full client API, config options, and release process: [src/sdk README](https://github.com/getdevteam-ai/analytics/tree/main/src/sdk).

package/dist/feedback-W5PGVRNZ.js

@@ -0,0 +1,651 @@
+// src/feedback/index.ts
+import { uuidV7 } from "@getdevteam/analytics-core";
+
+// src/feedback/capture.ts
+import { toCanvas } from "html-to-image";
+async function captureViewport(exclude, pixelRatio) {
+  return toCanvas(document.documentElement, {
+    filter: (node) => node !== exclude,
+    pixelRatio,
+    width: window.innerWidth,
+    height: window.innerHeight,
+    style: {
+      transform: `translate(${-window.scrollX}px, ${-window.scrollY}px)`
+    }
+  });
+}
+
+// src/feedback/exportImage.ts
+var JPEG_QUALITY = 0.85;
+var DOWNSCALE_FACTOR = 0.7;
+var MIN_EXPORT_DIMENSION = 200;
+function drawStrokes(ctx, strokes) {
+  for (const stroke of strokes) {
+    const [first, ...rest] = stroke.points;
+    if (!first) continue;
+    ctx.strokeStyle = stroke.color;
+    ctx.lineWidth = stroke.width;
+    ctx.lineCap = "round";
+    ctx.lineJoin = "round";
+    ctx.beginPath();
+    ctx.moveTo(first.x, first.y);
+    if (rest.length === 0) ctx.lineTo(first.x, first.y);
+    for (const point of rest) ctx.lineTo(point.x, point.y);
+    ctx.stroke();
+  }
+}
+async function exportAnnotatedImage(source, strokes, options) {
+  try {
+    const composed = compose(source, strokes);
+    if (!composed) return null;
+    const png = await encode(composed, "image/png");
+    if (png && png.size <= options.maxBytes) {
+      return { base64: await blobToBase64(png), contentType: "image/png" };
+    }
+    let canvas = composed;
+    let jpeg = await encode(canvas, "image/jpeg", JPEG_QUALITY);
+    while (jpeg && jpeg.size > options.maxBytes && Math.min(canvas.width, canvas.height) * DOWNSCALE_FACTOR >= MIN_EXPORT_DIMENSION) {
+      const smaller = downscale(canvas, DOWNSCALE_FACTOR);
+      if (!smaller) break;
+      canvas = smaller;
+      jpeg = await encode(canvas, "image/jpeg", JPEG_QUALITY);
+    }
+    if (jpeg && jpeg.size <= options.maxBytes) {
+      return { base64: await blobToBase64(jpeg), contentType: "image/jpeg" };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function compose(source, strokes) {
+  const canvas = document.createElement("canvas");
+  canvas.width = source.width;
+  canvas.height = source.height;
+  const ctx = get2dContext(canvas);
+  if (!ctx || canvas.width === 0 || canvas.height === 0) return null;
+  ctx.fillStyle = "#ffffff";
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+  ctx.drawImage(source, 0, 0);
+  drawStrokes(ctx, strokes);
+  return canvas;
+}
+function downscale(source, factor) {
+  const canvas = document.createElement("canvas");
+  canvas.width = Math.max(1, Math.round(source.width * factor));
+  canvas.height = Math.max(1, Math.round(source.height * factor));
+  const ctx = get2dContext(canvas);
+  if (!ctx) return null;
+  ctx.drawImage(source, 0, 0, canvas.width, canvas.height);
+  return canvas;
+}
+function get2dContext(canvas) {
+  try {
+    return canvas.getContext("2d");
+  } catch {
+    return null;
+  }
+}
+function encode(canvas, type, quality) {
+  return new Promise((resolve) => {
+    try {
+      canvas.toBlob((blob) => resolve(blob), type, quality);
+    } catch {
+      resolve(null);
+    }
+  });
+}
+async function blobToBase64(blob) {
+  const bytes = new Uint8Array(await blob.arrayBuffer());
+  let binary = "";
+  const chunkSize = 32768;
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+  }
+  return btoa(binary);
+}
+
+// src/feedback/strokes.ts
+function createStrokeStore() {
+  const strokes = [];
+  let active;
+  return {
+    begin(color, width, point) {
+      if (active) return;
+      active = { points: [point], color, width };
+      strokes.push(active);
+    },
+    extend(point) {
+      active?.points.push(point);
+    },
+    end() {
+      active = void 0;
+    },
+    undo() {
+      if (active) return;
+      strokes.pop();
+    },
+    clear() {
+      if (active) return;
+      strokes.length = 0;
+    },
+    list: () => strokes,
+    isDrawing: () => active !== void 0
+  };
+}
+function mapToImagePoint(clientX, clientY, rect, imageWidth, imageHeight) {
+  const scaleX = rect.width > 0 && imageWidth > 0 ? imageWidth / rect.width : 1;
+  const scaleY = rect.height > 0 && imageHeight > 0 ? imageHeight / rect.height : 1;
+  return { x: (clientX - rect.left) * scaleX, y: (clientY - rect.top) * scaleY };
+}
+
+// src/feedback/index.ts
+var DEFAULT_COLORS = ["#f44336", "#4caf50", "#2196f3", "#ffeb3b"];
+var DEFAULT_ACCENT = "#5b9cf5";
+var DEFAULT_Z_INDEX = 2147483e3;
+var PEN_WIDTH = 5;
+var MAX_SCREENSHOT_BYTES = 5 * 1024 * 1024;
+var MAX_TEXT_LENGTH = 1e4;
+var MAX_PAGE_URL_LENGTH = 2048;
+var SUCCESS_CLOSE_DELAY_MS = 1600;
+var defaultDeps = {
+  capture: captureViewport,
+  exportAnnotated: exportAnnotatedImage
+};
+function mountFeedback(config, deps = defaultDeps) {
+  const options = config.options;
+  const colors = options.colors && options.colors.length > 0 ? options.colors : DEFAULT_COLORS;
+  const accent = options.accentColor ?? DEFAULT_ACCENT;
+  const pixelRatio = options.pixelRatio ?? Math.min(typeof devicePixelRatio === "number" && devicePixelRatio > 0 ? devicePixelRatio : 1, 2);
+  let destroyed = false;
+  let overlayOpen = false;
+  let overlaySession = 0;
+  let capturing = false;
+  let sending = false;
+  let draftFeedbackId = uuidV7();
+  let sourceCanvas;
+  let activeColor = colors[0] ?? DEFAULT_COLORS[0];
+  let penWidth = PEN_WIDTH;
+  let previousBodyOverflow;
+  let closeTimer;
+  let drawContext;
+  const strokes = createStrokeStore();
+  const report = (error2) => {
+    try {
+      config.onError(error2);
+    } catch {
+    }
+  };
+  const safely = (fn) => {
+    try {
+      fn();
+    } catch (error2) {
+      report(error2);
+    }
+  };
+  const host = document.createElement("div");
+  host.setAttribute("data-devteam-feedback", "");
+  const shadow = host.attachShadow({ mode: "open" });
+  const style = document.createElement("style");
+  style.textContent = buildStyles(options, accent);
+  const container = element("div", "container");
+  const fab = element("button", "fab");
+  fab.type = "button";
+  fab.textContent = options.buttonLabel ?? "Feedback";
+  const overlay = element("div", "overlay");
+  overlay.hidden = true;
+  const backdrop = element("div", "backdrop");
+  const panel = element("div", "panel");
+  panel.setAttribute("role", "dialog");
+  panel.setAttribute("aria-modal", "true");
+  const header = element("div", "header");
+  const title = element("div", "title");
+  title.textContent = options.title ?? "Send feedback";
+  const closeButton = element("button", "close");
+  closeButton.type = "button";
+  closeButton.setAttribute("aria-label", "Close");
+  closeButton.textContent = "\xD7";
+  header.append(title, closeButton);
+  const preview = element("div", "preview");
+  const drawCanvas = document.createElement("canvas");
+  drawCanvas.className = "draw";
+  preview.appendChild(drawCanvas);
+  const tools = element("div", "tools");
+  const swatches = colors.map((color) => {
+    const swatch = element("button", "swatch");
+    swatch.type = "button";
+    swatch.style.background = color;
+    swatch.setAttribute("aria-label", `Pen color ${color}`);
+    swatch.addEventListener("click", () => safely(() => selectColor(color)));
+    tools.appendChild(swatch);
+    return { color, swatch };
+  });
+  const undoButton = element("button", "tool undo");
+  undoButton.type = "button";
+  undoButton.textContent = "Undo";
+  const clearButton = element("button", "tool clear");
+  clearButton.type = "button";
+  clearButton.textContent = "Clear";
+  tools.append(undoButton, clearButton);
+  const comment = document.createElement("textarea");
+  comment.className = "comment";
+  comment.placeholder = options.commentPlaceholder ?? "What went wrong, or what could be better?";
+  comment.maxLength = MAX_TEXT_LENGTH;
+  const error = element("div", "error");
+  error.hidden = true;
+  const success = element("div", "success");
+  success.hidden = true;
+  success.textContent = options.successMessage ?? "Thanks for the feedback!";
+  const actions = element("div", "actions");
+  const cancelButton = element("button", "cancel");
+  cancelButton.type = "button";
+  cancelButton.textContent = "Cancel";
+  const submitButton = element("button", "submit");
+  submitButton.type = "button";
+  submitButton.textContent = options.submitLabel ?? "Send";
+  actions.append(cancelButton, submitButton);
+  panel.append(header, preview, tools, comment, error, success, actions);
+  overlay.append(backdrop, panel);
+  container.append(fab, overlay);
+  shadow.append(style, container);
+  if (document.body) {
+    document.body.appendChild(host);
+  } else {
+    document.addEventListener(
+      "DOMContentLoaded",
+      () => {
+        if (!destroyed) document.body?.appendChild(host);
+      },
+      { once: true }
+    );
+  }
+  function selectColor(color) {
+    activeColor = color;
+    for (const entry of swatches) {
+      entry.swatch.classList.toggle("active", entry.color === color);
+    }
+  }
+  selectColor(activeColor);
+  function context2d() {
+    if (drawContext === void 0) {
+      try {
+        drawContext = drawCanvas.getContext("2d");
+      } catch {
+        drawContext = null;
+      }
+    }
+    return drawContext;
+  }
+  function repaint() {
+    const ctx = context2d();
+    if (!ctx) return;
+    ctx.clearRect(0, 0, drawCanvas.width, drawCanvas.height);
+    drawStrokes(ctx, strokes.list());
+  }
+  function pointFromEvent(event) {
+    const { clientX, clientY } = event;
+    if (typeof clientX !== "number" || typeof clientY !== "number") return void 0;
+    const rect = drawCanvas.getBoundingClientRect();
+    return mapToImagePoint(clientX, clientY, rect, drawCanvas.width, drawCanvas.height);
+  }
+  function withPointerCapture(event, action) {
+    const pointerId = event.pointerId;
+    if (typeof pointerId !== "number") return;
+    const method = action === "set" ? drawCanvas.setPointerCapture : drawCanvas.releasePointerCapture;
+    if (typeof method !== "function") return;
+    try {
+      method.call(drawCanvas, pointerId);
+    } catch {
+    }
+  }
+  const onPointerDown = (event) => safely(() => {
+    if (!sourceCanvas || sending) return;
+    const point = pointFromEvent(event);
+    if (!point) return;
+    if (typeof event.preventDefault === "function") event.preventDefault();
+    withPointerCapture(event, "set");
+    strokes.begin(activeColor, penWidth, point);
+    repaint();
+  });
+  const onPointerMove = (event) => safely(() => {
+    if (!strokes.isDrawing()) return;
+    const point = pointFromEvent(event);
+    if (!point) return;
+    strokes.extend(point);
+    repaint();
+  });
+  const onPointerEnd = (event) => safely(() => {
+    withPointerCapture(event, "release");
+    strokes.end();
+  });
+  drawCanvas.addEventListener("pointerdown", onPointerDown);
+  drawCanvas.addEventListener("pointermove", onPointerMove);
+  drawCanvas.addEventListener("pointerup", onPointerEnd);
+  drawCanvas.addEventListener("pointercancel", onPointerEnd);
+  drawCanvas.addEventListener("pointerleave", onPointerEnd);
+  shadow.addEventListener("pointerup", onPointerEnd);
+  undoButton.addEventListener(
+    "click",
+    () => safely(() => {
+      strokes.undo();
+      repaint();
+    })
+  );
+  clearButton.addEventListener(
+    "click",
+    () => safely(() => {
+      strokes.clear();
+      repaint();
+    })
+  );
+  const onKeyDown = (event) => {
+    if (event.key === "Escape") safely(close);
+  };
+  function lockScroll() {
+    if (previousBodyOverflow !== void 0) return;
+    previousBodyOverflow = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+  }
+  function unlockScroll() {
+    if (previousBodyOverflow === void 0) return;
+    document.body.style.overflow = previousBodyOverflow;
+    previousBodyOverflow = void 0;
+  }
+  function setError(message) {
+    error.hidden = message === void 0;
+    error.textContent = message ?? "";
+  }
+  function setFormVisible(visible) {
+    const hasPreview = sourceCanvas !== void 0;
+    preview.hidden = !visible || !hasPreview;
+    tools.hidden = !visible || !hasPreview;
+    comment.hidden = !visible;
+    actions.hidden = !visible;
+  }
+  function showOverlay(canvas) {
+    overlaySession += 1;
+    draftFeedbackId = uuidV7();
+    sourceCanvas = canvas;
+    strokes.end();
+    strokes.clear();
+    comment.value = "";
+    setError(void 0);
+    success.hidden = true;
+    submitButton.disabled = false;
+    if (canvas) {
+      canvas.classList.add("shot");
+      preview.insertBefore(canvas, drawCanvas);
+      drawCanvas.width = canvas.width;
+      drawCanvas.height = canvas.height;
+      penWidth = PEN_WIDTH * (pixelRatio > 0 ? pixelRatio : 1);
+      repaint();
+    }
+    selectColor(colors[0] ?? DEFAULT_COLORS[0]);
+    setFormVisible(true);
+    overlay.hidden = false;
+    overlayOpen = true;
+    lockScroll();
+    document.addEventListener("keydown", onKeyDown);
+  }
+  function close() {
+    if (!overlayOpen) return;
+    overlaySession += 1;
+    overlayOpen = false;
+    overlay.hidden = true;
+    document.removeEventListener("keydown", onKeyDown);
+    unlockScroll();
+    if (closeTimer !== void 0) {
+      clearTimeout(closeTimer);
+      closeTimer = void 0;
+    }
+    sending = false;
+    if (sourceCanvas) {
+      sourceCanvas.remove();
+      sourceCanvas = void 0;
+    }
+    strokes.end();
+    strokes.clear();
+  }
+  function open() {
+    if (destroyed || overlayOpen || capturing) return;
+    capturing = true;
+    void Promise.resolve().then(() => deps.capture(host, pixelRatio)).then(
+      (canvas) => {
+        capturing = false;
+        if (destroyed) return;
+        showOverlay(canvas);
+      },
+      (captureError) => {
+        capturing = false;
+        if (destroyed) return;
+        report(captureError);
+        showOverlay(void 0);
+      }
+    );
+  }
+  function buildBody(text, screenshot) {
+    const body = {
+      feedback_id: draftFeedbackId,
+      text: text.slice(0, MAX_TEXT_LENGTH)
+    };
+    if (screenshot) {
+      body.screenshot = screenshot.base64;
+      body.screenshot_content_type = screenshot.contentType;
+    }
+    const distinctId = config.getDistinctId();
+    if (distinctId) body.distinct_id = distinctId;
+    const sessionId = config.getSessionId();
+    if (sessionId) body.session_id = sessionId;
+    if (typeof location !== "undefined" && location.href) {
+      body.page_url = location.href.slice(0, MAX_PAGE_URL_LENGTH);
+    }
+    body.context = config.getContext();
+    return JSON.stringify(body);
+  }
+  async function submit() {
+    if (sending || !overlayOpen) return;
+    const text = comment.value.trim();
+    if (text.length === 0) {
+      setError("Please add a short comment before sending.");
+      return;
+    }
+    const session = overlaySession;
+    const sameSession = () => !destroyed && overlayOpen && overlaySession === session;
+    sending = true;
+    submitButton.disabled = true;
+    setError(void 0);
+    try {
+      let screenshot = null;
+      if (sourceCanvas) {
+        screenshot = await deps.exportAnnotated(sourceCanvas, strokes.list(), {
+          maxBytes: MAX_SCREENSHOT_BYTES
+        });
+      }
+      if (!config.fetch) throw new Error("fetch is not available in this environment");
+      const response = await config.fetch(config.url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-DevTeam-Key": config.key },
+        body: buildBody(text, screenshot)
+      });
+      if (!sameSession()) return;
+      if (response.ok) {
+        setFormVisible(false);
+        success.hidden = false;
+        closeTimer = setTimeout(() => safely(close), SUCCESS_CLOSE_DELAY_MS);
+      } else {
+        setError("Could not send feedback. Please try again.");
+      }
+    } catch (submitError) {
+      report(submitError);
+      if (sameSession()) setError("Could not send feedback. Please try again.");
+    } finally {
+      if (overlaySession === session) {
+        sending = false;
+        submitButton.disabled = false;
+      }
+    }
+  }
+  fab.addEventListener("click", () => safely(open));
+  closeButton.addEventListener("click", () => safely(close));
+  cancelButton.addEventListener("click", () => safely(close));
+  backdrop.addEventListener("click", () => safely(close));
+  submitButton.addEventListener("click", () => safely(() => void submit()));
+  return {
+    open: () => safely(open),
+    destroy: () => {
+      if (destroyed) return;
+      destroyed = true;
+      safely(() => {
+        close();
+        document.removeEventListener("keydown", onKeyDown);
+        host.remove();
+      });
+    }
+  };
+}
+function element(tag, className) {
+  const node = document.createElement(tag);
+  node.className = className;
+  return node;
+}
+function buildStyles(options, accent) {
+  const zIndex = options.zIndex ?? DEFAULT_Z_INDEX;
+  const side = options.position === "bottom-left" ? "left" : "right";
+  return `
+:host { all: initial; }
+* { box-sizing: border-box; }
+[hidden] { display: none !important; }
+.container {
+  position: fixed;
+  inset: 0;
+  z-index: ${zIndex};
+  pointer-events: none;
+  font-family: system-ui, -apple-system, sans-serif;
+  color: #1f2933;
+}
+.fab {
+  position: absolute;
+  bottom: 20px;
+  ${side}: 20px;
+  pointer-events: auto;
+  border: none;
+  border-radius: 999px;
+  padding: 10px 18px;
+  background: ${accent};
+  color: #fff;
+  font-size: 14px;
+  font-weight: 600;
+  cursor: pointer;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.25);
+}
+.overlay {
+  position: absolute;
+  inset: 0;
+  pointer-events: auto;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.backdrop {
+  position: absolute;
+  inset: 0;
+  background: rgba(15, 23, 42, 0.55);
+}
+.panel {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  width: min(560px, calc(100vw - 32px));
+  max-height: calc(100vh - 32px);
+  overflow: auto;
+  background: #fff;
+  border-radius: 12px;
+  padding: 16px;
+  box-shadow: 0 12px 40px rgba(0, 0, 0, 0.35);
+}
+.header { display: flex; align-items: center; justify-content: space-between; }
+.title { font-size: 16px; font-weight: 600; }
+.close {
+  border: none;
+  background: none;
+  font-size: 20px;
+  line-height: 1;
+  cursor: pointer;
+  color: #52606d;
+  padding: 4px 8px;
+}
+.preview {
+  position: relative;
+  border: 1px solid #d3dce6;
+  border-radius: 8px;
+  overflow: hidden;
+  background: #f5f7fa;
+}
+.preview .shot { display: block; width: 100%; height: auto; }
+.preview .draw {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  cursor: crosshair;
+  touch-action: none;
+}
+.tools { display: flex; align-items: center; gap: 8px; }
+.swatch {
+  width: 24px;
+  height: 24px;
+  border-radius: 50%;
+  border: 2px solid transparent;
+  cursor: pointer;
+  padding: 0;
+}
+.swatch.active { border-color: #1f2933; }
+.tool {
+  border: 1px solid #d3dce6;
+  background: #fff;
+  border-radius: 6px;
+  padding: 4px 10px;
+  font-size: 13px;
+  cursor: pointer;
+}
+.comment {
+  width: 100%;
+  min-height: 72px;
+  resize: vertical;
+  border: 1px solid #d3dce6;
+  border-radius: 8px;
+  padding: 8px 10px;
+  font: inherit;
+}
+.error { color: #b91c1c; font-size: 13px; }
+.success { color: #15803d; font-size: 14px; font-weight: 600; }
+.actions { display: flex; justify-content: flex-end; gap: 8px; }
+.cancel {
+  border: 1px solid #d3dce6;
+  background: #fff;
+  border-radius: 8px;
+  padding: 8px 14px;
+  font-size: 14px;
+  cursor: pointer;
+}
+.submit {
+  border: none;
+  background: ${accent};
+  color: #fff;
+  border-radius: 8px;
+  padding: 8px 16px;
+  font-size: 14px;
+  font-weight: 600;
+  cursor: pointer;
+}
+.submit:disabled { opacity: 0.6; cursor: default; }
+`;
+}
+export {
+  createStrokeStore,
+  exportAnnotatedImage,
+  mapToImagePoint,
+  mountFeedback
+};
+//# sourceMappingURL=feedback-W5PGVRNZ.js.map