### Getting Started with Glitchgrab

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/README.md

Provides the necessary commands to clone the repository, install dependencies using bun, set up environment variables, and start the development server.

```bash
git clone https://github.com/webnaresh/glitchgrab.git
cd glitchgrab
bun install
cp apps/web/.env.example apps/web/.env.local
# Fill in your keys
bun run dev
```

--------------------------------

### Start Development Server with Bun

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/CLAUDE.md

Starts all applications in development mode using Bun.

```bash
bun run dev
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/CLAUDE.md

Installs all project dependencies using the Bun package manager.

```bash
bun install
```

--------------------------------

### Build and Install Production Android APK with Bun

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/CLAUDE.md

Builds a production Android APK and installs it on a connected device via ADB using Bun.

```bash
bun run install:android:prod
```

--------------------------------

### Install Glitchgrab SDK

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/packages/sdk-nextjs/README.md

Install the Glitchgrab SDK using npm or bun.

```bash
npm install glitchgrab
# or
bun add glitchgrab
```

--------------------------------

### Build and Install Development Android APK with Bun

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/CLAUDE.md

Builds a development Android APK and installs it on a connected device via ADB using Bun.

```bash
bun run install:android:dev
```

--------------------------------

### GlitchgrabProvider Setup

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/packages/sdk-nextjs/README.md

Wrap your Next.js application with GlitchgrabProvider to enable Glitchgrab's features. Ensure you provide your public Glitchgrab token.

```APIDOC
## GlitchgrabProvider Setup

Wrap your app with `GlitchgrabProvider`:

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

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

--------------------------------

### Fetch GlitchGrab Reports using TanStack Query

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/packages/sdk-nextjs/README.md

Example of how to fetch GlitchGrab reports using the `fetchGlitchgrabReports` function with TanStack Query for efficient data fetching and caching.

```APIDOC
## Fetch GlitchGrab Reports with TanStack Query

### Description
Use the `fetchGlitchgrabReports` function within a `useQuery` hook to fetch reports. This method leverages TanStack Query for state management, caching, and background updates.

### Usage
```tsx
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,
  }),
});
```

### Parameters for `fetchGlitchgrabReports`
- **token** (string) - Required - Your GlitchGrab API token.
- **userId** (string) - Required - The ID of the user whose reports you want to fetch.
- **limit** (number) - Optional - The maximum number of reports to return.
```

--------------------------------

### REST API - Get All Reports

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Fetches all reports for a repository, with optional filters. Returns live GitHub issue state and comment counts.

```APIDOC
## GET /api/v1/sdk/reports

### Description
Fetch all reports for a repository, with optional filters by reporter primary key, status, and limit. Returns live GitHub issue state (open/closed) and comment counts.

### Method
GET

### Endpoint
https://www.glitchgrab.dev/api/v1/sdk/reports

### Query Parameters
- **reporterPrimaryKey** (string) - Optional - Filter reports by the reporter's primary key.
- **status** (string) - Optional - Filter reports by status (e.g., "PENDING", "PROCESSING", "CREATED", "FAILED").
- **limit** (integer) - Optional - The maximum number of reports to return.

### Request Example (All reports)
```bash
curl -H "Authorization: Bearer gg_your_token" \
  "https://www.glitchgrab.dev/api/v1/sdk/reports"
```

### Request Example (Filtered by user and limit)
```bash
curl -H "Authorization: Bearer gg_your_token" \
  "https://www.glitchgrab.dev/api/v1/sdk/reports?reporterPrimaryKey=user_123&limit=20"
```

### Request Example (Filtered by status and limit)
```bash
curl -H "Authorization: Bearer gg_your_token" \
  "https://www.glitchgrab.dev/api/v1/sdk/reports?status=CREATED&limit=50"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (array) - A list of report objects.
  - **id** (string) - Unique ID of the report.
  - **source** (string) - Source of the report (e.g., "SDK_USER_REPORT").
  - **status** (string) - Current status of the report.
  - **rawInput** (string) - The raw input provided for the report.
  - **reporterPrimaryKey** (string) - Primary key of the reporter.
  - **reporterName** (string) - Name of the reporter.
  - **reporterEmail** (string) - Email of the reporter.
  - **reporterPhone** (string) - Phone number of the reporter (nullable).
  - **pageUrl** (string) - URL where the report originated.
  - **createdAt** (string) - ISO 8601 timestamp of when the report was created.
  - **commentCount** (integer) - Number of comments on the associated GitHub issue.
  - **issue** (object) - Information about the associated GitHub issue.
    - **githubNumber** (integer) - GitHub issue number.
    - **githubUrl** (string) - URL of the GitHub issue.
    - **title** (string) - Title of the GitHub issue.
    - **labels** (array) - Labels applied to the GitHub issue.
    - **severity** (string) - Severity level of the issue.
    - **githubState** (string) - State of the GitHub issue (e.g., "open").

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "cmn7abc123",
      "source": "SDK_USER_REPORT",
      "status": "CREATED",
      "rawInput": "Payment button unresponsive",
      "reporterPrimaryKey": "user_123",
      "reporterName": "Alice Smith",
      "reporterEmail": "alice@example.com",
      "reporterPhone": null,
      "pageUrl": "https://myapp.com/checkout",
      "createdAt": "2026-04-30T10:00:00.000Z",
      "commentCount": 2,
      "issue": {
        "githubNumber": 99,
        "githubUrl": "https://github.com/your/repo/issues/99",
        "title": "Payment button unresponsive on Safari iOS 17",
        "labels": ["bug", "severity:high"],
        "severity": "high",
        "githubState": "open"
      }
    }
  ]
}
```
```

--------------------------------

### Fetch Reports using GlitchGrab REST API

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/packages/sdk-nextjs/README.md

Examples of how to fetch reports using cURL commands, demonstrating fetching all reports, reports for a specific user, and filtering by status.

```APIDOC
## Fetch Reports using REST API

### Description
Directly interact with the GlitchGrab REST API to fetch reports. You can retrieve all reports, filter by reporter, or by status.

### Endpoints

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

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

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

### Parameters
- **Authorization** (string) - Required - Bearer token for authentication (e.g., `Bearer gg_your_token`).
- **reporterPrimaryKey** (string) - Optional - Filter reports by user ID.
- **status** (string) - Optional - Filter reports by their status (e.g., `PENDING`, `PROCESSING`, `CREATED`, `FAILED`).
- **limit** (number) - Optional - The maximum number of reports to return.
```

--------------------------------

### Fetch All Reports with Filters using REST API

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Retrieve all reports for a repository using the GET /api/v1/sdk/reports endpoint. You can filter by 'reporterPrimaryKey', 'status', and 'limit'. The response includes live GitHub issue state and comment counts.

```bash
# All reports for the repo
curl -H "Authorization: Bearer gg_your_token" \
  "https://www.glitchgrab.dev/api/v1/sdk/reports"
```

```bash
# Reports by a specific user (the userId passed in session.userId)
curl -H "Authorization: Bearer gg_your_token" \
  "https://www.glitchgrab.dev/api/v1/sdk/reports?reporterPrimaryKey=user_123&limit=20"
```

```bash
# Filter by status: PENDING | PROCESSING | CREATED | FAILED
curl -H "Authorization: Bearer gg_your_token" \
  "https://www.glitchgrab.dev/api/v1/sdk/reports?status=CREATED&limit=50"
```

--------------------------------

### Glitchgrab API Report Response (JSON)

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/packages/sdk-nextjs/README.md

Example JSON response when fetching a report, including issue details and a list of comments.

```json
{
  "success": true,
  "data": {
    "id": "cmn7abc123",
    "issue": {
      "title": "Button not working",
      "body": "## Description\n\nThe submit button...",
      "githubState": "open",
      "labels": ["bug"]
    },
    "comments": [
      {
        "author": "WebNaresh",
        "body": "Can you share your browser version?",
        "createdAt": "2026-03-27T10:00:00Z"
      },
      {
        "author": "WebNaresh",
        "body": "It's Chrome 120 on Windows\n\n---\n> Commented by: **Vivek** (vivek@example.com)",
        "createdAt": "2026-03-27T10:05:00Z"
      }
    ]
  }
}
```

--------------------------------

### Glitchgrab Error Boundary Setup (React)

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/packages/sdk-nextjs/README.md

Wrap your React components with GlitchgrabErrorBoundary to automatically capture and display errors. Provide a fallback UI for when errors occur.

```tsx
import { GlitchgrabErrorBoundary } from "glitchgrab";

<GlitchgrabErrorBoundary fallback={<p>Something went wrong</p>}>
  <MyComponent />
</GlitchgrabErrorBoundary>
```

--------------------------------

### Manage Issues (Approve, Reject, Close) using React Hook

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/packages/sdk-nextjs/README.md

Example of using the `useGlitchgrabActions` hook to approve, reject, or close reports directly within a React component.

```APIDOC
## Manage Issues with React Hook

### Description
Utilize the `useGlitchgrabActions` hook to perform actions like approving, rejecting, or closing reports. This hook provides convenient functions and manages the pending and error states.

### Usage
```tsx
import { useGlitchgrabActions } from "glitchgrab";

