glitchgrab 0.1.0

package/README.md

@@ -0,0 +1,167 @@
+# glitchgrab
+
+Drop-in error capture and bug reporting for Next.js apps. Production errors automatically become GitHub issues.
+
+## Install
+
+```bash
+npm install glitchgrab
+# or
+bun add glitchgrab
+```
+
+## Quick Start
+
+Wrap your app with `GlitchgrabProvider` — that's it:
+
+```tsx
+// app/layout.tsx
+import { GlitchgrabProvider } from "glitchgrab";
+
+export default function RootLayout({ children }) {
+  return (
+    <GlitchgrabProvider token="gg_your_token">
+      {children}
+    </GlitchgrabProvider>
+  );
+}
+```
+
+This gives you:
+- Auto-capture of unhandled errors and promise rejections
+- Error boundary around your entire app
+- Page visit tracking for reproduction context
+- URL sanitization (strips tokens, keys, passwords)
+
+## Get a Token
+
+1. Go to [glitchgrab.dev](https://glitchgrab.dev)
+2. Sign in with GitHub
+3. Connect a repo
+4. Generate an API token
+
+## Usage
+
+### 1. Auto-Capture (zero config)
+
+Just add the provider. Production errors are captured automatically with:
+- Error message and stack trace
+- Current URL (sanitized)
+- User agent
+- Visited pages history
+
+### 2. Manual Bug Reporting (`useGlitchgrab` hook)
+
+Build your own report button or trigger:
+
+```tsx
+"use client";
+import { useGlitchgrab } from "glitchgrab";
+
+function MyReportButton() {
+  const { reportBug } = useGlitchgrab();
+
+  return (
+    <button onClick={() => reportBug("The checkout flow is broken")}>
+      Report Bug
+    </button>
+  );
+}
+```
+
+With metadata:
+
+```tsx
+reportBug("Payment failed", {
+  userId: "123",
+  plan: "pro",
+  browser: "Chrome 120",
+});
+```
+
+### 3. Pre-built Report Button (optional)
+
+If you want a ready-made floating button:
+
+```tsx
+import { GlitchgrabProvider, ReportButton } from "glitchgrab";
+
+<GlitchgrabProvider token="gg_your_token">
+  {children}
+  <ReportButton />
+</GlitchgrabProvider>
+```
+
+Options:
+
+```tsx
+<ReportButton
+  position="bottom-left"  // "bottom-right" (default) | "bottom-left"
+  label="Report Issue"    // default: "Report Bug"
+/>
+```
+
+### 4. Custom Error Boundary
+
+Wrap specific sections with a custom fallback:
+
+```tsx
+import { GlitchgrabErrorBoundary } from "glitchgrab";
+
+<GlitchgrabErrorBoundary
+  token="gg_your_token"
+  fallback={<div>Something went wrong in this section</div>}
+>
+  <DangerousComponent />
+</GlitchgrabErrorBoundary>
+```
+
+### 5. Provider Options
+
+```tsx
+<GlitchgrabProvider
+  token="gg_your_token"         // Required — your API token
+  baseUrl="https://your-api.com" // Optional — custom API URL (default: glitchgrab.dev)
+  onError={(error) => {          // Optional — callback when errors are captured
+    console.log("Captured:", error.message);
+  }}
+  fallback={<ErrorPage />}       // Optional — what to show when the app crashes
+>
+  {children}
+</GlitchgrabProvider>
+```
+
+## API Reference
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `GlitchgrabProvider` | Wraps your app. Captures errors, tracks pages. |
+| `ReportButton` | Optional floating bug report button with modal. |
+| `GlitchgrabErrorBoundary` | Standalone error boundary for specific sections. |
+
+### Hooks
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useGlitchgrab()` | `{ reportBug, token, baseUrl }` | Access bug reporting in any component. |
+
+### Utilities
+
+| Function | Description |
+|----------|-------------|
+| `sanitizeUrl(url)` | Strips sensitive query params from URLs. |
+| `captureContext(pages)` | Returns current URL, user agent, timestamp. |
+| `sendReport(payload, baseUrl)` | Low-level function to send a report. |
+
+## Safety
+
+- **Never crashes your app.** Every function is wrapped in try/catch.
+- **Non-blocking.** Uses `fetch` with `keepalive` and `sendBeacon` fallback.
+- **No sensitive data leaked.** URLs are sanitized before sending.
+- **Zero external dependencies.** Only peer deps on React and Next.js.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,149 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode } from 'react';
+
+interface GlitchgrabConfig {
+    token: string;
+    baseUrl?: string;
+    onError?: (error: Error) => void;
+    /** Called after a report is sent — use to sync with your own ticket system */
+    onReportSent?: (result: ReportResult) => void;
+    /** Enable breadcrumb tracking (default: true) */
+    breadcrumbs?: boolean;
+    /** Max breadcrumbs to keep (default: 50) */
+    maxBreadcrumbs?: number;
+}
+type ReportType = "BUG" | "FEATURE_REQUEST" | "QUESTION" | "OTHER";
+interface ReportPayload {
+    token: string;
+    source: "SDK_AUTO" | "SDK_USER_REPORT";
+    type?: ReportType;
+    description?: string;
+    errorMessage?: string;
+    errorStack?: string;
+    componentStack?: string;
+    pageUrl?: string;
+    userAgent?: string;
+    breadcrumbs?: Breadcrumb[];
+    deviceInfo?: DeviceInfo;
+    metadata?: Record<string, string>;
+}
+interface ReportResult {
+    success: boolean;
+    reportId?: string;
+    issueUrl?: string;
+    issueNumber?: number;
+    title?: string;
+    intent?: string;
+    message?: string;
+}
+type BreadcrumbType = "console" | "navigation" | "api" | "click" | "error" | "custom";
+interface Breadcrumb {
+    type: BreadcrumbType;
+    message: string;
+    timestamp: string;
+    data?: Record<string, string>;
+}
+interface DeviceInfo {
+    screenWidth: number;
+    screenHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    platform: string;
+    language: string;
+    online: boolean;
+    colorScheme: string;
+    devicePixelRatio: number;
+}
+interface CapturedContext {
+    url: string;
+    userAgent: string;
+    timestamp: string;
+    visitedPages: string[];
+    breadcrumbs: Breadcrumb[];
+    deviceInfo: DeviceInfo | null;
+}
+interface GlitchgrabProviderProps {
+    token: string;
+    baseUrl?: string;
+    onError?: (error: Error) => void;
+    onReportSent?: (result: ReportResult) => void;
+    breadcrumbs?: boolean;
+    maxBreadcrumbs?: number;
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface ReportButtonProps {
+    position?: "bottom-right" | "bottom-left";
+    label?: string;
+    className?: string;
+    /** Allow reporting feature requests, questions, not just bugs */
+    types?: ReportType[];
+}
+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>;
+    /** Add a custom breadcrumb */
+    addBreadcrumb: (message: string, data?: Record<string, string>) => void;
+    /** The token being used */
+    token: string;
+    /** The base URL of the Glitchgrab API */
+    baseUrl: string;
+}
+
+/**
+ * Hook to access Glitchgrab in your components.
+ *
+ * @example
+ * ```tsx
+ * const { reportBug, report, addBreadcrumb } = useGlitchgrab();
+ *
+ * // Report a bug
+ * reportBug("Login button crashes on mobile");
+ *
+ * // Report a feature request
+ * report("FEATURE_REQUEST", "Add dark mode");
+ *
+ * // Add a custom breadcrumb
+ * addBreadcrumb("User clicked checkout", { cartItems: "3" });
+ * ```
+ */
+declare function useGlitchgrab(): UseGlitchgrabReturn;
+declare function GlitchgrabProvider(props: GlitchgrabProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function ReportButton({ position, label, className, }: ReportButtonProps): react_jsx_runtime.JSX.Element;
+
+interface ErrorBoundaryProps {
+    token: string;
+    baseUrl?: string;
+    onError?: (error: Error) => void;
+    fallback?: React.ReactNode;
+    visitedPages: string[];
+    children: React.ReactNode;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+}
+declare class GlitchgrabErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    render(): React.ReactNode;
+}
+
+declare function initBreadcrumbs(max?: number): void;
+declare function addBreadcrumb(type: BreadcrumbType, message: string, data?: Record<string, string>): void;
+declare function getBreadcrumbs(): Breadcrumb[];
+declare function clearBreadcrumbs(): void;
+
+declare function sanitizeUrl(url: string): string;
+declare function captureDeviceInfo(): DeviceInfo | null;
+declare function captureContext(visitedPages: string[]): CapturedContext;
+/**
+ * Send a report and return the result.
+ * Never throws — returns null on failure.
+ */
+declare function sendReport(payload: ReportPayload, baseUrl?: string): Promise<ReportResult | null>;
+
+export { type Breadcrumb, type BreadcrumbType, type CapturedContext, type DeviceInfo, type GlitchgrabConfig, GlitchgrabErrorBoundary, GlitchgrabProvider, type GlitchgrabProviderProps, ReportButton, type ReportButtonProps, type ReportPayload, type ReportResult, type ReportType, type UseGlitchgrabReturn, addBreadcrumb, captureContext, captureDeviceInfo, clearBreadcrumbs, getBreadcrumbs, initBreadcrumbs, sanitizeUrl, sendReport, useGlitchgrab };

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode } from 'react';
+
+interface GlitchgrabConfig {
+    token: string;
+    baseUrl?: string;
+    onError?: (error: Error) => void;
+    /** Called after a report is sent — use to sync with your own ticket system */
+    onReportSent?: (result: ReportResult) => void;
+    /** Enable breadcrumb tracking (default: true) */
+    breadcrumbs?: boolean;
+    /** Max breadcrumbs to keep (default: 50) */
+    maxBreadcrumbs?: number;
+}
+type ReportType = "BUG" | "FEATURE_REQUEST" | "QUESTION" | "OTHER";
+interface ReportPayload {
+    token: string;
+    source: "SDK_AUTO" | "SDK_USER_REPORT";
+    type?: ReportType;
+    description?: string;
+    errorMessage?: string;
+    errorStack?: string;
+    componentStack?: string;
+    pageUrl?: string;
+    userAgent?: string;
+    breadcrumbs?: Breadcrumb[];
+    deviceInfo?: DeviceInfo;
+    metadata?: Record<string, string>;
+}
+interface ReportResult {
+    success: boolean;
+    reportId?: string;
+    issueUrl?: string;
+    issueNumber?: number;
+    title?: string;
+    intent?: string;
+    message?: string;
+}
+type BreadcrumbType = "console" | "navigation" | "api" | "click" | "error" | "custom";
+interface Breadcrumb {
+    type: BreadcrumbType;
+    message: string;
+    timestamp: string;
+    data?: Record<string, string>;
+}
+interface DeviceInfo {
+    screenWidth: number;
+    screenHeight: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    platform: string;
+    language: string;
+    online: boolean;
+    colorScheme: string;
+    devicePixelRatio: number;
+}
+interface CapturedContext {
+    url: string;
+    userAgent: string;
+    timestamp: string;
+    visitedPages: string[];
+    breadcrumbs: Breadcrumb[];
+    deviceInfo: DeviceInfo | null;
+}
+interface GlitchgrabProviderProps {
+    token: string;
+    baseUrl?: string;
+    onError?: (error: Error) => void;
+    onReportSent?: (result: ReportResult) => void;
+    breadcrumbs?: boolean;
+    maxBreadcrumbs?: number;
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface ReportButtonProps {
+    position?: "bottom-right" | "bottom-left";
+    label?: string;
+    className?: string;
+    /** Allow reporting feature requests, questions, not just bugs */
+    types?: ReportType[];
+}
+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>;
+    /** Add a custom breadcrumb */
+    addBreadcrumb: (message: string, data?: Record<string, string>) => void;
+    /** The token being used */
+    token: string;
+    /** The base URL of the Glitchgrab API */
+    baseUrl: string;
+}
+
+/**
+ * Hook to access Glitchgrab in your components.
+ *
+ * @example
+ * ```tsx
+ * const { reportBug, report, addBreadcrumb } = useGlitchgrab();
+ *
+ * // Report a bug
+ * reportBug("Login button crashes on mobile");
+ *
+ * // Report a feature request
+ * report("FEATURE_REQUEST", "Add dark mode");
+ *
+ * // Add a custom breadcrumb
+ * addBreadcrumb("User clicked checkout", { cartItems: "3" });
+ * ```
+ */
+declare function useGlitchgrab(): UseGlitchgrabReturn;
+declare function GlitchgrabProvider(props: GlitchgrabProviderProps): react_jsx_runtime.JSX.Element;
+
+declare function ReportButton({ position, label, className, }: ReportButtonProps): react_jsx_runtime.JSX.Element;
+
+interface ErrorBoundaryProps {
+    token: string;
+    baseUrl?: string;
+    onError?: (error: Error) => void;
+    fallback?: React.ReactNode;
+    visitedPages: string[];
+    children: React.ReactNode;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+}
+declare class GlitchgrabErrorBoundary extends React.Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    render(): React.ReactNode;
+}
+
+declare function initBreadcrumbs(max?: number): void;
+declare function addBreadcrumb(type: BreadcrumbType, message: string, data?: Record<string, string>): void;
+declare function getBreadcrumbs(): Breadcrumb[];
+declare function clearBreadcrumbs(): void;
+
+declare function sanitizeUrl(url: string): string;
+declare function captureDeviceInfo(): DeviceInfo | null;
+declare function captureContext(visitedPages: string[]): CapturedContext;
+/**
+ * Send a report and return the result.
+ * Never throws — returns null on failure.
+ */
+declare function sendReport(payload: ReportPayload, baseUrl?: string): Promise<ReportResult | null>;
+
+export { type Breadcrumb, type BreadcrumbType, type CapturedContext, type DeviceInfo, type GlitchgrabConfig, GlitchgrabErrorBoundary, GlitchgrabProvider, type GlitchgrabProviderProps, ReportButton, type ReportButtonProps, type ReportPayload, type ReportResult, type ReportType, type UseGlitchgrabReturn, addBreadcrumb, captureContext, captureDeviceInfo, clearBreadcrumbs, getBreadcrumbs, initBreadcrumbs, sanitizeUrl, sendReport, useGlitchgrab };