@checkflow/sdk 1.1.0 → 1.1.2

package/README.md

@@ -1,265 +1,109 @@
 # @checkflow/sdk
 
-> User feedback collection SDK with automatic context capture
-
-[![npm version](https://img.shields.io/npm/v/@checkflow/sdk.svg)](https://www.npmjs.com/package/@checkflow/sdk)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Lightweight bug reporter & feedback SDK for Checkflow — with screenshot capture, element highlighting, and framework integrations.
 
 ## Features
 
-- 📸 **Automatic Screenshot Capture** - Capture page screenshots with one click
-- 🔍 **Context Collection** - Automatically collect console logs, network requests, and performance metrics
-- 🎨 **Customizable Widget** - Beautiful feedback widget that matches your brand
-- ⚛️ **React Support** - First-class React hooks and components
-- 💚 **Vue Support** - Vue 3 composables and plugin
-- 🛡️ **Error Boundary** - Automatic error capture and reporting
-- 🌍 **i18n Ready** - Built-in translations (EN, FR, ES, DE)
-- 📱 **Responsive** - Works on desktop, tablet, and mobile
+- **Floating widget** — customizable feedback button with form
+- **Screenshot capture** — automatic page screenshots via html2canvas
+- **Element highlighting** — click-to-highlight elements for visual bug reports
+- **Context collection** — URL, viewport, browser, OS, locale, timezone
+- **Console & error capture** — intercepts console.log/warn/error + JS errors
+- **Performance metrics** — FCP, DOM load, page load times
+- **Framework support** — React/Next.js, Vue/Nuxt, vanilla JS
 
 ## Installation
 
 ```bash
 npm install @checkflow/sdk
-# or
-yarn add @checkflow/sdk
-# or
-pnpm add @checkflow/sdk
 ```
 
-## Quick Start
-
-### Vanilla JavaScript
-
-```javascript
-import { createCheckFlow } from '@checkflow/sdk';
+## Quick Start (Vanilla JS)
 
-const checkflow = createCheckFlow('your-api-key', {
-  projectId: 'your-project-id',
-  showWidget: true,
-  captureErrors: true,
-});
-
-// Programmatically open the feedback form
-checkflow.open();
+```js
+import { init } from '@checkflow/sdk';
 
-// Submit feedback programmatically
-await checkflow.submitFeedback({
-  title: 'Bug Report',
-  description: 'Something is broken',
-  type: 'bug',
-  priority: 'high',
+init({
+  apiKey: 'ck_live_...',
+  widget: { position: 'bottom-right', color: '#1e3a5f' },
 });
 ```
 
-### React
+## React / Next.js
 
 ```tsx
-import { CheckFlowProvider, useCheckFlow, FeedbackButton } from '@checkflow/sdk';
+// app/layout.tsx or _app.tsx
+import { useCheckflowInit } from '@checkflow/sdk/react';
 
-// Wrap your app
-function App() {
-  return (
-    <CheckFlowProvider 
-      apiKey="your-api-key"
-      options={{ projectId: 'your-project-id' }}
-    >
-      <YourApp />
-    </CheckFlowProvider>
-  );
+export default function Layout({ children }) {
+  useCheckflowInit({ apiKey: 'ck_live_...' });
+  return <>{children}</>;
 }
+```
 
-// Use the hook
-function MyComponent() {
-  const { openWidget, submitFeedback } = useCheckFlow();
+```tsx
+// Any component
+import { useCheckflowFeedback } from '@checkflow/sdk/react';
 
-  return (
-    <button onClick={openWidget}>
-      Send Feedback
-    </button>
-  );
-}
+function MyComponent() {
+  const { send, screenshot, highlight } = useCheckflowFeedback();
 
-// Or use the built-in button
-function AnotherComponent() {
-  return <FeedbackButton>Report Issue</FeedbackButton>;
+  const reportBug = async () => {
+    const img = await screenshot();
+    const annotations = await highlight();
+    await send({ title: 'Bug report', type: 'BUG' });
+  };
 }
 ```
 
-### Vue 3
+## Vue / Nuxt
 
-```typescript
-import { createApp } from 'vue';
-import { CheckFlowPlugin } from '@checkflow/sdk';
-
-const app = createApp(App);
-
-app.use(CheckFlowPlugin, {
-  apiKey: 'your-api-key',
-  projectId: 'your-project-id',
-});
-
-app.mount('#app');
+```ts
+// main.ts
+import { createCheckflowPlugin } from '@checkflow/sdk/vue';
+app.use(createCheckflowPlugin({ apiKey: 'ck_live_...' }));
 ```
 
 ```vue
 <script setup>
-import { useCheckFlow, useFeedbackForm } from '@checkflow/sdk';
-
-const { openWidget } = useCheckFlow();
-const { formState, submit, isSubmitting } = useFeedbackForm();
+import { useCheckflow } from '@checkflow/sdk/vue';
+const { send, screenshot, highlight } = useCheckflow();
 </script>
-
-<template>
-  <button @click="openWidget">Send Feedback</button>
-</template>
-```
-
-## Configuration Options
-
-```typescript
-interface CheckFlowOptions {
-  // API endpoint (default: https://api.checkflow.io)
-  apiUrl?: string;
-  
-  // Project ID for feedback association
-  projectId?: string;
-  
-  // Widget options
-  showWidget?: boolean;              // Show floating button (default: true)
-  widgetPosition?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
-  widgetButtonText?: string;         // Button text (default: 'Feedback')
-  
-  // Capture options
-  captureErrors?: boolean;           // Auto-capture errors (default: true)
-  captureConsole?: boolean;          // Capture console logs (default: true)
-  captureNetwork?: boolean;          // Capture network requests (default: true)
-  capturePerformance?: boolean;      // Capture performance metrics (default: true)
-  maxConsoleEntries?: number;        // Max console entries (default: 100)
-  maxNetworkEntries?: number;        // Max network entries (default: 100)
-  
-  // User identification
-  user?: {
-    id?: string;
-    email?: string;
-    name?: string;
-  };
-  
-  // Callbacks
-  beforeSubmit?: (feedback) => feedback | false;
-  onSubmit?: (result) => void;
-  onError?: (error) => void;
-  
-  // Localization
-  locale?: 'en' | 'fr' | 'es' | 'de';
-  translations?: Partial<Translations>;
-  
-  // Debug mode
-  debug?: boolean;
-}
 ```
 
-## Error Boundary (React)
+## Programmatic API
 
-```tsx
-import { CheckFlowErrorBoundary } from '@checkflow/sdk';
-
-function App() {
-  return (
-    <CheckFlowErrorBoundary
-      fallback={(error, reset) => (
-        <div>
-          <h1>Something went wrong</h1>
-          <pre>{error.message}</pre>
-          <button onClick={reset}>Try again</button>
-        </div>
-      )}
-      onError={(error, errorInfo) => {
-        console.error('Caught error:', error);
-      }}
-    >
-      <YourApp />
-    </CheckFlowErrorBoundary>
-  );
-}
-```
-
-## Manual Context Capture
-
-```typescript
-import { createCheckFlow } from '@checkflow/sdk';
-
-const checkflow = createCheckFlow('your-api-key');
-
-// Capture current page context
-const capture = await checkflow.capture({
-  fullPage: true,           // Capture full page (not just viewport)
-  quality: 80,              // Screenshot quality (1-100)
-  includeConsole: true,     // Include console logs
-  includeNetwork: true,     // Include network logs
-  hideElements: ['.secret'], // CSS selectors to hide
-  maskElements: ['.password'], // CSS selectors to mask
-});
-
-console.log(capture.screenshot);     // Base64 screenshot
-console.log(capture.consoleLogs);    // Console entries
-console.log(capture.networkLogs);    // Network requests
-console.log(capture.performance);    // Performance metrics
-console.log(capture.context);        // Page context (URL, browser, etc.)
-```
+```js
+import { sendFeedback, captureScreenshot, startHighlighting, showWidget, hideWidget, destroy } from '@checkflow/sdk';
 
-## User Identification
+// Send feedback
+await sendFeedback({ title: 'Bug', type: 'BUG', priority: 'HIGH' });
 
-```typescript
-// Set user info
-checkflow.setUser({
-  id: 'user-123',
-  email: 'user@example.com',
-  name: 'John Doe',
-});
-
-// Clear user info (on logout)
-checkflow.clearUser();
-```
+// Capture screenshot
+const dataUrl = await captureScreenshot();
 
-## CDN Usage
+// Start element highlighting mode
+const annotations = await startHighlighting();
 
-```html
-<script src="https://unpkg.com/@checkflow/sdk/dist/checkflow.umd.js"></script>
-<link rel="stylesheet" href="https://unpkg.com/@checkflow/sdk/dist/checkflow.css">
-
-<script>
-  const checkflow = new CheckFlow('your-api-key', {
-    projectId: 'your-project-id',
-  }).init();
-</script>
+// Widget control
+showWidget();
+hideWidget();
+destroy();
 ```
 
-## TypeScript
-
-The SDK is written in TypeScript and includes full type definitions.
-
-```typescript
-import type { 
-  FeedbackData, 
-  CaptureResult, 
-  CheckFlowOptions 
-} from '@checkflow/sdk';
-```
-
-## Privacy & Security
-
-- Screenshots can exclude sensitive elements using `hideElements` and `maskElements`
-- Console logs are filtered to remove potentially sensitive data
-- Network requests to CheckFlow API are excluded from capture
-- All data is transmitted over HTTPS
-
-## Browser Support
+## Configuration
 
-- Chrome 80+
-- Firefox 75+
-- Safari 13+
-- Edge 80+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | required | Your project API key |
+| `endpoint` | `string` | `https://api.checkflow.space/api/v1` | API endpoint |
+| `environment` | `string` | `production` | Environment name |
+| `enabled` | `boolean` | `true` | Enable/disable SDK |
+| `widget.position` | `string` | `bottom-right` | Widget position |
+| `widget.color` | `string` | `#1e3a5f` | Widget accent color |
+| `widget.text` | `string` | `Report Bug` | Widget button text |
+| `widget.showOnInit` | `boolean` | `true` | Show widget on init |
 
 ## License
 
-MIT © CheckFlow
+MIT

package/dist/chunk-CD33QAA6.mjs

@@ -0,0 +1,131 @@
+// src/highlighter.ts
+var overlay = null;
+var highlights = [];
+var isActive = false;
+var onDoneCallback = null;
+function getSelector(el) {
+  if (el.id) return `#${el.id}`;
+  const parts = [];
+  let current = el;
+  while (current && current !== document.body) {
+    let sel = current.tagName.toLowerCase();
+    if (current.id) {
+      parts.unshift(`#${current.id}`);
+      break;
+    }
+    if (current.className && typeof current.className === "string") {
+      const cls = current.className.trim().split(/\s+/).slice(0, 2).join(".");
+      if (cls) sel += `.${cls}`;
+    }
+    const parent = current.parentElement;
+    if (parent) {
+      const siblings = Array.from(parent.children).filter((c) => c.tagName === current.tagName);
+      if (siblings.length > 1) sel += `:nth-child(${Array.from(parent.children).indexOf(current) + 1})`;
+    }
+    parts.unshift(sel);
+    current = current.parentElement;
+  }
+  return parts.join(" > ");
+}
+function createOverlay() {
+  overlay = document.createElement("div");
+  overlay.id = "cf-highlight-overlay";
+  overlay.style.cssText = "position:fixed;top:0;left:0;width:100%;height:100%;z-index:99999;cursor:crosshair;";
+  const toolbar = document.createElement("div");
+  toolbar.style.cssText = "position:fixed;top:12px;left:50%;transform:translateX(-50%);z-index:100002;background:#1e3a5f;color:#fff;padding:8px 16px;border-radius:10px;font-family:system-ui;font-size:13px;display:flex;align-items:center;gap:12px;box-shadow:0 4px 20px rgba(0,0,0,.25);";
+  toolbar.innerHTML = `
+    <span>Click elements to highlight them</span>
+    <button id="cf-hl-done" style="background:#10b981;color:#fff;border:none;border-radius:6px;padding:6px 14px;font-size:12px;cursor:pointer;font-weight:500;">Done (${highlights.length})</button>
+    <button id="cf-hl-cancel" style="background:transparent;color:#fff;border:1px solid rgba(255,255,255,.3);border-radius:6px;padding:6px 14px;font-size:12px;cursor:pointer;">Cancel</button>
+  `;
+  overlay.appendChild(toolbar);
+  document.body.appendChild(overlay);
+  overlay.addEventListener("click", handleClick);
+  overlay.addEventListener("mousemove", handleHover);
+  document.getElementById("cf-hl-done")?.addEventListener("click", finishHighlighting);
+  document.getElementById("cf-hl-cancel")?.addEventListener("click", cancelHighlighting);
+}
+var hoverBox = null;
+function handleHover(e) {
+  if (!hoverBox) {
+    hoverBox = document.createElement("div");
+    hoverBox.style.cssText = "position:fixed;border:2px solid #0c66e4;background:rgba(12,102,228,0.08);pointer-events:none;z-index:100001;border-radius:3px;transition:all 0.05s;";
+    document.body.appendChild(hoverBox);
+  }
+  const target = document.elementFromPoint(e.clientX, e.clientY);
+  if (target && target !== overlay && !overlay?.contains(target)) {
+    const rect = target.getBoundingClientRect();
+    hoverBox.style.left = rect.left + "px";
+    hoverBox.style.top = rect.top + "px";
+    hoverBox.style.width = rect.width + "px";
+    hoverBox.style.height = rect.height + "px";
+    hoverBox.style.display = "block";
+  } else {
+    hoverBox.style.display = "none";
+  }
+}
+function handleClick(e) {
+  e.preventDefault();
+  e.stopPropagation();
+  const target = document.elementFromPoint(e.clientX, e.clientY);
+  if (!target || target === overlay || overlay?.contains(target)) return;
+  const rect = target.getBoundingClientRect();
+  highlights.push({ el: target, rect });
+  const marker = document.createElement("div");
+  marker.className = "cf-hl-marker";
+  marker.style.cssText = `position:fixed;left:${rect.left}px;top:${rect.top}px;width:${rect.width}px;height:${rect.height}px;border:2px solid #ae2a19;background:rgba(174,42,25,0.12);z-index:100001;pointer-events:none;border-radius:3px;`;
+  const badge = document.createElement("div");
+  badge.style.cssText = "position:absolute;top:-10px;right:-10px;background:#ae2a19;color:#fff;width:20px;height:20px;border-radius:50%;font-size:11px;display:flex;align-items:center;justify-content:center;font-family:system-ui;font-weight:600;";
+  badge.textContent = String(highlights.length);
+  marker.appendChild(badge);
+  overlay?.appendChild(marker);
+  const doneBtn = document.getElementById("cf-hl-done");
+  if (doneBtn) doneBtn.textContent = `Done (${highlights.length})`;
+}
+function finishHighlighting() {
+  const annotations = highlights.map((h) => ({
+    selector: getSelector(h.el),
+    tagName: h.el.tagName.toLowerCase(),
+    text: h.el.textContent?.slice(0, 100) || void 0,
+    rect: { x: Math.round(h.rect.x), y: Math.round(h.rect.y), width: Math.round(h.rect.width), height: Math.round(h.rect.height) },
+    note: h.note
+  }));
+  cleanup();
+  onDoneCallback?.(annotations);
+}
+function cancelHighlighting() {
+  cleanup();
+  onDoneCallback?.([]);
+}
+function cleanup() {
+  if (hoverBox) {
+    hoverBox.remove();
+    hoverBox = null;
+  }
+  if (overlay) {
+    overlay.remove();
+    overlay = null;
+  }
+  highlights = [];
+  isActive = false;
+}
+function startHighlighting() {
+  return new Promise((resolve) => {
+    if (isActive) {
+      resolve([]);
+      return;
+    }
+    isActive = true;
+    highlights = [];
+    onDoneCallback = resolve;
+    createOverlay();
+  });
+}
+function isHighlighting() {
+  return isActive;
+}
+
+export {
+  startHighlighting,
+  isHighlighting
+};

package/dist/chunk-CQ56DMFR.mjs

@@ -0,0 +1,83 @@
+// src/screenshot.ts
+var screenshotData = null;
+async function captureScreenshot() {
+  try {
+    if (typeof window.html2canvas === "function") {
+      const canvas2 = await window.html2canvas(document.body, {
+        useCORS: true,
+        allowTaint: true,
+        scale: Math.min(window.devicePixelRatio, 2),
+        logging: false,
+        width: window.innerWidth,
+        height: window.innerHeight,
+        x: window.scrollX,
+        y: window.scrollY
+      });
+      screenshotData = canvas2.toDataURL("image/png", 0.8);
+      return screenshotData;
+    }
+    const canvas = document.createElement("canvas");
+    const ctx = canvas.getContext("2d");
+    if (!ctx) return null;
+    canvas.width = window.innerWidth;
+    canvas.height = window.innerHeight;
+    ctx.fillStyle = "#ffffff";
+    ctx.fillRect(0, 0, canvas.width, canvas.height);
+    ctx.fillStyle = "#333333";
+    ctx.font = "14px system-ui";
+    ctx.fillText(`Page: ${window.location.href}`, 10, 30);
+    ctx.fillText(`Viewport: ${window.innerWidth}x${window.innerHeight}`, 10, 50);
+    ctx.fillText(`Screenshot captured at ${(/* @__PURE__ */ new Date()).toISOString()}`, 10, 70);
+    const svgData = `
+      <svg xmlns="http://www.w3.org/2000/svg" width="${window.innerWidth}" height="${window.innerHeight}">
+        <foreignObject width="100%" height="100%">
+          <div xmlns="http://www.w3.org/1999/xhtml">
+            ${document.documentElement.outerHTML}
+          </div>
+        </foreignObject>
+      </svg>`;
+    try {
+      const blob = new Blob([svgData], { type: "image/svg+xml;charset=utf-8" });
+      const url = URL.createObjectURL(blob);
+      const img = new Image();
+      await new Promise((resolve, reject) => {
+        img.onload = () => resolve();
+        img.onerror = () => reject();
+        img.src = url;
+      });
+      ctx.drawImage(img, 0, 0);
+      URL.revokeObjectURL(url);
+    } catch {
+    }
+    screenshotData = canvas.toDataURL("image/png", 0.8);
+    return screenshotData;
+  } catch {
+    return null;
+  }
+}
+function getLastScreenshot() {
+  return screenshotData;
+}
+function clearScreenshot() {
+  screenshotData = null;
+}
+function loadHtml2Canvas() {
+  return new Promise((resolve, reject) => {
+    if (typeof window.html2canvas === "function") {
+      resolve();
+      return;
+    }
+    const script = document.createElement("script");
+    script.src = "https://cdnjs.cloudflare.com/ajax/libs/html2canvas/1.4.1/html2canvas.min.js";
+    script.onload = () => resolve();
+    script.onerror = () => reject(new Error("Failed to load html2canvas"));
+    document.head.appendChild(script);
+  });
+}
+
+export {
+  captureScreenshot,
+  getLastScreenshot,
+  clearScreenshot,
+  loadHtml2Canvas
+};

package/dist/highlighter-D_wZWHlS.d.mts

@@ -0,0 +1,71 @@
+interface CheckflowConfig {
+    apiKey: string;
+    endpoint?: string;
+    projectId?: string;
+    environment?: string;
+    enabled?: boolean;
+    widget?: WidgetConfig;
+    /** Auto-load html2canvas for screenshot support (default: true) */
+    enableScreenshots?: boolean;
+}
+interface WidgetConfig {
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    color?: string;
+    text?: string;
+    showOnInit?: boolean;
+}
+interface FeedbackPayload {
+    title: string;
+    description?: string;
+    type?: 'BUG' | 'FEATURE' | 'IMPROVEMENT' | 'QUESTION';
+    priority?: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+    url?: string;
+    environment?: string;
+    viewport?: {
+        width: number;
+        height: number;
+        device: string;
+    };
+    user_agent?: string;
+    browser?: string;
+    os?: string;
+    locale?: string;
+    timezone?: string;
+    console_logs?: any[];
+    network_logs?: any[];
+    performance_metrics?: Record<string, number>;
+    javascript_errors?: any[];
+    screenshot_url?: string;
+    sdk_version?: string;
+}
+interface FeedbackResponse {
+    success: boolean;
+    data?: {
+        id: string;
+        short_id: string;
+    };
+    error?: {
+        message: string;
+        code: string;
+    };
+}
+
+/**
+ * Element highlighter for visual bug reporting.
+ * Allows users to click on elements to highlight them and annotate.
+ */
+interface HighlightAnnotation {
+    selector: string;
+    tagName: string;
+    text?: string;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    note?: string;
+}
+declare function startHighlighting(): Promise<HighlightAnnotation[]>;
+
+export { type CheckflowConfig as C, type FeedbackPayload as F, type HighlightAnnotation as H, type WidgetConfig as W, type FeedbackResponse as a, startHighlighting as s };

package/dist/highlighter-D_wZWHlS.d.ts

@@ -0,0 +1,71 @@
+interface CheckflowConfig {
+    apiKey: string;
+    endpoint?: string;
+    projectId?: string;
+    environment?: string;
+    enabled?: boolean;
+    widget?: WidgetConfig;
+    /** Auto-load html2canvas for screenshot support (default: true) */
+    enableScreenshots?: boolean;
+}
+interface WidgetConfig {
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    color?: string;
+    text?: string;
+    showOnInit?: boolean;
+}
+interface FeedbackPayload {
+    title: string;
+    description?: string;
+    type?: 'BUG' | 'FEATURE' | 'IMPROVEMENT' | 'QUESTION';
+    priority?: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+    url?: string;
+    environment?: string;
+    viewport?: {
+        width: number;
+        height: number;
+        device: string;
+    };
+    user_agent?: string;
+    browser?: string;
+    os?: string;
+    locale?: string;
+    timezone?: string;
+    console_logs?: any[];
+    network_logs?: any[];
+    performance_metrics?: Record<string, number>;
+    javascript_errors?: any[];
+    screenshot_url?: string;
+    sdk_version?: string;
+}
+interface FeedbackResponse {
+    success: boolean;
+    data?: {
+        id: string;
+        short_id: string;
+    };
+    error?: {
+        message: string;
+        code: string;
+    };
+}
+
+/**
+ * Element highlighter for visual bug reporting.
+ * Allows users to click on elements to highlight them and annotate.
+ */
+interface HighlightAnnotation {
+    selector: string;
+    tagName: string;
+    text?: string;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    note?: string;
+}
+declare function startHighlighting(): Promise<HighlightAnnotation[]>;
+
+export { type CheckflowConfig as C, type FeedbackPayload as F, type HighlightAnnotation as H, type WidgetConfig as W, type FeedbackResponse as a, startHighlighting as s };