Documentation

npm install glitchgrab
# or
bun add glitchgrab

// app/layout.tsx
import { GlitchgrabProvider } from "glitchgrab";

export default function RootLayout({ children }) {
  return (
    <GlitchgrabProvider token={process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!}>
      {children}
    </GlitchgrabProvider>
  );
}

import { GlitchgrabProvider, type GlitchgrabSession } from "glitchgrab";
import { useSession } from "next-auth/react"; // or your auth library

function Providers({ children }) {
  const { data: authSession } = useSession();

  // Map your auth session to GlitchgrabSession
  const session: GlitchgrabSession | null = authSession?.user
    ? {
        userId: authSession.user.id,     // required - your DB primary key
        name: authSession.user.name,     // required - display name
        email: authSession.user.email,   // optional
        phone: authSession.user.phone,   // optional
      }
    : null;

  return (
    <GlitchgrabProvider
      token={process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!}
      session={session}
    >
      {children}
    </GlitchgrabProvider>
  );
}

interface GlitchgrabSession {
  userId: string;          // required - primary key from your database
  name: string;            // required - reporter's display name
  email?: string | null;   // optional
  phone?: string | null;   // optional
  signature?: string | null; // optional - signSession() from "glitchgrab/server"
  [key: string]: unknown;  // any extra fields
}

// app/layout.tsx — a server component
import { signSession } from "glitchgrab/server";
import { auth } from "@/lib/auth"; // your auth library
import { Providers } from "./providers";

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const user = (await auth())?.user;

  const session = user
    ? {
        userId: user.id,
        name: user.name ?? "User",
        email: user.email,
        // Reads GLITCHGRAB_SIGNING_SECRET. Server env only — never NEXT_PUBLIC_.
        signature: signSession({ userId: user.id }),
      }
    : null;

  return <Providers session={session}>{children}</Providers>;
}

// app/providers.tsx — "use client"
// <GlitchgrabProvider token={process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!} session={session}>

import { ReportButton } from "glitchgrab";

// Floating button at bottom-right (default)
<ReportButton position="bottom-right" label="Report Bug" />

import { ReportButton } from "glitchgrab";

<ReportButton>
  {({ onClick, capturing }) => (
    <button onClick={onClick} disabled={capturing}>
      {capturing ? "Capturing..." : "Report a Bug"}
    </button>
  )}
</ReportButton>

import { useGlitchgrab } from "glitchgrab";

function MyComponent() {
  const { reportBug, report, addBreadcrumb, openReportDialog } = useGlitchgrab();

  // Report a bug silently (no UI)
  await reportBug("Button not working on mobile");

  // Report with a specific type
  await report("FEATURE_REQUEST", "Add dark mode support");

  // Open the Report Bug modal (captures screenshot + shows dialog)
  openReportDialog();

  // Open with pre-filled description
  openReportDialog({ description: "Error on /settings: Something went wrong" });

  // Add custom breadcrumbs for debugging context
  addBreadcrumb("User clicked checkout", { cartSize: "3" });
}

function FeedbackWidget() {
  const { openReportDialog } = useGlitchgrab();

  return (
    <div>
      <button onClick={() => alert("Thanks!")}>Good</button>
      <button onClick={() => openReportDialog()}>Bad — report a bug</button>
    </div>
  );
}

import { FeedbackButton } from "glitchgrab";

<FeedbackButton />                              // floating, bottom-left
<FeedbackButton position="bottom-right" label="Rate us" />

// Your own trigger
<FeedbackButton>
  {({ onClick }) => <button onClick={onClick}>How are we doing?</button>}
</FeedbackButton>

function RatingRow() {
  const { sendFeedback } = useGlitchgrab();

  return [1, 2, 3, 4, 5].map((stars) => (
    <button key={stars} onClick={() => sendFeedback(stars, "Loved the new export flow")}>
      {stars}★
    </button>
  ));
}

import { useGlitchgrabFeedback } from "glitchgrab";

function Testimonials() {
  const { feedback, isLoading } = useGlitchgrabFeedback({
    token: process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!,
    approvedOnly: true,
    minRating: 4,
  });

  if (isLoading) return null;

  return feedback.map((f) => (
    <blockquote key={f.id}>
      {f.message} — {f.reporterName} ({f.rating}★)
    </blockquote>
  ));
}

# Submit
curl -X POST https://glitchgrab.dev/api/v1/sdk/feedback \
  -H "Authorization: Bearer gg_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"rating":5,"message":"Fast and simple","metadata":{"sessionUserId":"user_123","sessionUserName":"Asha"}}'

