How szcharlesji/raycast-relay works
Project Type and Purpose
• This is a serverless relay service (“Raycast Relay for Cloudflare Workers”).
• It exposes an OpenAI-compatible API (endpoints under /v1/models, /v1/chat/completions, /health) and forwards requests to the Raycast AI service using your Raycast Bearer token.
• It’s written in TypeScript, packaged as a Cloudflare Worker (configured by wrangler.jsonc), and tested with Vitest.
File Structure
• Top-level: configuration and metadata files (package.json, pnpm-lock, tsconfig.json, wrangler.jsonc, eslint.config.ts).
• src/: core Worker code
• index.ts – the HTTP request handler that routes to /v1/models, /v1/chat/completions, /health.
• test/: Vitest tests (index.spec.ts) and test config (tsconfig.json, env.d.ts).
• img/: documentation screenshots.
• worker-configuration.d.ts: type definitions for the Worker environment (secrets).
Main Components
a. Client(s)
• Raycast App or any OpenAI-compatible client (e.g. Cursor).
• HTTP debug tools (Proxyman/Charles) during development.
b. Cloudflare Worker Service
• Deployed via Wrangler CLI → Cloudflare’s edge network.
• Contains the request router in src/index.ts, and accesses environment variables (RAYCAST_BEARER_TOKEN, optional API_KEY, ADVANCED, INCLUDE_DEPRECATED).
c. External Raycast AI API
• Downstream service that actually runs the AI models; the relay proxies requests here.
d. Developer Tooling & CI (optional)
• GitHub repo, Wrangler CLI on local machine, Vitest for tests.
Relationships & Data Flow
1. Client makes HTTP request → Worker endpoint (/v1/models or /v1/chat/completions).
2. Worker verifies optional API_KEY (if set), then constructs an HTTP request to the Raycast AI API, injecting RAYCAST_BEARER_TOKEN in Authorization header.
3. Raycast AI responds → Worker does any necessary transformation (e.g. filter advanced or deprecated models) → Worker returns response to Client.
4. /health endpoint returns simple OK for uptime checks.
5. Developer uses Wrangler CLI to push code to Cloudflare, and runs Vitest locally against src/index.ts.
Architectural Patterns & Design Principles
• Serverless / Edge-compute
• Single entry-point router (similar to a micro API)
• Configuration via environment variables / secrets (12-factor style)
• Lightweight pass-through with optional filtering logic
• Clear separation:
• src/ for runtime code
• test/ for automated tests
• config files (wrangler.jsonc, tsconfig.json)