@qovlo/sdk

Add Qovlo-powered bug reports, support chat, feature feedback, onboarding, and evidence capture to a web app.

Install

npm install @qovlo/sdk

What You Need

• A public Qovlo project key from your Qovlo project setup.
• A public Qovlo intake host for your workspace or environment.
• An authenticated app route that returns a short-lived Qovlo client token.

Keep admin credentials, server tokens, provider API keys, private URLs, database names, environment files, and sensitive user data out of browser code.

Quick Start

import { QovloClientSDK } from "@qovlo/sdk";

const sdk = new QovloClientSDK({
  intakeBackendUrl: "https://YOUR_QOVLO_PUBLIC_INTAKE_HOST",
  projectKey: "org_demo:proj_public_abc123",
  clientTokenProvider: async () => {
    const res = await fetch("/api/qovlo/public-token", {
      credentials: "include",
    });
    const data = await res.json();
    return data.client_token;
  },
  sourceChannel: "widget",
});

sdk.setContext({
  customerOrgId: "customer_org",
  clientRef: "web-app",
  userId: "user_42",
});

const report = await sdk.createReport({
  title: "Checkout button disabled",
  description: "Cannot place order after entering shipping details.",
});

Add The Widget

import { QovloClientSDK, mountQovloWidget } from "@qovlo/sdk";

const sdk = new QovloClientSDK({
  intakeBackendUrl: "https://YOUR_QOVLO_PUBLIC_INTAKE_HOST",
  projectKey: "org_demo:proj_public_abc123",
  clientTokenProvider: async () => {
    const res = await fetch("/api/qovlo/public-token", {
      credentials: "include",
    });
    const data = await res.json();
    return data.client_token;
  },
});

const widget = mountQovloWidget({
  sdk,
  defaultMode: "ai",
  displayMode: "side-panel",
  theme: {
    brandName: "Acme",
    assistantName: "Acme Assistant",
    launcherLabel: "Help",
    accent: "#0f766e",
    tabs: [
      { key: "ai", label: "Assistant", icon: "sparkles" },
      { key: "bug", label: "Report", icon: "bug" },
      { key: "feature", label: "Feature", icon: "sparkles" },
    ],
  },
});

widget.setContext({
  customerOrgId: "customer_org",
  clientRef: "web-app",
  userId: "user_42",
});

Next.js Token Route Example

Create a server route in your app that exchanges your server-side Qovlo credential for a short-lived client token.

import { NextResponse } from "next/server";

export async function GET() {
  const res = await fetch(process.env.QOVLO_CLIENT_TOKEN_URL!, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.QOVLO_SERVER_TOKEN}`,
    },
    body: JSON.stringify({
      project_key: process.env.NEXT_PUBLIC_QOVLO_PROJECT_KEY,
      scope: "public:intake",
      ttl_seconds: 900,
    }),
    cache: "no-store",
  });

  if (!res.ok) {
    return NextResponse.json({ error: "qovlo_token_failed" }, { status: 502 });
  }

  const data = await res.json();
  return NextResponse.json({ client_token: data.client_token });
}

Safe Context

Send context that helps triage reports:

• App version
• Page or route name
• Release channel
• Browser/device details
• Non-sensitive user or account labels
• Product area labels

Do not send passwords, payment data, session cookies, private notes, internal permissions, confidential business rules, or long-lived credentials.

Reports, Chat, And Search

const report = await sdk.createReport({
  title: "Checkout failed",
  description: "The pay button stays disabled.",
});

const matches = await sdk.searchPublicReports("checkout failed", 5);

const chat = await sdk.createChatSession(report.id);
await sdk.sendChatMessage(chat.id, "I can reproduce this on Safari.", "user");

await sdk.streamChatMessage(chat.id, "What should I try next?", "user", {}, {
  onToken: (token) => appendToChat(token),
  onDone: (reply) => console.log(reply),
});

Media Evidence

const screenshot = await sdk.captureScreenshot();
await sdk.uploadAndAttachMedia(report.id, screenshot, {
  caption: "Checkout screen before submit",
});

const recording = await sdk.startScreenRecording({
  audio: true,
  maxDurationSec: 90,
  captureArea: "prompt",
  camera: {
    microphone: true,
    position: "bottom-right",
    shape: "circle",
  },
  outputSize: {
    width: 1280,
    height: 720,
    fit: "contain",
    backgroundColor: "#020617",
  },
});

recording.pause();
recording.resume();

const video = await recording.stop();
await sdk.uploadAndAttachMedia(report.id, video, {
  caption: "Checkout reproduction",
});

// Or observe completion from floating recorder controls.
const completed = await recording.finished;

Screen recording supports full-source capture, selected-area capture, optional screen/system audio, opt-in camera commentary with microphone audio, floating pause/stop/discard controls, custom output sizing, looped review playback, timestamp notes, trim, stitched clip ranges, backgrounds, and text/arrow/box/draw overlays. When the browser supports canvas capture and MediaRecorder, the review dialog renders those edits into an attached WebM. If rendering is unavailable or the rendered file exceeds upload limits, the SDK safely attaches the raw recording and records the edit/fallback details in visual_evidence.rendered.

React Export

import { QovloWidget } from "@qovlo/sdk/react";

export function SupportWidget() {
  return (
    <QovloWidget
      intakeBackendUrl="https://YOUR_QOVLO_PUBLIC_INTAKE_HOST"
      projectKey="org_demo:proj_public_abc123"
      clientTokenProvider={async () => {
        const res = await fetch("/api/qovlo/public-token", {
          credentials: "include",
        });
        const data = await res.json();
        return data.client_token;
      }}
    />
  );
}

Playwright Reporter

Use the Playwright export when you want to send test results to Qovlo.

import { defineConfig } from "@playwright/test";

export default defineConfig({
  reporter: [
    ["list"],
    ["@qovlo/sdk/playwright", {
      testingAgentUrl: process.env.QOVLO_TESTING_AGENT_URL,
      runId: process.env.QOVLO_TESTING_RUN_ID,
      orgId: process.env.QOVLO_ORG_ID,
      projectId: process.env.QOVLO_PROJECT_ID,
      token: process.env.QOVLO_TESTING_TOKEN,
    }],
  ],
});

Main APIs

• new QovloClientSDK(config)
• createReport(input)
• searchPublicReports(query, limit?)
• createChatSession(reportId?)
• sendChatMessage(chatSessionId, message, role?, metadata?)
• streamChatMessage(chatSessionId, message, role?, metadata?, callbacks?)
• captureScreenshot()
• startScreenRecording(options?) with pause/resume, floating controls, region selection, opt-in camera commentary, review, browser-rendered edits, and timestamp notes
• startAudioRecording(options?) with pause/resume and review before upload
• uploadAndAttachMedia(reportId, media, options?)
• mountQovloWidget(config)
• QovloWidget from @qovlo/sdk/react
• Playwright reporter from @qovlo/sdk/playwright

More Documentation

• API reference: docs/v0.1/api-reference.md
• Security: docs/v0.1/security.md
• Plugins: docs/v0.1/plugins.md
• Browser extension bridge: docs/v0.1/browser-extension.md
• Replay and diagnostics: docs/v0.1/replay-and-diagnostics.md
• Examples: examples/