glitchgrab 1.29.1 → 1.31.0

package/README.md

@@ -146,6 +146,84 @@ function FeedbackWidget() {
 
 Note: `openReportDialog()` requires a `<ReportButton>` to be mounted somewhere in the component tree. It triggers the same modal with screenshot capture.
 
+## How do I collect feedback about my app?
+
+Reports are for bugs. **Feedback** is for how your users feel about your app — a 1–5 star rating with an optional message. Glitchgrab stores it, so you don't write a table, a route, or a migration. Feedback never becomes a GitHub issue.
+
+### Drop-in button
+
+```tsx
+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>
+```
+
+The dialog (stars + message) ships inside `GlitchgrabProvider` — the button is only the trigger. Open it from anywhere with `openFeedbackDialog()`.
+
+### Your own UI
+
+```tsx
+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>
+  ));
+}
+```
+
+`sendFeedback(rating, message?, metadata?)` never throws — it returns `null` on failure. The reporter is taken from the `session` prop on `GlitchgrabProvider`, so pass a session if you want to know who rated you.
+
+### Reading it back
+
+Every entry shows up on your Glitchgrab **Feedback** page, where you press **publish** on the ones you want to reuse. Published entries are the only ones returned with `approvedOnly` — so a testimonials wall can never leak an unvetted complaint:
+
+```tsx
+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>
+  ));
+}
+```
+
+Pass `userId` instead to show one user their own past ratings. `fetchGlitchgrabFeedback(...)` is the standalone fetcher for TanStack Query. Neither response includes email or phone, so both are safe to render on a public page.
+
+### REST
+
+```bash
+# 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"
+```
+
+The repo is always derived from the token — there is no `repoId` to pass. Rate limit: 30 submissions per token per hour.
+
 ## What keyboard shortcuts are available?
 
 Once `GlitchgrabProvider` is mounted, these shortcuts work globally:
@@ -455,6 +533,114 @@ import { GlitchgrabErrorBoundary } from "glitchgrab";
 </GlitchgrabErrorBoundary>
 ```
 
+⚠️ **This does not cover the Next.js App Router.** If your app has an `app/error.tsx`, Next's own boundary sits closer to the crashing component and catches first — `GlitchgrabErrorBoundary` never runs, and the crash is never reported. See [How do I capture App Router crashes?](#how-do-i-capture-app-router-crashes) below.
+
+## How do I capture App Router crashes?
+
+**Read this if you use `app/error.tsx` or `app/global-error.tsx` — otherwise your render crashes are silently lost.**
+
+A React error that a boundary *handles* never reaches `window.onerror`, so provider auto-capture cannot see it. In an App Router app, Next's `error.tsx` is that boundary. The user sees the fallback screen, and the message and stack are gone.
+
+Report it yourself with `captureError`:
+
+```tsx
+// app/error.tsx
+"use client";
+
+import { useEffect } from "react";
+import { useGlitchgrab } from "glitchgrab";
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string };
+  reset: () => void;
+}) {
+  const { captureError } = useGlitchgrab();
+
+  useEffect(() => {
+    captureError(error, { digest: error.digest, boundary: "next-app-router" });
+  }, [error, captureError]);
+
+  return (
+    <div>
+      <p>Something went wrong</p>
+      <button onClick={reset}>Try again</button>
+    </div>
+  );
+}
+```
+
+`global-error.tsx` replaces the root layout, so it renders **outside** the provider tree and `useGlitchgrab()` would throw. Use the standalone export there — it reads the token from the last mounted provider:
+
+```tsx
+// app/global-error.tsx
+"use client";
+
+import { useEffect } from "react";
+import { captureError } from "glitchgrab";
+
+export default function GlobalError({
+  error,
+}: {
+  error: Error & { digest?: string };
+}) {
+  useEffect(() => {
+    captureError(error, { digest: error.digest, boundary: "next-global-error" });
+  }, [error]);
+
+  return (
+    <html>
+      <body>
+        <p>Something went wrong</p>
+      </body>
+    </html>
+  );
+}
+```
+
+The same applies to React Router `errorElement`, Remix `ErrorBoundary`, and any hand-rolled `componentDidCatch` — call `captureError` from each.
+
+### Catching every boundary error in one place (React 19)
+
+React 19 lets you intercept *all* boundary-caught errors at the root, so you don't have to wire each boundary by hand:
+
+```tsx
+// app/instrumentation-client.ts (or your custom hydrateRoot call)
+import { captureError } from "glitchgrab";
+
+hydrateRoot(document, <App />, {
+  onCaughtError: (error, errorInfo) => {
+    captureError(error, {
+      componentStack: errorInfo.componentStack ?? undefined,
+      boundary: "react-onCaughtError",
+    });
+  },
+});
+```
+
+Next.js does not expose `hydrateRoot` options, so App Router apps should use the `error.tsx` snippets above.
+
+### captureError options
+
+```ts
+captureError(error: unknown, options?: {
+  componentStack?: string;  // from componentDidCatch / onCaughtError
+  digest?: string;          // Next.js error digest — also feeds dedup
+  boundary?: string;        // which boundary caught it, stored as metadata
+  metadata?: Record<string, string>;
+})
+```
+
+- Sends `source: "SDK_AUTO"`, `type: "BUG"` with the message, stack, component stack, breadcrumbs, device info, page URL and session identity — same shape as auto-capture.
+- **Deduped.** An identical error repeating within 5 minutes files one issue, not N — a crash loop won't spam your repo.
+- Honours the provider's `ignoreErrors`.
+- Fire-and-forget. Never throws, never blocks your fallback UI from rendering.
+- Runs in development too (unlike passive auto-capture), so you can verify the wiring the moment you add it.
+- Pass `digest` whenever you have it. In production Next replaces server-boundary error messages with one generic string — without the digest, every distinct server crash on a page collapses into a single deduped issue.
+- No-ops if no `GlitchgrabProvider` has rendered yet.
+
 ## What configuration options are available?
 
 | Prop | Type | Default | Description |
@@ -468,6 +654,9 @@ import { GlitchgrabErrorBoundary } from "glitchgrab";
 | `onReportSent` | `(result: ReportResult) => void` | - | Called after a report is sent |
 | `fallback` | `ReactNode` | - | Error boundary fallback UI |
 | `ignoreErrors` | `(string \| RegExp)[]` | - | Skip auto-capture for errors whose message matches (substring for `string`, `.test()` for `RegExp`) |
+| `release` | `string` | env fallback | Build identifier on every report — version, tag, or commit SHA |
+| `context` | `Record<string, unknown>` | - | App-owned key-values on every report (orgId, plan, flags) |
+| `responseBodyOrigins` | `string[]` | - | Extra origins whose failed-request bodies may be recorded. Same-origin is always recorded; third parties never are unless listed |
 
 ### Ignoring known-noisy errors
 
@@ -482,6 +671,48 @@ Some errors that reach `window.onerror` aren't app bugs — browser extension br
 </GlitchgrabProvider>
 ```
 
