collabGPT

OAuth Action backend for a private or invite‑only Custom GPT to capture and share notes with attribution. Built with Bun + Hono + Zod + zod‑openapi, Clerk OAuth (OIDC), and a single JSON file on a persistent volume.

⚠️ Important Zod Pattern Note

NEVER use z.record(z.any()) - this is invalid Zod syntax and will cause runtime errors.

ALWAYS use z.record(z.any(), z.any()) - Zod’s record type requires two arguments:

• First argument: key type
• Second argument: value type

Example:

// ❌ WRONG - Will cause errors
z.record(z.any())

// ✅ CORRECT
z.record(z.any(), z.any())  // any key, any value
z.record(z.string(), z.number())  // string keys, number values

What It Does

• Knowledge Base API with Meilisearch backend:
  • POST /documents — upsert documents with auto-chunking
  • GET /documents/:id — retrieve specific document
  • GET /search — full-text search with facets and filtering
  • POST /annotate — partial updates to documents/chunks
  • POST /config/ranking — configure search ranking rules
• Sourcegraph Integration:
  • POST /graphql — GraphQL passthrough to Sourcegraph API
  • Full code intelligence across all Kognova repositories
• Userscripts System (NEW):
  • GET /userscripts — list available userscripts
  • POST /userscripts/:id/compile — compile userscript with metadata
  • PUT /userscripts/:id/metadata — update metadata with auto-versioning
  • Internal routes for serving compiled scripts (see below)
• Validates requests with Clerk OAuth (OIDC) or cookie authentication
• Publishes OpenAPI at /openapi.json and Swagger UI at /docs for easy Action schema import

Quick Start (Dev)

1. Run the orchestrator from repo root:
   • bun run start
   • This picks up collabGPT/server.agent.md and starts the API on http://localhost:8080.
2. Dev auth (no Clerk needed):
   • Default user is sub=dev_sub, email=dev@example.com.
   • Override via headers: Authorization: Bearer dev:my_sub:me@example.com.
   • Or set env: CLERK_DEV_ALLOW_INSECURE=1, DEV_SUB, DEV_EMAIL.

Production Auth (Clerk OIDC)

• Create an OAuth application in Clerk and use its hosted sign‑in (Account Portal).
• In GPT Builder → Actions → Authentication: choose OAuth.
  • Authorize URL: Clerk authorize endpoint
  • Token URL: Clerk token endpoint
  • Scopes: openid email profile (add more only if required)
  • Callback URL: copy from GPT Builder into Clerk’s Redirect URI list
• Backend env:
  • CLERK_ISSUER=https://<your>.clerk.accounts.dev
  • CLERK_AUDIENCE=<your-oauth-client-id-or-aud>
• Notes:
  • Backend validates bearer tokens (issuer, audience, exp, signature via JWKS).
  • If your access token is opaque, call the userinfo endpoint instead and map claims; current code expects JWT access/ID tokens.

Userscripts System

The API now includes a complete userscripts management system for browser automation and enhancement.

Architecture

Dual Router Pattern: We use separate routers for public API endpoints vs internal serving routes:

1. Public API Routes (api/routes/userscripts.ts):
   • Mounted at /userscripts
   • Protected by auth middleware
   • Returns JSON responses
   • Used for management operations (list, compile, update)
   • Documented in OpenAPI spec
2. Internal Serving Routes (api/internal/userscripts.ts):
   • Also mounted at /userscripts (overlapping paths)
   • Serves HTML pages and raw JavaScript
   • Sets authentication cookies
   • Used for browser installation flow
   • Not included in OpenAPI (intentionally)

Userscript Workflow

1. Development: Write userscripts in scripts/userscripts/*.js
2. Compilation: POST to /userscripts/:id/compile adds metadata headers
3. Installation: Visit /userscripts/:id/install in browser
   • Sets authentication cookie (collabgpt_auth)
   • Shows installation page with button
4. Auto-Update: Scripts check /userscripts/:id/meta for new versions
5. Download: Browser fetches from /userscripts/:id/script

Example Userscripts

• github-enhancer.js: Adds CollabGPT search to GitHub repos
• api-helper.js: Floating widget for API access from any webpage

Cookie Authentication

Userscripts use cookie-based auth since they can’t easily manage Bearer tokens:

• Cookie set during installation: collabgpt_auth=true
• Checked in api/auth.ts before Bearer token validation
• Allows userscripts to make authenticated API calls

Endpoints & Schemas

Knowledge Base Endpoints

• POST /documents — upsert document with auto-chunking
• GET /documents/:id — retrieve document by ID
• GET /search — full-text search with filtering
• POST /annotate — partial update to document/chunk
• POST /config/ranking — update search ranking rules

Sourcegraph Endpoints

• POST /graphql — GraphQL passthrough to Sourcegraph
• GET /sourcegraph/status — check configuration status

Userscripts Endpoints (Public API)

• GET /userscripts — list available userscripts
• GET /userscripts/:id — get userscript info
• POST /userscripts/:id/compile — compile with metadata
• PUT /userscripts/:id/metadata — update metadata (auto-increments version)

Userscripts Endpoints (Internal Serving)

• GET /userscripts/:id/install — HTML installation page (sets cookie)
• GET /userscripts/:id/script — serve compiled userscript
• GET /userscripts/:id/meta — serve metadata block only

System Endpoints

• GET /healthz — health check
• GET /openapi.json — OpenAPI specification
• GET /docs — Swagger UI
• GET /llms.txt — LLM-friendly docs with OpenAPI YAML

Storage

• Path: /data/kb.json in Fly.io; in dev defaults to ./collabGPT_data/kb.json.
• Write safety: in‑process write queue; writes go to a temp file then rename for atomicity; a .bak snapshot is created on first write.
• Env: set DATA_DIR=/data in production to match your volume mount.

Run Manually (without orchestrator)

bun run collabGPT/server.ts
# PORT=8080 by default

Static Site (Astro)

• Install and build from the collabGPT folder:
  • cd collabGPT && bun install && bun run site:build
  • Output goes to /docs for GitHub Pages
• Local preview:
  • cd collabGPT && bun run site:dev

OpenAPI Snippet (for GPT Action)

paths:
  /notes:
    get:
      operationId: listNotes
      summary: List shared notes
      responses:
        "200": { description: OK }
    post:
      operationId: createNote
      summary: Create a new note attributed to the caller
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text: { type: string }
      responses:
        "200": { description: Created }
  /notes/search:
    get:
      operationId: searchNotes
      parameters:
        - in: query
          name: q
          required: true
          schema: { type: string }
      responses:
        "200": { description: OK }

Deployment (Fly.io)

Dockerfile (example):

FROM oven/bun:1.1
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile
COPY . .
EXPOSE 8080
ENV PORT=8080
CMD ["bun", "run", "collabGPT/server.ts"]

fly.toml (sketch):

app = "collabgpt-notes"
primary_region = "den"

[build]
  dockerfile = "Dockerfile"

[[mounts]]
  source = "kb_data"
  destination = "/data"

[http_service]
  internal_port = 8080
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true

Volume:

fly volumes create kb_data --region den --size 1

Env to set in Fly:

• CLERK_ISSUER
• CLERK_AUDIENCE
• DATA_DIR=/data
• PORT=8080

Voice UX Caveat

Advanced Voice Mode in ChatGPT currently doesn’t trigger external Actions. Include a brief instruction in your GPT for voice users to switch to text when they want to save/read notes.