function ReportActions({ reportId }: { reportId: string }) {
  const { approve, reject, close, isPending, error } = useGlitchgrabActions({
    token: process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!,
    onSuccess: () => refetch(),        // refresh your reports list
    onError: (err) => alert(err.message),
  });

  return (
    <div>
      <button onClick={() => approve(reportId)} disabled={isPending}>Approve</button>
      <button onClick={() => reject(reportId)} disabled={isPending}>Reject</button>
      <button onClick={() => close(reportId)} disabled={isPending}>Close</button>
      {error && <p>{error}</p>}
    </div>
  );
}
```

### Parameters for `useGlitchgrabActions`
- **token** (string) - Required - Your GlitchGrab API token.
- **onSuccess** (function) - Optional - Callback function executed upon successful action.
- **onError** (function) - Optional - Callback function executed if an error occurs during the action.

### Methods
- **approve(reportId: string)**: Approves a report.
- **reject(reportId: string)**: Rejects a report.
- **close(reportId: string)**: Closes a report.
- **isPending** (boolean): Indicates if an action is currently in progress.
- **error** (Error | null): Contains error information if an action failed.
```

--------------------------------

### Manage Issues using GlitchGrab REST API

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/packages/sdk-nextjs/README.md

Examples of using cURL to perform actions like approving, rejecting, closing, reopening, and labeling issues via the REST API.

```APIDOC
## Manage Issues using REST API

### Description
Perform actions on reports directly through the GlitchGrab REST API. This includes approving, rejecting, closing, reopening, and applying custom labels to issues.

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

### Authentication
Requires a `Bearer gg_` token or dashboard session.

### Actions

#### Approve a report
```bash
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "label", "label": "approved"}' \
  https://www.glitchgrab.dev/api/v1/reports/REPORT_ID/actions
```

#### Reject a report
```bash
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "label", "label": "rejected"}' \
  https://www.glitchgrab.dev/api/v1/reports/REPORT_ID/actions
```

#### Close an issue
```bash
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "close"}' \
  https://www.glitchgrab.dev/api/v1/reports/REPORT_ID/actions
```

#### Reopen an issue
```bash
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "reopen"}' \
  https://www.glitchgrab.dev/api/v1/reports/REPORT_ID/actions
```

#### Remove a label
```bash
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "unlabel", "label": "rejected"}' \
  https://www.glitchgrab.dev/api/v1/reports/REPORT_ID/actions
```

#### Add any custom label
```bash
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "label", "label": "high-priority"}' \
  https://www.glitchgrab.dev/api/v1/reports/REPORT_ID/actions
```

### Request Body Parameters
- **action** (string) - Required - The action to perform (e.g., `label`, `close`, `reopen`, `unlabel`).
- **label** (string) - Required if `action` is `label` or `unlabel` - The label to apply or remove.
```

--------------------------------

### REST API - Get Single Report by ID

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Fetches a single report by its ID, including the full GitHub issue body and all comments.

```APIDOC
## GET /api/v1/sdk/reports/[id]

### Description
Fetch a single report by its ID. This endpoint retrieves the full GitHub issue body and all associated comments, proxying the GitHub API for comment data.

### Method
GET

### Endpoint
https://www.glitchgrab.dev/api/v1/sdk/reports/[id]

### Path Parameters
- **id** (string) - Required - The unique identifier of the report to retrieve.

### Request Example
```bash
curl -H "Authorization: Bearer gg_your_token" \
  "https://www.glitchgrab.dev/api/v1/sdk/reports/cmn7abc123"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the full details of the report.
  - **id** (string) - Unique ID of the report.
  - **source** (string) - Source of the report (e.g., "SDK_USER_REPORT").
  - **status** (string) - Current status of the report.
  - **rawInput** (string) - The raw input provided for the report.
  - **reporterPrimaryKey** (string) - Primary key of the reporter.
  - **reporterName** (string) - Name of the reporter.
  - **reporterEmail** (string) - Email of the reporter.
  - **createdAt** (string) - ISO 8601 timestamp of when the report was created.
  - **issue** (object) - Information about the associated GitHub issue.
    - **githubNumber** (integer) - GitHub issue number.
    - **githubUrl** (string) - URL of the GitHub issue.
    - **title** (string) - Title of the GitHub issue.
    - **body** (string) - The full body content of the GitHub issue.
    - **labels** (array) - Labels applied to the GitHub issue.
    - **severity** (string) - Severity level of the issue.
    - **githubState** (string) - State of the GitHub issue (e.g., "open").
  - **comments** (array) - A list of comments on the GitHub issue (structure not fully detailed in source).

#### Response Example
```json
{
  "success": true,
  "data": {
    "id": "cmn7abc123",
    "source": "SDK_USER_REPORT",
    "status": "CREATED",
    "rawInput": "Payment button unresponsive",
    "reporterPrimaryKey": "user_123",
    "reporterName": "Alice Smith",
    "reporterEmail": "alice@example.com",
    "createdAt": "2026-04-30T10:00:00.000Z",
    "issue": {
      "githubNumber": 99,
      "githubUrl": "https://github.com/your/repo/issues/99",
      "title": "Payment button unresponsive on Safari iOS 17",
      "body": "## Description\n\nThe payment button does nothing...\n\n## Environment\n\n**Page:** /checkout\n**Platform:** iPhone",
      "labels": ["bug", "severity:high"],
      "severity": "high",
      "githubState": "open"
    },
    "comments": [
      // Comment objects would be listed here
    ]
  }
}
```
```

--------------------------------

### Build Project with Bun

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/CLAUDE.md

Builds all project components using Bun.

```bash
bun run build
```

--------------------------------

### Generate Prisma Client with Bun

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/CLAUDE.md

Generates the Prisma client for database interactions using Bun.

```bash
bun run db:generate
```

--------------------------------

### Run Tests with Bun

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/CLAUDE.md

Executes all project tests using Bun.

```bash
bun run test
```

--------------------------------

### Push Schema to Database with Bun

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/CLAUDE.md

Applies the database schema to the connected database using Bun.

```bash
bun run db:push
```

--------------------------------

### Build Production Android APK with Bun

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/CLAUDE.md

Builds a production-ready Android APK from the mobile app directory using Bun.

```bash
bun run build:android:prod
```

--------------------------------

### Build Development Android APK with Bun

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/CLAUDE.md

Builds a development Android APK from the mobile app directory using Bun.

```bash
bun run build:android:dev
```

--------------------------------

### Create GitHub Issue Directly with SDK_USER_REPORT

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Use this method to create a GitHub issue directly from the SDK. It requires detailed information about the bug, including breadcrumbs and device info. Ensure your 'Authorization' header contains your GlitchGrab token.

```bash
curl -X POST https://www.glitchgrab.dev/api/v1/sdk/report \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "SDK_USER_REPORT",
    "type": "BUG",
    "description": "Payment button unresponsive on Safari iOS 17",
    "pageUrl": "https://myapp.com/checkout",
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
    "breadcrumbs": [
      { "type": "navigation", "message": "Navigate to /checkout", "timestamp": "2026-04-30T10:00:00Z" },
      { "type": "click", "message": "Click button#pay-now \"Pay Now\"", "timestamp": "2026-04-30T10:00:05Z" }
    ],
    "deviceInfo": { "screenWidth": 390, "screenHeight": 844, "platform": "iPhone", "colorScheme": "dark" },
    "metadata": { "sessionUserId": "user_789", "sessionUserName": "Alice", "sessionUserEmail": "alice@example.com" }
  }'
```

--------------------------------

### Get reports analytics

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Retrieves analytics data for reports, including a 365-day heatmap, total counts, average reports per day, and counts for today and failed/undismissed reports.

```APIDOC
## GET /api/v1/reports/analytics

### Description
Returns a 365-day daily report heatmap, total count, average per day, today's count, and failed/undismissed report count. Requires session authentication (dashboard use; not for SDK tokens).

### Method
GET

### Endpoint
/api/v1/reports/analytics

### Parameters
#### Query Parameters
This endpoint does not accept query parameters.

### Request Example
```bash
# Dashboard session cookie required
curl -H "Cookie: next-auth.session-token=..."
  "https://www.glitchgrab.dev/api/v1/reports/analytics"
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains the analytics data.
  - **daily** (array) - An array of objects, each representing a day's report count.
    - **date** (string) - The date in YYYY-MM-DD format.
    - **count** (integer) - The number of reports for that day.
  - **total** (integer) - The total number of reports.
  - **avgPerDay** (number) - The average number of reports per day.
  - **today** (integer) - The number of reports for the current day.
  - **failed** (integer) - The number of failed reports.
```

--------------------------------

### Queue Report for AI Pipeline Processing with SDK_AUTO

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

This method queues a report for AI processing. It's suitable for automated error reporting where detailed user interaction data might not be available. Include 'errorMessage' and 'errorStack' for effective analysis.

