Quartz 4

BetterFiles Chat API Handler

2 min read

BetterFiles Chat API Handler

Internal HTTP server that bridges the BetterFiles Chrome extension with the OpenClaw agent gateway. Receives chat messages from the extension, assembles cross-system context from Supabase (deal state, OTC fields, CCP data), calls the betterfiles agent via the OpenClaw gateway at 127.0.0.1:18789, and returns the agent response. Exposed via Tailscale Funnel at /betterfiles path — not public internet.

Endpoint

MethodPathDescription
POST/chatSend message with context, get agent response
GET/healthLiveness check

Port: 18802 (or process.env.BETTERFILES_CHAT_PORT) Tailscale path: https://srv1347501.tailb025a7.ts.net/betterfiles → localhost:18802 Not in Cloudflare Tunnel — Tailscale-only access.

Auth method

x-betterfiles-token header — static token from BETTERFILES_CHAT_TOKEN env var (default dev: bf-chat-day1-token, set production token in master.env). Handler rejects requests missing or mismatching the token.

CORS policy — allows Chrome extension origins and localhost dev:

  • chrome-extension://* — BetterFiles Chrome extension
  • http://localhost — local development

CORS headers: Access-Control-Allow-Methods: POST, GET, OPTIONS and Access-Control-Allow-Headers: Content-Type, x-betterfiles-token.

Payload shape

POST /chat request:

{
  "message": "string",
  "dealId": "uuid (optional)",
  "currentUrl": "string (optional)"
}

Response:

{
  "response": "string",
  "agentId": "betterfiles"
}

Downstream dispatch

betterfiles-chat-handler.js
 ├─ Auth: check x-betterfiles-token header
 ├─ Context assembly: supabase.from('...').select() → deal state, OTC fields, CCP data
 │   (SUPABASE_URL: svueekfvfrvhylxygktb, service role key from master.env)
 └─ Gateway call: POST http://127.0.0.1:18789/v1/responses
     Headers: Authorization: Bearer OPENCLAW_GATEWAY_TOKEN
     Body: enriched message + context
     → betterfiles agent → LLM via Portkey proxy

Sources for context assembly:

  • workspace/scripts/catchup-replies.js — gateway call pattern
  • knowledge-base/opentoclose/API.md — OTC field names
  • Supabase schema (verified 2026-03-18)

Dedup strategy

N/A — this is a real-time request/response handler. No event dedup needed. Chrome extension is responsible for preventing double-submission.

Audit trail

  • Fatal error handler: uncaughtException + unhandledRejection log structured JSON with handler: 'betterfiles-chat' before process exit.
  • No webhook_audit_log write — this is an agent API endpoint, not an external webhook. Logging is via gateway + agent memory.
  • Liveness: GET /health returns 200 OK for monitoring.
  • webhook-architecture — Internal handler; not in FUNNEL-REGISTRY public path list. Tailscale Funnel path is the access boundary.
  • _summary — BetterFiles agent is the downstream consumer; Chrome extension is the upstream client
  • cron-timer-registry — Service unit for this handler (verify in live systemctl state; port 18802)

Graph View