# Read published entries
curl "https://glitchgrab.dev/api/v1/sdk/feedback?approved=true&minRating=4&limit=20" \
  -H "Authorization: Bearer gg_xxxxx"

const { submitLead } = useGlitchgrab();

const result = await submitLead({
  name: "Asha Mehta",
  phone: "+91 98765 43210",
  source: "demo",               // which form — filter on it later
  email: "asha@firm.in",        // optional
  company: "Mehta & Co",        // optional
  address: "Pune",              // optional
  metadata: { practice: "CA", language: "Hindi" }, // optional, flat values
});
// { success: true, id: "…", created: true } — or null on failure. Never throws.

import { listLeads } from "glitchgrab/server";

const leads = await listLeads({ source: "demo", since: "2026-09-01" }); // GLITCHGRAB_CALLS_KEY=ggc_…

function SupportHint() {
  const { shortcutLabel } = useGlitchgrab();
  return <p>Found a bug? Press {shortcutLabel} anywhere to report it.</p>;
}

import { useGlitchgrabReports } from "glitchgrab";

function MyReports() {
  const { reports, isLoading, error, refetch } = useGlitchgrabReports({
    token: process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!,
    userId: session.user.id,        // your DB primary key
    limit: 20,                       // optional, default 100
  });

  if (isLoading) return <p>Loading...</p>;
  if (error) return <p>Error: {error}</p>;

  return (
    <ul>
      {reports.map((r) => (
        <li key={r.id}>
          {r.issue?.title ?? r.rawInput} — {r.issue?.githubState ?? r.status}
        </li>
      ))}
    </ul>
  );
}

import { fetchGlitchgrabReports } from "glitchgrab";
import { useQuery } from "@tanstack/react-query";

const { data: reports, isLoading } = useQuery({
  queryKey: ["glitchgrab-reports", session.user.id],
  queryFn: () => fetchGlitchgrabReports({
    token: process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!,
    userId: session.user.id,
    limit: 50,
  }),
});

# Fetch all reports
curl -H "Authorization: Bearer gg_your_token" \
  https://glitchgrab.dev/api/v1/sdk/reports

# Fetch reports by a specific user
curl -H "Authorization: Bearer gg_your_token" \
  "https://glitchgrab.dev/api/v1/sdk/reports?reporterPrimaryKey=user_123"

# Filter by status
curl -H "Authorization: Bearer gg_your_token" \
  "https://glitchgrab.dev/api/v1/sdk/reports?status=CREATED&limit=20"

{
  "success": true,
  "data": [
    {
      "id": "cmn7abc123",
      "source": "SDK_USER_REPORT",
      "status": "CREATED",
      "rawInput": "Button not working",
      "reporterPrimaryKey": "user_123",
      "reporterName": "John Doe",
      "reporterEmail": "john@example.com",
      "reporterPhone": null,
      "pageUrl": "/dashboard/settings",
      "createdAt": "2026-03-26T12:00:00.000Z",
      "issue": {
        "githubNumber": 42,
        "githubUrl": "https://github.com/your/repo/issues/42",
        "title": "Button not working",
        "labels": ["bug"],
        "severity": "medium",
        "githubState": "open"
      }
    }
  ]
}

## How do I approve, reject, or close issues?

### React hook

### Dashboard

Go to **Reports > Product Issues**. Each open report shows:
- **Approve** — adds `approved` label to GitHub issue
- **Reject** — adds `rejected` label to GitHub issue
- **Close** — closes the GitHub issue

### REST API

`POST /api/v1/reports/{reportId}/actions`

Auth: `Bearer gg_` token or dashboard session.

#### Approve a report

#### Reject a report

#### Close an issue

#### Reopen an issue

#### Remove a label

#### Add any custom label

### How to get the report ID

Use the [Fetching Reports API](#how-do-i-fetch-reports-by-user) to list reports. Each report has an `id` field — use that as `REPORT_ID`.

### How it works

1. End-user reports a bug via SDK -> GitHub issue created
2. You fetch reports via API or view on dashboard
3. Approve/reject/close via API or dashboard buttons
4. Labels and state sync directly to GitHub — GitHub is the source of truth

## How do I add comments to a report?

Each report has a conversation thread powered by GitHub issue comments. No extra database — comments live on GitHub.

### View a report with comments

Returns the full issue body + all comments:

### Reply to a report

The comment is posted to the GitHub issue with attribution: "Commented by: **Vivek** (vivek@example.com)".

### Dashboard

Click any report on the Reports page to see the full conversation thread. Reply directly from the dashboard — comments sync to GitHub.

## How do I add an error boundary?

Wrap components to auto-capture React errors: