glitchgrab 1.47.0 → 1.48.1

package/README.md

@@ -1,6 +1,8 @@
 # glitchgrab
 
-Turn messy bugs into structured GitHub issues with AI. Drop-in SDK for Next.js apps.
+Turn production errors and your users' bug reports into structured GitHub issues. Drop-in SDK for Next.js apps.
+
+This page covers the SDK. Step-by-step guides for everything else — the Chrome extension, QA testers, call recording, the AI report assistant, MCP for Claude — are at **[glitchgrab.dev/guides](https://glitchgrab.dev/guides)**.
 
 ## How do I install Glitchgrab?
 
@@ -10,6 +12,15 @@ npm install glitchgrab
 bun add glitchgrab
 ```
 
+## How do I get a token?
+
+1. Sign in at [glitchgrab.dev/login](https://glitchgrab.dev/login) with GitHub.
+2. Connect your GitHub org and install the Glitchgrab GitHub App on the repo that should receive issues.
+3. Open **API Tokens**, pick the repo and create a token. It starts with `gg_`.
+4. Put it in your environment as `NEXT_PUBLIC_GLITCHGRAB_TOKEN`.
+
+With screenshots: [Connect your GitHub org](https://glitchgrab.dev/guides/connect-your-github-org) and [Create an API token](https://glitchgrab.dev/guides/create-an-api-token).
+
 ## How do I get started?
 
 Wrap your app with `GlitchgrabProvider`:
@@ -354,15 +365,15 @@ Use the REST API directly to fetch reports:
 ```bash
 # Fetch all reports
 curl -H "Authorization: Bearer gg_your_token" \
-  https://www.glitchgrab.dev/api/v1/sdk/reports
+  https://glitchgrab.dev/api/v1/sdk/reports
 
 # Fetch reports by a specific user
 curl -H "Authorization: Bearer gg_your_token" \
-  "https://www.glitchgrab.dev/api/v1/sdk/reports?reporterPrimaryKey=user_123"
+  "https://glitchgrab.dev/api/v1/sdk/reports?reporterPrimaryKey=user_123"
 
 # Filter by status
 curl -H "Authorization: Bearer gg_your_token" \
-  "https://www.glitchgrab.dev/api/v1/sdk/reports?status=CREATED&limit=20"
+  "https://glitchgrab.dev/api/v1/sdk/reports?status=CREATED&limit=20"
 ```
 
 ### Response
@@ -454,7 +465,7 @@ 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
+  https://glitchgrab.dev/api/v1/reports/REPORT_ID/actions
 ```
 
 #### Reject a report
@@ -464,7 +475,7 @@ 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
+  https://glitchgrab.dev/api/v1/reports/REPORT_ID/actions
 ```
 
 #### Close an issue
@@ -474,7 +485,7 @@ 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
+  https://glitchgrab.dev/api/v1/reports/REPORT_ID/actions
 ```
 
 #### Reopen an issue
@@ -484,7 +495,7 @@ 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
+  https://glitchgrab.dev/api/v1/reports/REPORT_ID/actions
 ```
 
 #### Remove a label
@@ -494,7 +505,7 @@ 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
+  https://glitchgrab.dev/api/v1/reports/REPORT_ID/actions
 ```
 
 #### Add any custom label
@@ -504,7 +515,7 @@ 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
+  https://glitchgrab.dev/api/v1/reports/REPORT_ID/actions
 ```
 
 ### How to get the report ID
@@ -526,7 +537,7 @@ Each report has a conversation thread powered by GitHub issue comments. No extra
 
 ```bash
 curl -H "Authorization: Bearer gg_your_token" \
-  https://www.glitchgrab.dev/api/v1/sdk/reports/REPORT_ID
+  https://glitchgrab.dev/api/v1/sdk/reports/REPORT_ID
 ```
 
 Returns the full issue body + all comments:
@@ -565,7 +576,7 @@ curl -X POST \
   -H "Authorization: Bearer gg_your_token" \
   -H "Content-Type: application/json" \
   -d '{"message": "I can reproduce this, fixing now", "reporterName": "Vivek", "reporterEmail": "vivek@example.com"}' \
-  https://www.glitchgrab.dev/api/v1/sdk/reports/REPORT_ID/comments
+  https://glitchgrab.dev/api/v1/sdk/reports/REPORT_ID/comments
 ```
 
 The comment is posted to the GitHub issue with attribution: "Commented by: **Vivek** (vivek@example.com)".
@@ -799,13 +810,91 @@ reportServerError(error: unknown, options?: {
   development, or the API refused it.
 - No React, no DOM, no `"use client"`. Safe in any Node runtime.
 
+## How do I show my guides on my own site?
+
+Write guides in Glitchgrab (the Guides page, or an agent with `save_guide`), then
+render them on your site from server components. Uses the same `GLITCHGRAB_TOKEN`
+(or `NEXT_PUBLIC_GLITCHGRAB_TOKEN`) as the rest of the SDK, and reads published
+guides only.
+
+```tsx
+// app/guides/page.tsx
+import { listGuides } from "glitchgrab/server";
+
+export default async function GuidesPage() {
+  const guides = await listGuides();
+  return (
+    <ul>
+      {guides.map((g) => (
+        <li key={g.slug}>
+          <a href={`/guides/${g.slug}`}>{g.title}</a> — {g.summary}
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+```tsx
+// app/guides/[slug]/page.tsx
+import { notFound } from "next/navigation";
+import { escapeJsonForScript, getGuide } from "glitchgrab/server";
+
+export default async function GuidePage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const guide = await getGuide(slug);
+  if (!guide) notFound();
+
+  const jsonLd = { "@context": "https://schema.org", "@type": "HowTo", name: guide.title, description: guide.summary };
+
+  return (
+    <article>
+      <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: escapeJsonForScript(jsonLd) }} />
+      <h1>{guide.title}</h1>
+      <div dangerouslySetInnerHTML={{ __html: guide.html }} />
+    </article>
+  );
+}
+```
+
+- **Never throws.** `listGuides()` returns `[]` and `getGuide()` returns `null` on
+  any failure — no token, Glitchgrab down, a slow response (5s timeout), an
+  unexpected shape. An outage leaves the page empty instead of a 500.
+- **Cached for 5 minutes** by default. The API route is dynamic, so the cache is
+  yours: pass `{ revalidate: 60 }`, or `0` to read fresh every request.
+- **Use `escapeJsonForScript` for JSON-LD.** `JSON.stringify` leaves `</script>`
+  intact, so a guide title containing it would break out of the tag.
+- **`html` is sanitized by Glitchgrab** — raw HTML in the markdown arrives as
+  text, and only http(s), mailto and relative links survive. On a domain that
+  holds your users' sessions, add your own sanitize pass as defence in depth;
+  the SDK ships no sanitizer to stay dependency-free.
+- **Headings have ids** — `<h2 id="guide-before-you-start">` — for a table of
+  contents or a link to one step. The `guide-` prefix is there so a heading can
+  never shadow a `window` global on your page.
+- `link` is where the guide lives on your site (its own link, else your guides
+  base URL + slug), or `null` when neither is set.
+
+```ts
+listGuides(options?: GuideReadOptions): Promise<GuideSummary[]>
+getGuide(slug: string, options?: GuideReadOptions): Promise<Guide | null>
+
+interface GuideReadOptions {
+  token?: string;      // default: GLITCHGRAB_TOKEN, then NEXT_PUBLIC_GLITCHGRAB_TOKEN
+  baseUrl?: string;    // default: GLITCHGRAB_BASE_URL, then https://glitchgrab.dev
+  revalidate?: number; // seconds, default 300
+  timeoutMs?: number;  // default 5000
+}
+```
+
+Never pass the `ggw_` guides write key here for a public page — it reads drafts too.
+
 ## What configuration options are available?
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `token` | `string` | required | Your Glitchgrab API token (`gg_...`) |
 | `session` | `GlitchgrabSession \| null` | `null` | Logged-in user info for report attribution |
-| `baseUrl` | `string` | `https://www.glitchgrab.dev` | API base URL |
+| `baseUrl` | `string` | `https://glitchgrab.dev` | API base URL |
 | `breadcrumbs` | `boolean` | `true` | Enable automatic breadcrumb tracking |
 | `maxBreadcrumbs` | `number` | `50` | Max breadcrumbs to keep |
 | `onError` | `(error: Error) => void` | - | Called on unhandled errors |