```bash
curl -X POST https://www.glitchgrab.dev/api/v1/sdk/report \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "SDK_AUTO",
    "type": "BUG",
    "errorMessage": "Cannot read properties of null (reading '\'user\'')",
    "errorStack": "TypeError: Cannot read properties of null\n  at ProfilePage (/app/profile/page.tsx:15:22)",
    "pageUrl": "https://myapp.com/profile",
    "breadcrumbs": []
  }'
```

--------------------------------

### SDK User Report - Create GitHub Issue

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Use the SDK_USER_REPORT source to create a GitHub issue directly from user-submitted information. This bypasses AI processing.

```APIDOC
## POST /api/v1/sdk/report (SDK_USER_REPORT)

### Description
Creates a GitHub issue directly from user-provided report details. This method is intended for direct user feedback and does not involve AI processing.

### Method
POST

### Endpoint
https://www.glitchgrab.dev/api/v1/sdk/report

### Headers
- Authorization: Bearer gg_your_token
- Content-Type: application/json

### Request Body
- **source** (string) - Required - Must be "SDK_USER_REPORT".
- **type** (string) - Required - Type of report (e.g., "BUG").
- **description** (string) - Required - Detailed description of the issue.
- **pageUrl** (string) - Required - The URL where the issue occurred.
- **userAgent** (string) - Required - The user's User-Agent string.
- **breadcrumbs** (array) - Optional - A list of user actions leading to the issue.
  - **type** (string) - Type of breadcrumb (e.g., "navigation", "click").
  - **message** (string) - Description of the action.
  - **timestamp** (string) - ISO 8601 timestamp of the action.
- **deviceInfo** (object) - Optional - Information about the user's device.
  - **screenWidth** (integer) - Screen width.
  - **screenHeight** (integer) - Screen height.
  - **platform** (string) - Device platform (e.g., "iPhone").
  - **colorScheme** (string) - Color scheme of the device (e.g., "dark").
- **metadata** (object) - Optional - Additional metadata about the session.
  - **sessionUserId** (string) - User ID for the session.
  - **sessionUserName** (string) - User name for the session.
  - **sessionUserEmail** (string) - User email for the session.

### Request Example
```json
{
  "source": "SDK_USER_REPORT",
  "type": "BUG",
  "description": "Payment button unresponsive on Safari iOS 17",
  "pageUrl": "https://myapp.com/checkout",
  "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
  "breadcrumbs": [
    { "type": "navigation", "message": "Navigate to /checkout", "timestamp": "2026-04-30T10:00:00Z" },
    { "type": "click", "message": "Click button#pay-now \"Pay Now\"", "timestamp": "2026-04-30T10:00:05Z" }
  ],
  "deviceInfo": { "screenWidth": 390, "screenHeight": 844, "platform": "iPhone", "colorScheme": "dark" },
  "metadata": { "sessionUserId": "user_789", "sessionUserName": "Alice", "sessionUserEmail": "alice@example.com" }
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains details about the created report.
  - **reportId** (string) - The unique ID of the report.
  - **intent** (string) - The action taken (e.g., "create").
  - **issueUrl** (string) - URL of the created GitHub issue.
  - **issueNumber** (integer) - The number of the GitHub issue.
  - **title** (string) - The title of the GitHub issue.

#### Response Example
```json
{
  "success": true,
  "data": {
    "reportId": "cmn7xyz456",
    "intent": "create",
    "issueUrl": "https://github.com/your/repo/issues/99",
    "issueNumber": 99,
    "title": "Payment button unresponsive on Safari iOS 17"
  }
}
```

#### Error Response (429)
- **success** (boolean) - Indicates failure.
- **error** (string) - Error message (e.g., "Rate limit exceeded").
- **retryAfter** (integer) - Seconds to wait before retrying.
```

--------------------------------

### useGlitchgrabReports Hook

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

A React hook to fetch reports for a specific user by polling the GET /api/v1/sdk/reports endpoint. It provides live GitHub issue state and supports custom polling limits.

```APIDOC
## useGlitchgrabReports Hook

React hook to fetch reports for a specific user, identified by their `userId` (the `reporterPrimaryKey` stored when the session was passed to the provider). Polls the `GET /api/v1/sdk/reports` endpoint and returns live GitHub issue state.

### Parameters
- **token** (string) - Required - Glitchgrab API token.
- **userId** (string) - Required - The primary key of the user in your database.
- **limit** (number) - Optional - The maximum number of reports to fetch. Defaults to 100, max 100.

### Returns
- **reports** (Array<GlitchgrabReport>) - An array of report objects.
- **isLoading** (boolean) - True if the initial data is loading.
- **isFetching** (boolean) - True if data is being fetched in the background.
- **error** (string | null) - An error message if fetching fails, otherwise null.
- **refetch** (function) - A function to manually refetch the reports.

### GlitchgrabReport Shape
```
{
  id: string,
  source: string,
  status: string,
  rawInput: string,
  reporterPrimaryKey: string,
  reporterName: string,
  reporterEmail: string,
  reporterPhone: string,
  pageUrl: string,
  createdAt: string,
  commentCount: number,
  issue: {
    githubNumber: number,
    githubUrl: string,
    title: string,
    labels: string[],
    severity: string,
    githubState: string
  } | null
}
```
```

--------------------------------

### Project Structure Overview

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/README.md

Illustrates the directory layout of the Glitchgrab monorepo, detailing the organization of applications, packages, and configuration files.

```tree
glitchgrab/
├── apps/
│   ├── web/                    # Next.js dashboard + API
│   └── mobile/                 # React Native (Expo) mobile app
├── packages/
│   ├── sdk-nextjs/             # glitchgrab npm package
│   ├── mcp-server/             # MCP server for Claude
│   └── shared/                 # Shared types
├── CLAUDE.md                   # Instructions for Claude Code
├── README.md
├── package.json
└── turbo.json
```

--------------------------------

### Initialize Glitchgrab SDK in Next.js Layout

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/README.md

Wrap your application with GlitchgrabProvider to enable automatic error capturing and add an end-user error reporting button. Ensure you replace 'gg_your_token' with your actual Glitchgrab token.

```tsx
import { GlitchgrabProvider } from "glitchgrab";

export default function RootLayout({ children }) {
  return (
    <GlitchgrabProvider token="gg_your_token">{children}</GlitchgrabProvider>
  );
}
```

--------------------------------

### Get Report Analytics via REST API

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Retrieve analytics data including a 365-day heatmap, total counts, and daily averages. This endpoint requires dashboard session authentication, not SDK tokens.

```bash
# Dashboard session cookie required
curl -H "Cookie: next-auth.session-token=..." \
  "https://www.glitchgrab.dev/api/v1/reports/analytics"
```

--------------------------------

### List GitHub Repositories

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/CLAUDE.md

Retrieves a list of the authenticated user's GitHub repositories, intended for use in a connect dialog.

```APIDOC
## GET /api/v1/repos/github

### Description
Lists the user's GitHub repositories. This endpoint is typically used to populate a selection list when connecting a GitHub account.

### Method
GET

### Endpoint
/api/v1/repos/github

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (array) - An array of GitHub repository objects if successful.
- **error** (string) - Error message if the operation failed.
```

--------------------------------

### Fetch Single Report by ID using REST API

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Retrieve a specific report using its ID with the GET /api/v1/sdk/reports/[id] endpoint. This endpoint proxies the GitHub API to provide the full issue body and comments.

```bash
curl -H "Authorization: Bearer gg_your_token" \
  "https://www.glitchgrab.dev/api/v1/sdk/reports/cmn7abc123"
```

--------------------------------

### Standalone Fetcher for Glitchgrab Reports

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Use `fetchGlitchgrabReports` for direct data fetching, compatible with libraries like TanStack Query or SWR. It throws an error on failure. Ensure your token is correctly configured.

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

// With TanStack Query
export function ReportsWithQuery({ userId }: { userId: string }) {
  const { data: reports = [], isLoading } = useQuery({
    queryKey: ["glitchgrab-reports", userId],
    queryFn: () =>
      fetchGlitchgrabReports({
        token: process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!,
        userId,
        limit: 50,
      }),
    refetchInterval: 30_000, // poll every 30s
  });

  return <div>{reports.length} reports found</div>;
}

// Standalone async fetch (server-side or in useEffect)
const reports = await fetchGlitchgrabReports({
  token: "gg_your_token",
  userId: "user_123",
  limit: 10,
});
// Returns GlitchgrabReport[]
// Throws: Error("Failed to fetch reports") on API error
```

--------------------------------

### SDK Auto Report - Queued for AI Processing

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Use the SDK_AUTO source to queue reports for AI pipeline processing. This is suitable for automated error reporting.

```APIDOC
## POST /api/v1/sdk/report (SDK_AUTO)

### Description
Queues a report for AI pipeline processing. This method is suitable for automated error reporting where AI analysis is desired.

### Method
POST

### Endpoint
https://www.glitchgrab.dev/api/v1/sdk/report

### Headers
- Authorization: Bearer gg_your_token
- Content-Type: application/json

### Request Body
- **source** (string) - Required - Must be "SDK_AUTO".
- **type** (string) - Required - Type of report (e.g., "BUG").
- **errorMessage** (string) - Required - The error message encountered.
- **errorStack** (string) - Optional - The stack trace of the error.
- **pageUrl** (string) - Optional - The URL where the error occurred.
- **breadcrumbs** (array) - Optional - A list of user actions leading to the error.

### Request Example
```json
{
  "source": "SDK_AUTO",
  "type": "BUG",
  "errorMessage": "Cannot read properties of null (reading '\'user\'')",
  "errorStack": "TypeError: Cannot read properties of null\n  at ProfilePage (/app/profile/page.tsx:15:22)",
  "pageUrl": "https://myapp.com/profile",
  "breadcrumbs": []
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **data** (object) - Contains details about the queued report.
  - **reportId** (string) - The unique ID of the report.
  - **status** (string) - The current status of the report (e.g., "PROCESSING").

#### Response Example (Queued)
```json
{
  "success": true,
  "data": {
    "reportId": "cmn7abc111",
    "status": "PROCESSING"
  }
}
```

#### Response Example (Duplicate Detected)
```json
{
  "success": true,
  "data": {
    "reportId": "cmn7old999",
    "status": "DUPLICATE",
    "issueUrl": "https://github.com/your/repo/issues/42",
    "message": "Duplicate of recent report — skipped"
  }
}
```

#### Error Response (429)
- **success** (boolean) - Indicates failure.
- **error** (string) - Error message (e.g., "Rate limit exceeded").
- **retryAfter** (integer) - Seconds to wait before retrying.
```

--------------------------------

### fetchGlitchgrabReports (Standalone Fetcher)

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

A promise-based fetcher function that can be used with data-fetching libraries like TanStack Query or SWR, or as a standalone async function. It throws an error if the API request fails.

```APIDOC
## fetchGlitchgrabReports (Standalone Fetcher)

Promise-based fetcher compatible with TanStack Query, SWR, or any data-fetching library. Throws on error.

### Parameters
- **token** (string) - Required - Glitchgrab API token.
- **userId** (string) - Required - The primary key of the user in your database.
- **limit** (number) - Optional - The maximum number of reports to fetch. Defaults to 100, max 100.

### Returns
- **Promise<Array<GlitchgrabReport>>** - A promise that resolves to an array of report objects.

### Throws
- **Error** - If the API request fails.
```

--------------------------------

### Keyboard Shortcuts

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/packages/sdk-nextjs/README.md

Glitchgrab provides global keyboard shortcuts for opening the report dialog, pasting screenshots, and closing the dialog, active as long as the `GlitchgrabProvider` is mounted.

```APIDOC
## Keyboard Shortcuts

Once `GlitchgrabProvider` is mounted, these shortcuts work globally:

| Shortcut | Action |
|----------|--------|
| `Cmd+Shift+G` / `Ctrl+Shift+G` | Open the report dialog |
| `Cmd+V` / `Ctrl+V` (dialog open) | Paste a screenshot from clipboard |
| `Escape` | Close the dialog |

No configuration needed — shortcuts are active as long as the provider is in the tree.
```

--------------------------------

### Configure GlitchgrabProvider in Next.js Layout

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Wrap your application's root layout with GlitchgrabProvider to auto-capture errors, track navigation, and enable user reporting. Ensure your session data is mapped correctly to GlitchgrabSession. The provider is a no-op if the token is empty.

```tsx
// app/layout.tsx
import { GlitchgrabProvider, type GlitchgrabSession } from "glitchgrab";
import { auth } from "@/lib/auth"; // your auth library

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

  // Map your session to GlitchgrabSession — userId is the DB primary key
  const session: GlitchgrabSession | null = authSession?.user
    ? {
        userId: authSession.user.id,       // required
        name: authSession.user.name ?? "", // required
        email: authSession.user.email,     // optional — attached to every report
        phone: null,                       // optional
      }
    : null;

  return (
    <html lang="en">
      <body>
        <GlitchgrabProvider
          token={process.env.NEXT_PUBLIC_GLITCHGRAB_TOKEN!}
          session={session}
          breadcrumbs={true}        // default: true — intercepts console/fetch/click/nav
          maxBreadcrumbs={50}       // default: 50
          onReportSent={(result) => {
            // result: { success, reportId, issueUrl, issueNumber, title, intent }
            console.log("Issue created:", result.issueUrl);
          }}
          onError={(error) => {
            // also called for auto-captured errors — add your own logging here
            console.error("Glitchgrab caught:", error);
          }}
          fallback={<div>Something went wrong. Our team has been notified.</div>}
        >
          {children}
        </GlitchgrabProvider>
      </body>
    </html>
  );
}
```

--------------------------------

### Open Report Dialog on Bad Feedback

Source: https://github.com/navibyte-innovations-pvt-ltd/glitchgrab/blob/main/packages/sdk-nextjs/README.md

Use `openReportDialog` from `useGlitchgrab` to trigger the bug reporting modal when specific conditions are met, such as negative user feedback. Requires a `ReportButton` to be mounted.

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

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

--------------------------------

### Initialize and Manage Breadcrumbs

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Use these functions to manually control breadcrumbs. `initBreadcrumbs` sets the maximum number of breadcrumbs. `addBreadcrumb` adds custom events, and `getBreadcrumbs` retrieves all stored crumbs. `clearBreadcrumbs` removes them.

```typescript
import {
  initBreadcrumbs,
  addBreadcrumb,
  getBreadcrumbs,
  clearBreadcrumbs,
} from "glitchgrab";

// Initialize with custom max (normally handled by GlitchgrabProvider)
initBreadcrumbs(100);

// Add a custom breadcrumb from any module (not just React components)
addBreadcrumb("user:checkout_started", { cartTotal: "99.00", itemCount: "3" });
addBreadcrumb("api:payment_initiated", { provider: "stripe", currency: "USD" });

// Read all stored breadcrumbs (useful for custom error handlers)
const crumbs = getBreadcrumbs();
// Returns: Breadcrumb[]
// Each: { type: "console"|"navigation"|"api"|"click"|"error"|"custom", message, timestamp, data? }
console.log(crumbs);
// [
//   { type: "custom", message: "user:checkout_started", timestamp: "2026-04-30T10:00:00.000Z", data: { cartTotal: "99.00" } },
//   { type: "api", message: "POST /api/checkout → 200", timestamp: "...", data: { method: "POST", status: "200", duration: "123ms" } }
// ]

// Clear stored breadcrumbs (e.g., on user logout)
clearBreadcrumbs();
```

--------------------------------

### Trigger Report Dialog Programmatically with SDK

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

Use the `useGlitchgrab` hook to programmatically open the report dialog. You can open a blank dialog or pre-fill it with specific content and report types.

```tsx
// Active automatically once GlitchgrabProvider is mounted:
// Cmd+Shift+G  (macOS) / Ctrl+Shift+G  (Windows/Linux) → opens report dialog
// Cmd+V        (macOS) / Ctrl+V        (Windows/Linux) → paste screenshot from clipboard (dialog must be open)
// Escape → close the dialog

// Trigger programmatically (same effect as keyboard shortcut):
const { openReportDialog } = useGlitchgrab();

// Open blank dialog
openReportDialog();

// Open with pre-filled content
openReportDialog({
  description: "Error on /settings page: unexpected token in JSON",
  type: "BUG", // "BUG" | "FEATURE_REQUEST" | "QUESTION" | "OTHER"
});
```

--------------------------------

### Perform Actions on Report via REST API

Source: https://context7.com/navibyte-innovations-pvt-ltd/glitchgrab/llms.txt

This endpoint allows performing actions such as labeling, closing, reopening, or dismissing a report's linked GitHub issue. It accepts API tokens or session cookies. Use specific JSON payloads for each action.

```bash
# Approve — adds "approved" label to the GitHub issue
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "label", "label": "approved"}' \
  "https://www.glitchgrab.dev/api/v1/reports/cmn7abc123/actions"
```

```bash
# Reject — adds "rejected" label
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "label", "label": "rejected"}' \
  "https://www.glitchgrab.dev/api/v1/reports/cmn7abc123/actions"
```

```bash
# Close GitHub issue
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "close"}' \
  "https://www.glitchgrab.dev/api/v1/reports/cmn7abc123/actions"
```

```bash
# Reopen GitHub issue
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "reopen"}' \
  "https://www.glitchgrab.dev/api/v1/reports/cmn7abc123/actions"
```

```bash
# Custom label
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "label", "label": "high-priority"}' \
  "https://www.glitchgrab.dev/api/v1/reports/cmn7abc123/actions"
```

```bash
# Unlabel
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "unlabel", "label": "rejected"}' \
  "https://www.glitchgrab.dev/api/v1/reports/cmn7abc123/actions"
```

```bash
# Dismiss (marks report as dismissed in DB — hides from failed count)
curl -X POST \
  -H "Authorization: Bearer gg_your_token" \
  -H "Content-Type: application/json" \
  -d '{"action": "dismiss"}' \
  "https://www.glitchgrab.dev/api/v1/reports/cmn7abc123/actions"
```