+## How do I attach my own context to reports?
+
+The SDK captures what a browser can see. It cannot know that this user is on the enterprise plan, in org 42, with the new billing flow switched on — and that is usually the difference between "a crash" and "a crash for one tenant on one flag".
+
+Attach your own keys once; every report from then on carries them:
+
+```tsx
+const { setContext, setContexts } = useGlitchgrab();
+
+setContext("orgId", org.id);
+setContexts({ plan: org.plan, role: user.role, newBilling: flags.newBilling });
+
+// Pass null to remove a key — a user who leaves an org stops reporting it
+setContext("orgId", null);
+```
+
+Or set them declaratively on the provider:
+
+```tsx
+<GlitchgrabProvider
+  token={process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!}
+  context={{ plan: org.plan, region: "in-south" }}
+>
+  {children}
+</GlitchgrabProvider>
+```
+
+They arrive on the report prefixed with `ctx_` (`ctx_orgId`, `ctx_plan`), so an app key named `timestamp` or `status` can never overwrite a field the dashboard relies on. `setContext` / `setContexts` are also exported standalone for non-React code, and the values survive navigation and provider remounts. Limits: 30 keys, 200 chars per value.
+
+## How do I tell which deploy broke?
+
+Pass a `release` and every report names the build it came from:
+
+```tsx
+<GlitchgrabProvider
+  token={process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!}
+  release={process.env.NEXT_PUBLIC_APP_VERSION}
+>
+```
+
+If you don't pass one, the SDK falls back to `NEXT_PUBLIC_APP_VERSION`, then `NEXT_PUBLIC_RELEASE`, then `NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA` — so on Vercel this works with no configuration at all.
+
 ## Do I need a Content-Security-Policy allowance?
 
 If your app sets a CSP header (e.g. via `proxy.ts` / `middleware.ts` in Next.js), allow Glitchgrab's API host so `fetch` calls from the SDK aren't blocked:
