cosmoe-bot/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

• npm run dev — Start local dev server (Wrangler)
• npm run deploy — Deploy to Cloudflare Workers (wrangler deploy)
• npm test — Run tests with Vitest (Cloudflare Workers pool)
• npm run cf-typegen — Regenerate TypeScript types from Wrangler config

Architecture

Telegram bot for the CosMoe photography platform (https://cos.cx/api/v1), deployed as a Cloudflare Worker with a 1-minute cron trigger.

Entry points (src/index.ts)

• fetch handler — Receives Telegram webhooks, creates a grammy Bot, registers commands via setupCommands(), delegates to webhookCallback.
• scheduled handler — Runs every minute via cron. Checks for new events and pushes notifications to all registered users.

Command routing (src/command/index.ts)

setupCommands() wires grammy commands, conversation plugins, regex-based hears handlers, and callbackQuery handlers. The conversations plugin uses KV-backed storage for multi-step flows (login).

Bot commands: start, login, events, history, logout Pattern handlers: /event_{id}, /book_{eventId}_{slotIndex}, /cancel_{bookingId} Callback queries: cancel confirmation, coupon selection

Handlers (src/command/handlers/)

Each is a standalone async function. Most follow the pattern: authenticate user from KV → call CosMoe API → format and reply.

API client (src/client/cosmoe.ts)

CosmoeClient wraps the CosMoe REST API. Auth uses user_id + token passed as URL params (GET) or FormData (POST). Credentials are stored per-user in COSMOE_CREDENTIALS KV keyed by Telegram user ID.

Scheduler (src/scheduler/index.ts)

Tracks notified event IDs in COSMOE_STORAGE KV to avoid duplicate notifications. Iterates all credential keys to broadcast to every registered user.

KV namespaces

• COSMOE_CREDENTIALS — Per-user auth tokens (keyed by Telegram user ID)
• COSMOE_STORAGE — Conversation state and scheduler data

Key conventions

• All user-facing text is Chinese.
• Beijing timezone (UTC+8) is hardcoded for date comparisons in handlers and scheduler.
• Formatting: Prettier with tabs, single quotes, 140 char width.
• TypeScript: ES2024, strict mode, Bundler module resolution.
• The Env interface is defined separately in src/command/index.ts; handlers receive env as an untyped any parameter.
• Tests use @cloudflare/vitest-pool-workers for the Workers runtime.