Skip to content

Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.

12.2 KB
Raw Blame

Cloudflare Workers

Worker Configuration (backend/wrangler.toml)

name = "twiligent"
main = "server.ts"
compatibility_date = "2025-01-01"

[triggers]
crons = ["* * * * *", "*/5 * * * *", "0 0 * * *"]
  • name - the Worker name as deployed on Cloudflare; also determines the default URL
  • main - entry point file (backend/server.ts). Wrangler bundles it with esbuild, which strips the TypeScript types without checking them; npm run typecheck is the check
  • compatibility_date - pins the Workers runtime API version
  • crons - cron trigger schedules (see docs/architecture/backend/CRON.md). The every minute trigger sends waiting comment replies and follow-ups; the five minute trigger publishes due posts on the quarter hour and checks the reply queue on its other runs; the daily trigger refreshes tokens and deletes old records. The Workers Free plan allows five cron triggers per account and this Worker uses three, so a self-hoster with other Workers should count the triggers on their account first. Each cron run counts as a Worker request: the every minute trigger adds 1,440 a day (about 1.4% of the Free plan's 100,000), the five minute one 288 and the daily one 1

Worker Export Format

The Worker exports two handlers:

export default {
    fetch: app.fetch,            // handles HTTP requests (the Hono app from backend/app.ts)
    async scheduled(event: ScheduledController, env: Env, ctx: ExecutionContext) {   // handles cron triggers
        ctx.waitUntil(runScheduledJob(event.cron, env, event.scheduledTime));
    },
} satisfies ExportedHandler<Env>;

event.cron is the cron expression that fired, event.scheduledTime the minute it was due for, env holds the Worker secrets and variables, and ctx.waitUntil(promise) keeps the Worker alive for the job. runScheduledJob() in backend/jobs/scheduled.ts picks the job for the expression; see docs/architecture/backend/CRON.md.

ScheduledController, ExecutionContext and ExportedHandler come from @cloudflare/workers-types, which backend/tsconfig.json loads as its only ambient types.

Environment Bindings (Secrets)

All secrets are set via npx wrangler secret put <NAME>, run from backend/. They are available at runtime as env.NAME or c.env.NAME, typed by the Env interface in backend/types/env.ts. The three Supabase values are declared as string; the rest are optional (?: string), so code that reads them handles the missing case. Application code reads them through readConfig(env) in backend/lib/config.ts, which trims stray whitespace and byte order marks; a request that needs a missing optional value fails with 503 (NOT_CONFIGURED).

Secret Required Purpose
SUPABASE_URL Yes Supabase project URL
SUPABASE_SERVICE_KEY Yes Service-role key - bypasses RLS, all DB operations
SUPABASE_ANON_KEY Yes Anon key - used only for JWT verification in requireAuth
YOUTUBE_API_KEY Yes Shared YouTube Data API v3 key (all users share quota)
INSTAGRAM_APP_ID Yes Meta/Facebook App ID for OAuth
INSTAGRAM_APP_SECRET Yes Used for OAuth token exchange + HMAC state signing
CLOUDINARY_CLOUD_NAME Yes Cloudinary cloud name
CLOUDINARY_UPLOAD_PRESET Yes Unsigned upload preset for direct browser uploads
BACKEND_URL Yes This Worker's public URL (for OAuth callback construction)
FRONTEND_URL Yes Frontend URL: the browser origin CORS allows, and the post-OAuth redirect back to the SPA
ALLOWED_ORIGINS Optional Comma-separated extra browser origins CORS allows besides FRONTEND_URL, such as a second domain (https://a.example.com,https://b.example.com). Set it with wrangler secret put like the others, so the next wrangler deploy keeps it (a plain variable added in the dashboard can be replaced on deploy)
UPSTASH_REDIS_REST_URL Optional Upstash Redis endpoint; caching disabled if absent
UPSTASH_REDIS_REST_TOKEN Optional Upstash auth token
SEND_EMAIL_HOOK_SECRET Optional The Send Email hook secret from Supabase (v1,whsec_...); verifies that POST /api/auth/email-hook was called by your Supabase Auth. Without it the hook answers 503
RESEND_API_KEY Optional Resend API key with sending access; sends the auth emails (verification codes)
EMAIL_FROM Optional Sender of the auth emails on a domain verified in Resend, such as Twiligent <[email protected]>
EMAIL_DAILY_LIMIT Optional Auth emails a day across all users (each code sign-in is one) before the sign-in page pauses email codes and points to Google or a password; defaults to 100, Resend's free daily quota
INSTAGRAM_WEBHOOK_VERIFY_TOKEN Optional The Verify Token typed into the Meta dashboard's Instagram webhook settings; GET /api/webhooks/instagram answers Meta's check only with it. Without it, and INSTAGRAM_APP_SECRET, no comment reaches the Worker and the Instagram automation page says so
CLOUDINARY_API_KEY, CLOUDINARY_API_SECRET Optional The Cloudinary account's API key and secret (Settings, API Keys). Only for deleting files through the Claude delete_media tool; without them a delete removes Twiligent's record and says the file stays on Cloudinary. Never sent to the browser
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET Optional The Google Cloud Web application OAuth client for YouTube publishing (redirect URI <BACKEND_URL>/api/auth/youtube/callback). With TOKEN_ENCRYPTION_KEY they turn YouTube publishing on; see docs/platform-v2/YOUTUBE_INTEGRATION.md
TOKEN_ENCRYPTION_KEY Optional At least 32 random characters (openssl rand -base64 48). Keys derived from it sign the MCP confirmation tokens and seal the stored Google tokens (AES-GCM). Without it the Claude tools that publish or delete refuse to run and YouTube publishing stays off. Changing it voids confirmations in flight and makes every stored Google token unreadable, so people connect YouTube again
MCP_OAUTH_ENABLED Optional true once Supabase Auth's OAuth server is turned on with the authorization path /oauth/consent; the MCP endpoint then publishes its protected resource metadata, so Claude on the web, desktop and mobile can connect. Access tokens work without it
META_APP_SECRET Optional The Meta app's own secret (App settings, Basic). Webhook signatures are checked against INSTAGRAM_APP_SECRET and, when this is set, against it too
AUTOMATION_PAUSED Optional true holds every comment-to-DM reply on the instance; comments are still stored and matched
AUTOMATION_ACCOUNT_HOURLY_LIMIT Optional Private replies an hour per Instagram account; default 200, at most 750 (Instagram's limit)
AUTOMATION_USER_HOURLY_LIMIT Optional Private replies an hour across one member's accounts; default 500
AUTOMATION_GLOBAL_HOURLY_LIMIT Optional Private replies an hour across the instance; default 1000
AUTOMATION_RECIPIENT_DAILY_LIMIT Optional Private replies a day one person can get from one account; default 3
AUTOMATION_PUBLIC_ACCOUNT_HOURLY_LIMIT Optional Public replies under comments an hour per Instagram account; default 60, at most 200. Meta publishes no limit for comment replies but blocks accounts that comment like a bot, so the pace stays human
AUTOMATION_BATCH_SIZE Optional Replies sent by one webhook request or one dispatch run, for each kind of reply; default 10, at most 15 (each costs three of the free plan's 50 subrequests)

The automation values are plain settings, not secrets, but setting them with wrangler secret put keeps them across deploys like the rest. A missing or invalid value falls back to its default.

Setting secrets

cd backend
npx wrangler secret put SUPABASE_URL
npx wrangler secret put SUPABASE_SERVICE_KEY
# (paste value when prompted - no echo)

Local development (.dev.vars)

Create backend/.dev.vars (gitignored) with the same keys:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
YOUTUBE_API_KEY=AIzaSy...
INSTAGRAM_APP_ID=123456789
INSTAGRAM_APP_SECRET=abc123...
CLOUDINARY_CLOUD_NAME=mycloud
CLOUDINARY_UPLOAD_PRESET=ml_default
BACKEND_URL=http://localhost:8787
FRONTEND_URL=http://localhost:5173
# ALLOWED_ORIGINS=https://another-domain.example.com
UPSTASH_REDIS_REST_URL=https://...
UPSTASH_REDIS_REST_TOKEN=...
# only to test the Send Email hook locally; Supabase cannot reach localhost, so sign request bodies yourself
# SEND_EMAIL_HOOK_SECRET=v1,whsec_...
# RESEND_API_KEY=re_...
# EMAIL_FROM=Twiligent <[email protected]>
# only to test the Instagram webhook locally; Meta cannot reach localhost, so sign request bodies yourself
# INSTAGRAM_WEBHOOK_VERIFY_TOKEN=a-long-random-string
# AUTOMATION_PAUSED=true
# signs the MCP confirmation tokens; any 32 or more random characters
# TOKEN_ENCRYPTION_KEY=...

Run locally from the repository root: npm run dev:backend (Worker only, port 8787) or npm run dev (Worker and Vite together). Both run wrangler dev in backend/, which reloads on save.

CORS origins

The API answers browsers only on FRONTEND_URL and the origins in ALLOWED_ORIGINS; a browser on any other origin is blocked. A Worker served from localhost or 127.0.0.1 also allows the Vite dev server (http://localhost:5173 and http://127.0.0.1:5173), so local development needs no extra setting. Requests without an Origin header (curl, the GitHub Actions scheduler) are not affected. See docs/architecture/backend/MIDDLEWARE.md.

Worker Constraints

These are hard constraints imposed by the Cloudflare Workers runtime. Violating them causes runtime errors:

  1. No Node.js APIs. No fs, Buffer, path, process.env (use c.env), require(). Everything must be ESM import. backend/tsconfig.json does not load the Node types, so npm run typecheck flags these in Worker source.

  2. No binary file handling. The Worker cannot efficiently stream large binary files. Never add routes that accept file uploads - Cloudinary handles that directly from the browser.

  3. No persistent state between requests. The Worker isolate may be a fresh instance on every request. Do not rely on module-level variables to persist state across requests. All state must come from Supabase, Redis, or Worker KV. (The cache cooldown and the rate limiter's memory fallback keep per-isolate state on purpose, as a best-effort optimization that is safe to lose.)

  4. CPU time limit. On the Workers Free plan each invocation gets 10 ms of CPU time (Workers Paid: 30 seconds by default, up to 5 minutes). Time waiting on fetch does not count, so I/O-bound work fits; long synchronous work is killed. Use async/await for all I/O.

  5. Subrequests. On the Workers Free plan an invocation can make 50 subrequests (each fetch, including Supabase and Redis calls); Workers Paid allows 10,000. A webhook request, a dispatch run, a reconcile run and a publishing run each count separately. AUTOMATION_BATCH_SIZE is capped at 15 for this reason, and a fetch the runtime refuses at the cap is recorded as not sent rather than as an unknown outcome.

  6. ctx.waitUntil() in cron handlers and after responses. Cron handlers must use ctx.waitUntil(promise) for async work. Without it, the Worker may terminate before the work completes. After an HTTP response, waitUntil keeps the Worker running for at most 30 seconds; inBackground() in controllers/http.ts gives such work its own 25 second deadline.

  7. Bundle size. The Worker bundle must be a single ESM file (Wrangler handles bundling). Avoid large dependencies. Type-only imports, including everything in shared/types/, add nothing to the bundle.

Adding a New Worker Secret

  1. Declare it in the Env interface in backend/types/env.ts (NEW_SECRET_NAME?: string unless the Worker cannot run without it), and read it into AppConfig in backend/lib/config.ts with cleanSecret()
  2. Set via npx wrangler secret put NEW_SECRET_NAME from backend/
  3. Add to backend/.env.example with a placeholder value
  4. Add to backend/.dev.vars locally
  5. Set as a GitHub secret if needed by deploy workflow
  6. Update docs/architecture/cloudflare/WORKERS.md (this file)
  7. Append to DECISIONS.md if it represents an architectural dependency