heartbeads 0.4.0

package/app/api/docs/page.tsx

@@ -0,0 +1,497 @@
+import { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Heartbeads API Docs",
+  description: "Public REST API documentation for Heartbeads",
+};
+
+export default function ApiDocsPage() {
+  return (
+    <div className="min-h-screen bg-white text-zinc-800 antialiased overflow-y-auto h-screen">
+      <div className="max-w-3xl mx-auto px-6 py-12">
+        {/* Header */}
+        <div className="mb-10">
+          <a
+            href="/"
+            className="text-xs text-zinc-400 hover:text-emerald-500 transition-colors"
+          >
+            &larr; Back to graph
+          </a>
+          <h1 className="text-2xl font-semibold mt-3 text-zinc-900">
+            Heartbeads API
+          </h1>
+          <p className="text-sm text-zinc-500 mt-1.5 leading-relaxed">
+            Read-only REST API for AI agents, CI/CD bots, and integrations.
+            No authentication required. All endpoints return JSON with CORS
+            headers.
+          </p>
+          <div className="flex items-center gap-3 mt-3">
+            <span className="text-[11px] font-mono px-2 py-0.5 rounded-full bg-emerald-50 text-emerald-600 border border-emerald-200">
+              v1
+            </span>
+            <span className="text-[11px] text-zinc-400">
+              Base path: <code className="font-mono">/api/v1</code>
+            </span>
+          </div>
+        </div>
+
+        {/* Table of contents */}
+        <nav className="mb-10 p-4 rounded-xl bg-zinc-50 border border-zinc-100">
+          <h2 className="text-[11px] font-semibold uppercase tracking-widest text-zinc-400 mb-2">
+            Endpoints
+          </h2>
+          <ul className="space-y-1.5 text-sm">
+            <li>
+              <a href="#graph" className="text-teal-600 hover:text-teal-700 underline-offset-2 hover:underline">
+                <code className="font-mono text-xs">GET /api/v1/graph</code>
+                <span className="text-zinc-400 ml-2">&mdash; Full project snapshot</span>
+              </a>
+            </li>
+            <li>
+              <a href="#issues" className="text-teal-600 hover:text-teal-700 underline-offset-2 hover:underline">
+                <code className="font-mono text-xs">GET /api/v1/issues/:id</code>
+                <span className="text-zinc-400 ml-2">&mdash; Single issue detail</span>
+              </a>
+            </li>
+            <li>
+              <a href="#ready" className="text-teal-600 hover:text-teal-700 underline-offset-2 hover:underline">
+                <code className="font-mono text-xs">GET /api/v1/ready</code>
+                <span className="text-zinc-400 ml-2">&mdash; Actionable issues</span>
+              </a>
+            </li>
+          </ul>
+        </nav>
+
+        {/* Common info */}
+        <section className="mb-10">
+          <h2 className="text-lg font-semibold text-zinc-900 mb-3">Common Details</h2>
+          <div className="space-y-3 text-sm text-zinc-600 leading-relaxed">
+            <p>
+              All responses include CORS headers (<code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">Access-Control-Allow-Origin: *</code>) and are cached for 30 seconds.
+            </p>
+            <p>
+              Every response includes a <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">_meta</code> object with <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">generated_at</code> (ISO 8601), <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">api_version</code>, <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">heartbeads_version</code>, and optional <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">warnings</code>.
+            </p>
+            <p>
+              Error responses return <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">{`{ "error": "...", "hint": "..." }`}</code> with appropriate HTTP status codes (404, 500).
+            </p>
+          </div>
+        </section>
+
+        {/* Authentication */}
+        <section className="mb-10">
+          <h2 className="text-lg font-semibold text-zinc-900 mb-3">Authentication</h2>
+          <div className="space-y-3 text-sm text-zinc-600 leading-relaxed">
+            <p>
+              By default, no authentication is required. When heartbeads is started with <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">--password</code>, all API requests must include the password:
+            </p>
+            <div className="space-y-2">
+              <div className="flex items-start gap-2">
+                <span className="shrink-0 text-[11px] font-mono px-1.5 py-0.5 rounded bg-zinc-100 text-zinc-600 mt-0.5">1</span>
+                <div>
+                  <span className="font-medium text-zinc-700">Bearer token</span> (recommended)
+                  <pre className="mt-1 bg-zinc-950 text-zinc-300 rounded-lg p-3 text-xs font-mono overflow-x-auto">
+{`curl -H "Authorization: Bearer <password>" http://localhost:3000/api/v1/graph`}
+                  </pre>
+                </div>
+              </div>
+              <div className="flex items-start gap-2">
+                <span className="shrink-0 text-[11px] font-mono px-1.5 py-0.5 rounded bg-zinc-100 text-zinc-600 mt-0.5">2</span>
+                <div>
+                  <span className="font-medium text-zinc-700">Query parameter</span>
+                  <pre className="mt-1 bg-zinc-950 text-zinc-300 rounded-lg p-3 text-xs font-mono overflow-x-auto">
+{`curl "http://localhost:3000/api/v1/graph?token=<password>"`}
+                  </pre>
+                </div>
+              </div>
+            </div>
+            <p>
+              Unauthenticated API requests return <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">401</code> with a JSON error. Browser requests are redirected to a login page.
+            </p>
+          </div>
+        </section>
+
+        <hr className="border-zinc-100 mb-10" />
+
+        {/* GET /api/v1/graph */}
+        <section id="graph" className="mb-12 scroll-mt-8">
+          <div className="flex items-center gap-2 mb-3">
+            <span className="text-[11px] font-mono font-bold px-2 py-0.5 rounded bg-emerald-50 text-emerald-600 border border-emerald-200">
+              GET
+            </span>
+            <code className="text-sm font-mono font-semibold text-zinc-900">
+              /api/v1/graph
+            </code>
+          </div>
+          <p className="text-sm text-zinc-600 mb-4 leading-relaxed">
+            Returns the entire project state in a single response: all issues with comments and claims,
+            dependency edges, summary statistics, and a recent activity feed. This is the primary endpoint
+            for AI agents that need full project context.
+          </p>
+
+          <h3 className="text-xs font-semibold text-zinc-700 mb-2">Query Parameters</h3>
+          <div className="overflow-x-auto mb-4">
+            <table className="w-full text-sm border-collapse">
+              <thead>
+                <tr className="text-left text-xs text-zinc-500 border-b border-zinc-100">
+                  <th className="py-2 pr-4 font-medium">Param</th>
+                  <th className="py-2 pr-4 font-medium">Type</th>
+                  <th className="py-2 pr-4 font-medium">Default</th>
+                  <th className="py-2 font-medium">Description</th>
+                </tr>
+              </thead>
+              <tbody className="text-zinc-600">
+                <tr className="border-b border-zinc-50">
+                  <td className="py-2 pr-4 font-mono text-xs text-teal-600">status</td>
+                  <td className="py-2 pr-4 text-xs">string</td>
+                  <td className="py-2 pr-4 text-xs text-zinc-400">all</td>
+                  <td className="py-2 text-xs">Comma-separated status filter: <code className="bg-zinc-100 px-1 rounded">open,in_progress,blocked,deferred,closed</code></td>
+                </tr>
+                <tr className="border-b border-zinc-50">
+                  <td className="py-2 pr-4 font-mono text-xs text-teal-600">priority</td>
+                  <td className="py-2 pr-4 text-xs">string</td>
+                  <td className="py-2 pr-4 text-xs text-zinc-400">all</td>
+                  <td className="py-2 text-xs">Comma-separated priority filter: <code className="bg-zinc-100 px-1 rounded">0</code> (critical) to <code className="bg-zinc-100 px-1 rounded">4</code> (backlog)</td>
+                </tr>
+                <tr className="border-b border-zinc-50">
+                  <td className="py-2 pr-4 font-mono text-xs text-teal-600">prefix</td>
+                  <td className="py-2 pr-4 text-xs">string</td>
+                  <td className="py-2 pr-4 text-xs text-zinc-400">all</td>
+                  <td className="py-2 text-xs">Filter by repo prefix (e.g. <code className="bg-zinc-100 px-1 rounded">beads-map</code>)</td>
+                </tr>
+                <tr className="border-b border-zinc-50">
+                  <td className="py-2 pr-4 font-mono text-xs text-teal-600">include</td>
+                  <td className="py-2 pr-4 text-xs">string</td>
+                  <td className="py-2 pr-4 text-xs text-zinc-400">comments,activity</td>
+                  <td className="py-2 text-xs">Opt-in to expensive fields. Empty string skips both. Omitting returns all.</td>
+                </tr>
+                <tr>
+                  <td className="py-2 pr-4 font-mono text-xs text-teal-600">limit</td>
+                  <td className="py-2 pr-4 text-xs">number</td>
+                  <td className="py-2 pr-4 text-xs text-zinc-400">50</td>
+                  <td className="py-2 text-xs">Activity feed cap (max 200)</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+
+          <h3 className="text-xs font-semibold text-zinc-700 mb-2">Example Request</h3>
+          <pre className="bg-zinc-950 text-zinc-300 rounded-lg p-4 text-xs font-mono overflow-x-auto mb-4">
+{`curl http://localhost:3000/api/v1/graph?status=open,in_progress&limit=10`}
+          </pre>
+
+          <h3 className="text-xs font-semibold text-zinc-700 mb-2">Response Shape</h3>
+          <pre className="bg-zinc-950 text-zinc-300 rounded-lg p-4 text-xs font-mono overflow-x-auto">
+{`{
+  "project": {
+    "name": "my-project",
+    "prefix": "my-proj",
+    "repos": [".", "../backend"],
+    "repoUrls": { "my-proj": "https://github.com/org/my-project" }
+  },
+  "issues": [
+    {
+      "id": "my-proj-abc",
+      "title": "Fix login redirect",
+      "description": "Full markdown description...",
+      "status": "open",
+      "priority": 1,
+      "issue_type": "bug",
+      "owner": "alice",
+      "assignee": "bob",
+      "labels": [],
+      "created_at": "2025-01-15T10:00:00Z",
+      "updated_at": "2025-01-16T14:30:00Z",
+      "closed_at": null,
+      "close_reason": null,
+      "prefix": "my-proj",
+      "blockers": ["my-proj-xyz"],
+      "dependents": ["my-proj-def"],
+      "comments": [
+        {
+          "author": { "handle": "alice.bsky.social", "did": "did:plc:..." },
+          "text": "This needs to be fixed before release",
+          "createdAt": "2025-01-16T14:30:00Z",
+          "likes": 2,
+          "replies": []
+        }
+      ],
+      "claimed_by": {
+        "handle": "bob.bsky.social",
+        "did": "did:plc:...",
+        "claimed_at": "2025-01-16T15:00:00Z"
+      }
+    }
+  ],
+  "dependencies": [
+    { "from": "my-proj-xyz", "to": "my-proj-abc", "type": "blocks" }
+  ],
+  "stats": {
+    "total": 42, "open": 15, "in_progress": 8,
+    "blocked": 3, "closed": 16, "actionable": 12
+  },
+  "activity": [
+    {
+      "type": "comment-added",
+      "time": "2025-01-16T14:30:00Z",
+      "issue_id": "my-proj-abc",
+      "issue_title": "Fix login redirect",
+      "actor": { "handle": "alice.bsky.social" },
+      "detail": "This needs to be fixed..."
+    }
+  ],
+  "_meta": {
+    "generated_at": "2025-01-17T09:00:00Z",
+    "api_version": "v1",
+    "heartbeads_version": "0.3.7"
+  }
+}`}
+          </pre>
+        </section>
+
+        <hr className="border-zinc-100 mb-10" />
+
+        {/* GET /api/v1/issues/:id */}
+        <section id="issues" className="mb-12 scroll-mt-8">
+          <div className="flex items-center gap-2 mb-3">
+            <span className="text-[11px] font-mono font-bold px-2 py-0.5 rounded bg-emerald-50 text-emerald-600 border border-emerald-200">
+              GET
+            </span>
+            <code className="text-sm font-mono font-semibold text-zinc-900">
+              /api/v1/issues/:id
+            </code>
+          </div>
+          <p className="text-sm text-zinc-600 mb-4 leading-relaxed">
+            Returns a single issue with its full description, threaded comments, claim info, and
+            enriched blockers/dependents (each includes <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">title</code> and <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">status</code> so
+            you can understand the blocking context without extra requests).
+          </p>
+
+          <h3 className="text-xs font-semibold text-zinc-700 mb-2">Path Parameters</h3>
+          <div className="overflow-x-auto mb-4">
+            <table className="w-full text-sm border-collapse">
+              <thead>
+                <tr className="text-left text-xs text-zinc-500 border-b border-zinc-100">
+                  <th className="py-2 pr-4 font-medium">Param</th>
+                  <th className="py-2 font-medium">Description</th>
+                </tr>
+              </thead>
+              <tbody className="text-zinc-600">
+                <tr>
+                  <td className="py-2 pr-4 font-mono text-xs text-teal-600">id</td>
+                  <td className="py-2 text-xs">The issue ID (e.g. <code className="bg-zinc-100 px-1 rounded">beads-map-abc</code>)</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+
+          <h3 className="text-xs font-semibold text-zinc-700 mb-2">Example Request</h3>
+          <pre className="bg-zinc-950 text-zinc-300 rounded-lg p-4 text-xs font-mono overflow-x-auto mb-4">
+{`curl http://localhost:3000/api/v1/issues/beads-map-abc`}
+          </pre>
+
+          <h3 className="text-xs font-semibold text-zinc-700 mb-2">Response Shape</h3>
+          <pre className="bg-zinc-950 text-zinc-300 rounded-lg p-4 text-xs font-mono overflow-x-auto mb-4">
+{`{
+  "issue": {
+    "id": "beads-map-abc",
+    "title": "Fix login redirect",
+    "description": "Full markdown description...",
+    "status": "open",
+    "priority": 1,
+    "issue_type": "bug",
+    "owner": "alice",
+    "assignee": null,
+    "labels": [],
+    "created_at": "2025-01-15T10:00:00Z",
+    "updated_at": "2025-01-16T14:30:00Z",
+    "closed_at": null,
+    "close_reason": null,
+    "prefix": "beads-map",
+    "blockers": [
+      { "id": "beads-map-xyz", "title": "Deploy auth service", "status": "in_progress" }
+    ],
+    "dependents": [
+      { "id": "beads-map-def", "title": "Add SSO support", "status": "open" }
+    ],
+    "comments": [...],
+    "claimed_by": null
+  },
+  "_meta": { ... }
+}`}
+          </pre>
+
+          <h3 className="text-xs font-semibold text-zinc-700 mb-2">Error Response (404)</h3>
+          <pre className="bg-zinc-950 text-zinc-300 rounded-lg p-4 text-xs font-mono overflow-x-auto">
+{`{
+  "error": "Issue not found",
+  "hint": "No issue with id \\"nonexistent\\". Use GET /api/v1/graph to list all issues."
+}`}
+          </pre>
+        </section>
+
+        <hr className="border-zinc-100 mb-10" />
+
+        {/* GET /api/v1/ready */}
+        <section id="ready" className="mb-12 scroll-mt-8">
+          <div className="flex items-center gap-2 mb-3">
+            <span className="text-[11px] font-mono font-bold px-2 py-0.5 rounded bg-emerald-50 text-emerald-600 border border-emerald-200">
+              GET
+            </span>
+            <code className="text-sm font-mono font-semibold text-zinc-900">
+              /api/v1/ready
+            </code>
+          </div>
+          <p className="text-sm text-zinc-600 mb-4 leading-relaxed">
+            Returns issues that are ready to work on: status is <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">open</code> or <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">in_progress</code> and
+            all upstream blockers are <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">closed</code>. Sorted by priority
+            (critical first), then by age (oldest first).
+          </p>
+          <p className="text-sm text-zinc-500 mb-4 leading-relaxed">
+            This is the &ldquo;what should I work on?&rdquo; endpoint. A Playwright test bot
+            can hit <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">?type=feature&amp;unclaimed=true</code> to find untested features.
+            A code reviewer can query <code className="text-xs font-mono bg-zinc-100 px-1.5 py-0.5 rounded">?type=bug</code> to find bugs needing review.
+          </p>
+
+          <h3 className="text-xs font-semibold text-zinc-700 mb-2">Query Parameters</h3>
+          <div className="overflow-x-auto mb-4">
+            <table className="w-full text-sm border-collapse">
+              <thead>
+                <tr className="text-left text-xs text-zinc-500 border-b border-zinc-100">
+                  <th className="py-2 pr-4 font-medium">Param</th>
+                  <th className="py-2 pr-4 font-medium">Type</th>
+                  <th className="py-2 pr-4 font-medium">Default</th>
+                  <th className="py-2 font-medium">Description</th>
+                </tr>
+              </thead>
+              <tbody className="text-zinc-600">
+                <tr className="border-b border-zinc-50">
+                  <td className="py-2 pr-4 font-mono text-xs text-teal-600">unclaimed</td>
+                  <td className="py-2 pr-4 text-xs">boolean</td>
+                  <td className="py-2 pr-4 text-xs text-zinc-400">false</td>
+                  <td className="py-2 text-xs">Only return issues with no claim comment</td>
+                </tr>
+                <tr className="border-b border-zinc-50">
+                  <td className="py-2 pr-4 font-mono text-xs text-teal-600">type</td>
+                  <td className="py-2 pr-4 text-xs">string</td>
+                  <td className="py-2 pr-4 text-xs text-zinc-400">all</td>
+                  <td className="py-2 text-xs">Comma-separated issue type filter: <code className="bg-zinc-100 px-1 rounded">task,bug,feature,chore,epic</code></td>
+                </tr>
+                <tr className="border-b border-zinc-50">
+                  <td className="py-2 pr-4 font-mono text-xs text-teal-600">assignee</td>
+                  <td className="py-2 pr-4 text-xs">string</td>
+                  <td className="py-2 pr-4 text-xs text-zinc-400">all</td>
+                  <td className="py-2 text-xs">Filter by assignee handle</td>
+                </tr>
+                <tr className="border-b border-zinc-50">
+                  <td className="py-2 pr-4 font-mono text-xs text-teal-600">prefix</td>
+                  <td className="py-2 pr-4 text-xs">string</td>
+                  <td className="py-2 pr-4 text-xs text-zinc-400">all</td>
+                  <td className="py-2 text-xs">Filter by repo prefix</td>
+                </tr>
+                <tr>
+                  <td className="py-2 pr-4 font-mono text-xs text-teal-600">limit</td>
+                  <td className="py-2 pr-4 text-xs">number</td>
+                  <td className="py-2 pr-4 text-xs text-zinc-400">all</td>
+                  <td className="py-2 text-xs">Max issues returned</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+
+          <h3 className="text-xs font-semibold text-zinc-700 mb-2">Example Requests</h3>
+          <pre className="bg-zinc-950 text-zinc-300 rounded-lg p-4 text-xs font-mono overflow-x-auto mb-4">
+{`# All actionable issues
+curl http://localhost:3000/api/v1/ready
+
+# Only unclaimed bugs
+curl "http://localhost:3000/api/v1/ready?unclaimed=true&type=bug"
+
+# Top 5 highest priority
+curl "http://localhost:3000/api/v1/ready?limit=5"`}
+          </pre>
+
+          <h3 className="text-xs font-semibold text-zinc-700 mb-2">Response Shape</h3>
+          <pre className="bg-zinc-950 text-zinc-300 rounded-lg p-4 text-xs font-mono overflow-x-auto">
+{`{
+  "issues": [
+    {
+      "id": "my-proj-abc",
+      "title": "Fix login redirect",
+      "status": "open",
+      "priority": 0,
+      "issue_type": "bug",
+      ...
+      "comments": [...],
+      "claimed_by": null
+    }
+  ],
+  "stats": {
+    "total_ready": 12,
+    "unclaimed": 8,
+    "by_priority": { "0": 2, "1": 5, "2": 3, "3": 2 },
+    "by_type": { "bug": 4, "feature": 6, "task": 2 }
+  },
+  "_meta": { ... }
+}`}
+          </pre>
+        </section>
+
+        <hr className="border-zinc-100 mb-10" />
+
+        {/* Use cases */}
+        <section className="mb-12">
+          <h2 className="text-lg font-semibold text-zinc-900 mb-4">Example Use Cases</h2>
+          <div className="space-y-3">
+            {[
+              {
+                agent: "Playwright test bot",
+                endpoint: "GET /api/v1/ready?type=feature&unclaimed=true",
+                desc: "Finds untested features, writes E2E tests",
+              },
+              {
+                agent: "Code reviewer AI",
+                endpoint: "GET /api/v1/graph?status=in_progress",
+                desc: "Reviews work in progress, posts feedback as comments",
+              },
+              {
+                agent: "Planning agent",
+                endpoint: "GET /api/v1/graph",
+                desc: "Analyzes the full dependency graph, identifies bottlenecks",
+              },
+              {
+                agent: "CI/CD bot",
+                endpoint: "GET /api/v1/issues/:id",
+                desc: "Checks a specific issue's status after deployment",
+              },
+              {
+                agent: "Standup bot",
+                endpoint: "GET /api/v1/graph?include=activity&limit=20",
+                desc: "Summarizes the last 20 activities for daily standup",
+              },
+            ].map((uc) => (
+              <div
+                key={uc.agent}
+                className="flex items-start gap-3 p-3 rounded-lg bg-zinc-50 border border-zinc-100"
+              >
+                <div className="shrink-0 w-5 h-5 rounded-full bg-teal-100 flex items-center justify-center mt-0.5">
+                  <div className="w-1.5 h-1.5 rounded-full bg-teal-500" />
+                </div>
+                <div>
+                  <div className="text-xs font-semibold text-zinc-700">{uc.agent}</div>
+                  <code className="text-[11px] font-mono text-teal-600">{uc.endpoint}</code>
+                  <div className="text-xs text-zinc-500 mt-0.5">{uc.desc}</div>
+                </div>
+              </div>
+            ))}
+          </div>
+        </section>
+
+        {/* Footer */}
+        <footer className="text-center text-xs text-zinc-300 pt-6 border-t border-zinc-100">
+          Heartbeads API v1
+        </footer>
+      </div>
+    </div>
+  );
+}

package/app/api/login/route.ts

@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from "next/server";
+import { getGlobalOAuthClient } from "@/lib/auth/client";
+import { isValidHandle } from "@atproto/syntax";
+import { OAuthResolverError } from "@atproto/oauth-client-node";
+import { getRawSession } from "@/lib/session";
+
+export const dynamic = "force-dynamic";
+
+export async function POST(request: NextRequest) {
+  try {
+    const client = await getGlobalOAuthClient();
+    const body = await request.json();
+    const handle = body?.handle;
+    const returnTo = body?.returnTo;
+
+    if (typeof handle !== "string" || !isValidHandle(handle)) {
+      return NextResponse.json({ error: "Invalid handle" }, { status: 400 });
+    }
+
+    // Store returnTo in session before redirecting
+    if (returnTo && typeof returnTo === "string") {
+      const session = await getRawSession();
+      session.returnTo = returnTo;
+      await session.save();
+    }
+
+    const url = await client.authorize(handle, {
+      scope: "atproto transition:generic",
+    });
+
+    return NextResponse.json({ redirectUrl: url.toString() });
+  } catch (error) {
+    console.error("OAuth authorize failed:", error);
+    let errorMessage = "Couldn't initiate login";
+
+    if (error instanceof OAuthResolverError) {
+      errorMessage = error.message;
+    }
+
+    return NextResponse.json({ error: errorMessage }, { status: 500 });
+  }
+}

package/app/api/logout/route.ts

@@ -0,0 +1,14 @@
+import { NextResponse } from "next/server";
+import { clearSession } from "@/lib/session";
+
+export const dynamic = "force-dynamic";
+
+export async function POST() {
+  try {
+    await clearSession();
+    return NextResponse.json({ success: true });
+  } catch (error) {
+    console.error("Logout failed:", error);
+    return NextResponse.json({ error: "Logout failed" }, { status: 500 });
+  }
+}

package/app/api/oauth/callback/route.ts

@@ -0,0 +1,97 @@
+import { NextRequest } from "next/server";
+import { Agent } from "@atproto/api";
+import { getGlobalOAuthClient } from "@/lib/auth/client";
+import { getRawSession } from "@/lib/session";
+import { env } from "@/lib/env";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(request: NextRequest) {
+  try {
+    const client = await getGlobalOAuthClient();
+    const url = new URL(request.url);
+    const params = new URLSearchParams(url.search);
+
+    // Retry OAuth callback up to 3 times for network errors
+    let oauthSession;
+    let lastError;
+
+    for (let attempt = 1; attempt <= 3; attempt++) {
+      try {
+        const result = await client.callback(params);
+        oauthSession = result.session;
+        break;
+      } catch (error) {
+        lastError = error;
+        const errorMessage =
+          error instanceof Error ? error.message : String(error);
+        console.error(
+          `OAuth callback attempt ${attempt} failed:`,
+          errorMessage
+        );
+
+        const isNetworkError =
+          errorMessage.includes("UND_ERR_SOCKET") ||
+          errorMessage.includes("fetch failed") ||
+          errorMessage.includes("Failed to resolve OAuth server metadata");
+
+        if (isNetworkError && attempt < 3) {
+          await new Promise((resolve) =>
+            setTimeout(resolve, attempt * 1000)
+          );
+          continue;
+        }
+
+        throw error;
+      }
+    }
+
+    if (!oauthSession) {
+      throw lastError || new Error("Failed to create session after retries");
+    }
+
+    // Fetch profile information
+    let handle: string = oauthSession.did;
+    let displayName: string | undefined;
+    let avatar: string | undefined;
+
+    try {
+      const agent = new Agent(oauthSession);
+      const profile = await agent.getProfile({ actor: oauthSession.did });
+
+      if (profile.success) {
+        handle = profile.data.handle;
+        displayName = profile.data.displayName;
+        avatar = profile.data.avatar;
+      }
+    } catch (err) {
+      console.warn("Failed to fetch profile during login:", err);
+    }
+
+    // Save user info to session cookie and read returnTo
+    const session = await getRawSession();
+    const returnTo = session.returnTo || "/";
+    session.did = oauthSession.did;
+    session.handle = handle;
+    session.displayName = displayName;
+    session.avatar = avatar;
+    session.returnTo = undefined; // Clear after use
+    await session.save();
+
+    // Redirect to the page the user was on before login.
+    // Use PUBLIC_URL when behind a reverse proxy (Caddy/nginx), since
+    // request.url will show the internal origin (e.g., http://localhost:3000)
+    // instead of the external one (e.g., https://heartbeads.duckdns.org).
+    const origin = env.PUBLIC_URL || new URL(request.url).origin;
+    const redirectPath = returnTo.startsWith("/") ? returnTo : "/";
+
+    return Response.redirect(`${origin}${redirectPath}`, 303);
+  } catch (error) {
+    console.error("OAuth callback failed:", error);
+    const origin = env.PUBLIC_URL || new URL(request.url).origin;
+    return Response.redirect(
+      `${origin}/?error=${encodeURIComponent("Authentication failed - please try again")}`,
+      303
+    );
+  }
+}