@@ -497,6 +728,7 @@ response.headers.set(
 - `connect-src https://glitchgrab.dev` — required for `sendReport`, `enhanceText`, `transcribeAudio`, and the report-fetching hooks/REST calls. All SDK requests go to this single host by default.
 - If you pass a custom `baseUrl` prop, allow that host instead (self-hosted or proxied deployments).
 - Screenshot capture (`html2canvas-pro`) runs entirely client-side against `document.body` — no network request, no extra `img-src`/`connect-src` needed for it.
+- `img-src` only matters if your `session` carries an avatar URL — the report dialog renders it. If your CSP blocks that host the dialog falls back to the reporter's initials, so it degrades rather than breaking.
 - No `script-src`, `style-src`, or `frame-src` allowances are required — the SDK doesn't load remote scripts, styles, or iframes.
 
 ## How does auto-capture work?
@@ -506,10 +738,27 @@ In production (`NODE_ENV=production`), the SDK automatically captures:
 - Unhandled promise rejections
 - Console errors (as breadcrumbs)
 - Navigation events (as breadcrumbs)
-- API calls (as breadcrumbs)
+- API calls, both `fetch` and `XMLHttpRequest` (as breadcrumbs)
+
+Both HTTP paths are patched, so **axios works** — axios uses `XMLHttpRequest` in the browser, not `fetch`.
+
+For a failed request the breadcrumb also carries the response body, so a `→ 500` says *why*. Guardrails:
+
+- **Same-origin only.** Your own API's error shape is yours; a third-party 422 from Stripe or Auth0 echoes fields you don't control (dates of birth, phone numbers) that would end up in a public GitHub issue. Third-party calls are still recorded — status, method, duration — just never their body.
+- Add trusted hosts explicitly when your API is on another origin:
+  ```tsx
+  <GlitchgrabProvider
+    token={process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!}
+    responseBodyOrigins={["https://api.myapp.com"]}
+  >
+  ```
+- Truncated to 500 chars; sensitively-named JSON keys dropped; emails, JWTs and bearer tokens scrubbed.
+- **Only non-2xx responses are read.** Successful traffic is never buffered.
 
 Auto-capture is **disabled in development** to avoid noisy issues.
 
+It does **not** cover React errors that a framework error boundary handles — those never reach `window.onerror`. Call [`captureError`](#how-do-i-capture-app-router-crashes) from your boundary to report them.
+
 ## What data is included in each report?
 
 - Description from the user
@@ -517,8 +766,11 @@ Auto-capture is **disabled in development** to avoid noisy issues.
 - Page URL and user agent
 - Device info (screen size, viewport, platform, language, color scheme)
 - Page navigation history
-- Activity log (last 15 breadcrumbs)
+- Activity log (last 15 breadcrumbs), including failed API calls with their response body
 - Session info (userId, name, email, phone)
+- Release / build identifier
+- Your own context keys (`ctx_orgId`, `ctx_plan`, …)
+- Runtime health — time on page, error count this session, tab visibility, JS heap usage, connection type and RTT (heap and connection are Chromium-only)
 
 ## License
 

package/dist/index.d.mts

@@ -35,6 +35,21 @@ interface ReportPayload {
     deviceInfo?: DeviceInfo;
     metadata?: Record<string, string>;
 }
+/** Extra context for an error your app already caught — see `captureError` */
+interface CaptureErrorOptions {
+    /** React component stack, e.g. from `componentDidCatch` / `onCaughtError` */
+    componentStack?: string;
+    /**
+     * Next.js error digest. In production Next replaces server-boundary error
+     * messages with a generic string — the digest is the only thing that tells
+     * two different crashes apart, so it also feeds the dedup signature.
+     */
+    digest?: string;
+    /** Which boundary caught it, e.g. `"next-app-router"` — attached as metadata */
+    boundary?: string;
+    /** Extra metadata merged into the report */
+    metadata?: Record<string, string>;
+}
 interface ReportResult {
     success: boolean;
     reportId?: string;
@@ -44,6 +59,34 @@ interface ReportResult {
     intent?: string;
     message?: string;
 }
+interface FeedbackPayload {
+    token: string;
+    /** 1–5 stars */
+    rating: number;
+    message?: string;
+    pageUrl?: string;
+    userAgent?: string;
+    metadata?: Record<string, string>;
+}
+interface FeedbackResult {
+    success: boolean;
+    feedbackId?: string;
+    rating?: number;
+    createdAt?: string;
+    message?: string;
+}
+/** One stored feedback entry, as returned by the read endpoint. */
+interface GlitchgrabFeedback {
+    id: string;
+    rating: number;
+    message: string | null;
+    pageUrl: string | null;
+    /** Whether the repo owner published this entry for public display */
+    approved: boolean;
+    reporterPrimaryKey: string;
+    reporterName: string;
+    createdAt: string;
+}
 type BreadcrumbType = "console" | "navigation" | "api" | "click" | "error" | "custom";
 interface Breadcrumb {
     type: BreadcrumbType;
@@ -62,6 +105,26 @@ interface DeviceInfo {
     colorScheme: string;
     devicePixelRatio: number;
 }
+/**
+ * Machine state at the moment of the crash, as opposed to `DeviceInfo`, which
+ * describes the machine itself. Most fields are Chromium-only and simply absent
+ * elsewhere — never assume one is present.
+ */
+interface RuntimeInfo {
+    /** ms since this page loaded */
+    timeOnPageMs: number;
+    /** How many errors the SDK has already auto-captured in this page session */
+    errorCount: number;
+    /** `document.visibilityState` — a crash in a background tab reads differently */
+    visibility: string;
+    jsHeapUsedMb?: number;
+    jsHeapLimitMb?: number;
+    /** `navigator.connection.effectiveType` — "4g", "3g", "2g", "slow-2g" */
+    connectionType?: string;
+    downlinkMbps?: number;
+    rttMs?: number;
+    saveData?: boolean;
+}
 interface CapturedContext {
     url: string;
     userAgent: string;
@@ -69,6 +132,12 @@ interface CapturedContext {
     visitedPages: string[];
     breadcrumbs: Breadcrumb[];
     deviceInfo: DeviceInfo | null;
+    /** Runtime health snapshot — null when unavailable (SSR) */
+    runtime: RuntimeInfo | null;
+    /** Key-values the host app attached via `setContext` */
+    appContext: Record<string, string>;
+    /** Build identifier this crash came from, if known */
+    release?: string;
 }
 interface GlitchgrabSession {
     /** Primary key of the user in your database (required) */
@@ -103,17 +172,69 @@ interface GlitchgrabProviderProps {
      * signatures that aren't app bugs — e.g. browser extension bridge errors.
      */
     ignoreErrors?: (string | RegExp)[];
+    /**
+     * Build identifier attached to every report — a version, a tag, a commit SHA.
+     * Tells you which deploy introduced a crash. Falls back to
+     * `NEXT_PUBLIC_APP_VERSION`, `NEXT_PUBLIC_RELEASE`, then
+     * `NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA` when not passed.
+     */
+    release?: string;
+    /**
+     * App-owned context attached to every report — orgId, plan, role, feature
+     * flags. Merged with anything set imperatively via `setContext`.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Extra origins whose failed-request bodies may be recorded in breadcrumbs,
+     * e.g. `["https://api.myapp.com"]`. Same-origin requests are always recorded;
+     * third-party APIs are excluded by default because their error envelopes carry
+     * data you don't control and shouldn't forward into a GitHub issue.
+     */
+    responseBodyOrigins?: string[];
 }
 interface ReportButtonProps {
     position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
     label?: string;
     className?: string;
 }
+interface FeedbackButtonProps {
+    position?: "bottom-right" | "bottom-left" | "top-right" | "top-left";
+    label?: string;
+    className?: string;
+    /** Heading inside the dialog (default: "How are we doing?") */
+    title?: string;
+    /** Placeholder for the message box */
+    placeholder?: string;
+    /** Shown after a successful submit */
+    thanksMessage?: string;
+}
 interface UseGlitchgrabReturn {
     /** Report a bug programmatically */
     reportBug: (description: string, metadata?: Record<string, string>) => Promise<ReportResult | null>;
     /** Report with a specific type */
     report: (type: ReportType, description: string, metadata?: Record<string, string>) => Promise<ReportResult | null>;
+    /**
+     * Report an error your app already caught — a framework error boundary
+     * (`app/error.tsx`, React Router `errorElement`, Remix `ErrorBoundary`) or a
+     * `try/catch`. These never reach `window.onerror`, so auto-capture misses them.
+     * Sends `SDK_AUTO`. Fire-and-forget, never throws.
+     */
+    captureError: (error: unknown, options?: CaptureErrorOptions) => void;
+    /**
+     * Attach a key-value to every future report — orgId, plan, role, feature flag.
+     * Pass `null` to remove a key. Survives navigation and provider remounts.
+     */
+    setContext: (key: string, value: unknown) => void;
+    /** Set several context keys at once. Merges; does not replace. */
+    setContexts: (values: Record<string, unknown>) => void;
+    /**
+     * Save a 1–5 star rating your end-user left about your app. Stored by
+     * Glitchgrab and shown on your Feedback page — never becomes a GitHub issue.
+     * Returns null on any failure (never throws).
+     */
+    sendFeedback: (rating: number, message?: string, metadata?: Record<string, string>) => Promise<FeedbackResult | null>;
+    /** Open the built-in feedback dialog (stars + message) programmatically */
+    openFeedbackDialog: () => void;
     /** Add a custom breadcrumb */
     addBreadcrumb: (message: string, data?: Record<string, string>) => void;
     /** Open the ReportButton modal programmatically (captures screenshot + shows dialog) */
@@ -144,11 +265,14 @@ interface UseGlitchgrabReturn {
  *
  * @example
  * ```tsx
- * const { reportBug, report, addBreadcrumb } = useGlitchgrab();
+ * const { reportBug, report, captureError, addBreadcrumb } = useGlitchgrab();
  *
  * // Report a bug
  * reportBug("Login button crashes on mobile");
  *
+ * // Report an error your own boundary already caught (e.g. app/error.tsx)
+ * captureError(error, { digest: error.digest, boundary: "next-app-router" });
+ *
  * // Report a feature request
  * report("FEATURE_REQUEST", "Add dark mode");
  *
@@ -188,6 +312,31 @@ declare function ReportButton({ position, label, className, children, }: ReportB
     }) => ReactNode;
 }): react_jsx_runtime.JSX.Element | null;
 
+/**
+ * Trigger for the built-in feedback dialog (stars + message).
+ *
+ * The dialog itself lives inside `GlitchgrabProvider` — this is only the visible
+ * trigger. Open it programmatically with `useGlitchgrab().openFeedbackDialog()`,
+ * or skip the dialog entirely and call `sendFeedback(rating, message)` from your
+ * own UI.
+ *
+ * @example
+ * ```tsx
+ * // Default floating button
+ * <FeedbackButton />
+ *
+ * // Your own trigger
+ * <FeedbackButton>
+ *   {({ onClick }) => <button onClick={onClick}>Rate us</button>}
+ * </FeedbackButton>
+ * ```
+ */
+declare function FeedbackButton({ position, label, className, children, }: FeedbackButtonProps & {
+    children?: (props: {
+        onClick: () => void;
+    }) => ReactNode;
+}): react_jsx_runtime.JSX.Element | null;
+
 interface ErrorBoundaryProps {
     token: string;
     baseUrl?: string;
@@ -207,6 +356,52 @@ declare class GlitchgrabErrorBoundary extends React.Component<ErrorBoundaryProps
     render(): React.ReactNode;
 }
 
+/**
+ * Report an error your app already caught — a framework error boundary
+ * (`app/error.tsx`, `app/global-error.tsx`, React Router `errorElement`, Remix
+ * `ErrorBoundary`), a `componentDidCatch`, or a `try/catch` you want filed.
+ *
+ * These never reach `window.onerror`, so provider auto-capture cannot see them.
+ *
+ * Fire-and-forget. Never throws, never blocks the fallback UI render. No-ops if
+ * no `GlitchgrabProvider` has rendered yet (nothing to authenticate with).
+ *
+ * @example
+ * ```tsx
+ * // app/global-error.tsx — renders outside the provider tree
+ * "use client";
+ * import { captureError } from "glitchgrab";
+ *
+ * export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
+ *   useEffect(() => {
+ *     captureError(error, { digest: error.digest, boundary: "next-global-error" });
+ *   }, [error]);
+ *   return <html><body><p>Something went wrong</p></body></html>;
+ * }
+ * ```
+ */
+declare function captureError(error: unknown, options?: CaptureErrorOptions): void;
+
+/**
+ * App-owned context: key-values the host app attaches once and every report
+ * carries thereafter — orgId, plan, role, active feature flags. The SDK cannot
+ * guess these, and they are usually the difference between "a crash" and "a
+ * crash for enterprise tenants on the new billing flow".
+ *
+ * Module-level, not React state, so it survives the provider unmount that
+ * `global-error.tsx` causes and is readable from non-React call sites.
+ */
+/**
+ * Attach one key-value to every future report. Passing `null`/`undefined`
+ * removes the key — so a value that goes away (user logs out of an org) stops
+ * being reported instead of going stale.
+ */
+declare function setContext(key: string, value: unknown): void;
+/** Set several keys at once. Merges — it does not replace what's already set. */
+declare function setContexts(values: Record<string, unknown>): void;
+declare function getAppContext(): Record<string, string>;
+declare function clearAppContext(): void;
+
 interface GlitchgrabReport {
     id: string;
     source: string;
@@ -299,7 +494,60 @@ declare function useGlitchgrabActions({ token, onSuccess, onError, }: {
     error: string | null;
 };
 
-declare function initBreadcrumbs(max?: number): void;
+interface FeedbackQuery {
+    token: string;
+    /** Only entries the repo owner published — use this for a public testimonials wall */
+    approvedOnly?: boolean;
+    /** Only this end-user's feedback (their primary key in your DB) */
+    userId?: string;
+    /** Floor on the star rating, 1–5 */
+    minRating?: number;
+    /** Max results (default 50, max 100) */
+    limit?: number;
+    baseUrl?: string;
+}
+/**
+ * Standalone fetcher — use with TanStack Query or any data fetching library.
+ *
+ * ```tsx
+ * const { data } = useQuery({
+ *   queryKey: ["testimonials"],
+ *   queryFn: () => fetchGlitchgrabFeedback({
+ *     token: process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!,
+ *     approvedOnly: true,
+ *     minRating: 4,
+ *   }),
+ * });
+ * ```
+ */
+declare function fetchGlitchgrabFeedback(query: FeedbackQuery): Promise<GlitchgrabFeedback[]>;
+/**
+ * Hook to read back the feedback your end-users left — render it as a
+ * testimonials wall, or show a user their own past ratings.
+ *
+ * ```tsx
+ * const { feedback, isLoading, error, refetch } = useGlitchgrabFeedback({
+ *   token: process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!,
+ *   approvedOnly: true,
+ * });
+ * ```
+ */
+declare function useGlitchgrabFeedback(query: FeedbackQuery): {
+    feedback: GlitchgrabFeedback[];
+    isLoading: boolean;
+    isFetching: boolean;
+    error: string | null;
+    refetch: () => Promise<void>;
+};
+
+interface BreadcrumbOptions {
+    /**
+     * Additional origins to capture error response bodies from, e.g.
+     * `["https://api.myapp.com"]`. Same-origin requests are always captured.
+     */
+    responseBodyOrigins?: string[];
+}
+declare function initBreadcrumbs(max?: number, options?: BreadcrumbOptions): void;
 declare function addBreadcrumb(type: BreadcrumbType, message: string, data?: Record<string, string>): void;
 declare function getBreadcrumbs(): Breadcrumb[];
 declare function clearBreadcrumbs(): void;
@@ -330,6 +578,15 @@ declare function captureContext(visitedPages: string[]): CapturedContext;
  * Never throws — returns null on failure.
  */
 declare function sendReport(payload: ReportPayload, baseUrl?: string): Promise<ReportResult | null>;
+/**
+ * Save a star rating your end-user left about your app.
+ * Never throws — returns null on failure.
+ *
+ * Unlike `sendReport`, this is always a deliberate user action with a dialog
+ * open in front of them, so it retries on transient failure but skips the
+ * sendBeacon fallback: the caller needs a real result to show a thank-you.
+ */
+declare function sendFeedback(payload: FeedbackPayload, baseUrl?: string): Promise<FeedbackResult | null>;
 interface EnhanceContext {
     url?: string;
     visitedPages?: string[];
@@ -349,8 +606,14 @@ declare function computeSignature(params: {
     errorMessage: string | undefined;
     pageUrl: string | undefined;
     errorStack?: string | undefined;
+    /**
+     * Next.js error digest. Production strips server-boundary errors to a generic
+     * message with no useful stack, so without the digest every distinct server
+     * crash on one page collapses into a single signature.
+     */
+    digest?: string | undefined;
 }): string;
 declare function shouldSkipDuplicate(signature: string, windowMs?: number, now?: number): boolean;
 declare function clearDedupCache(): void;
 
-export { type Breadcrumb, type BreadcrumbType, type CapturedContext, type DeviceInfo, GLITCHGRAB_SHORTCUT, GLITCHGRAB_SHORTCUT_MAC, type GlitchgrabConfig, GlitchgrabErrorBoundary, GlitchgrabProvider, type GlitchgrabProviderProps, type GlitchgrabReport, type GlitchgrabSession, ReportButton, type ReportButtonProps, type ReportPayload, type ReportResult, type ReportSeverity, type ReportType, type UseGlitchgrabReturn, addBreadcrumb, captureContext, captureDeviceInfo, clearBreadcrumbs, clearDedupCache, computeSignature, enhanceText, fetchGlitchgrabReports, getBreadcrumbs, getShortcutLabel, initBreadcrumbs, matchesShortcut, sanitizeUrl, sendReport, shouldSkipDuplicate, useGlitchgrab, useGlitchgrabActions, useGlitchgrabReports };
+export { type Breadcrumb, type BreadcrumbType, type CaptureErrorOptions, type CapturedContext, type DeviceInfo, FeedbackButton, type FeedbackButtonProps, type FeedbackPayload, type FeedbackQuery, type FeedbackResult, GLITCHGRAB_SHORTCUT, GLITCHGRAB_SHORTCUT_MAC, type GlitchgrabConfig, GlitchgrabErrorBoundary, type GlitchgrabFeedback, GlitchgrabProvider, type GlitchgrabProviderProps, type GlitchgrabReport, type GlitchgrabSession, ReportButton, type ReportButtonProps, type ReportPayload, type ReportResult, type ReportSeverity, type ReportType, type RuntimeInfo, type UseGlitchgrabReturn, addBreadcrumb, captureContext, captureDeviceInfo, captureError, clearAppContext, clearBreadcrumbs, clearDedupCache, computeSignature, enhanceText, fetchGlitchgrabFeedback, fetchGlitchgrabReports, getAppContext, getBreadcrumbs, getShortcutLabel, initBreadcrumbs, matchesShortcut, sanitizeUrl, sendFeedback, sendReport, setContext, setContexts, shouldSkipDuplicate, useGlitchgrab, useGlitchgrabActions, useGlitchgrabFeedback, useGlitchgrabReports };