Development Guide

This file provides guidance for coding agents working in this repository.

Essential Commands

Development

• pnpm run dev - Start local development (wrangler dev on :8080 + local SES on :8005)
• pnpm run create-token - Generate JWT token for API testing

Quality Checks

• pnpm run lint - Run Biome checks
• pnpm run fix - Apply Biome formatting/fixes
• pnpm run typecheck - Run TypeScript type checking
• pnpm run test - Run unit tests
• pnpm run test:coverage - Run tests with coverage

Architecture Overview

• Runtime: Cloudflare Workers + Hono
• Deployment: GitHub Actions (staging branch -> staging, main branch -> production)
• Auth: JWT middleware on /api/*
• OpenAPI: served at /schema/v1

Email Delivery Flow

• POST /api/v1/send: send a single email via AWS SES
• POST /api/v1/send-multiple: accept an async campaign and enqueue up to 100 recipients per queue message
• Queue consumer: sends emails via AWS SES with controlled pace (~8/sec)
• Retry policy: queue-level retries with DLQ fallback

Storage and Logging

• R2 bucket binding: MAIL_LOGS_BUCKET
• Campaign acceptance logs and recipient failure logs are stored as JSON

Required Bindings and Vars

• ENVIRONMENT
• TOKEN_SECRET
• ERROR_NOTIFICATION_TOKEN
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• MAIL_LOGS_BUCKET
• MAIL_SEND_QUEUE

Working Conventions

• Use TDD where practical.
• Keep API contracts stable unless explicitly requested.
• Prefer minimal, focused changes and keep tests updated.
• Communicate with the developer in Japanese.
• Write code comments and documentation in English.

Change Checklist

When implementing changes, make sure to:

1. Update related tests.
2. Run pnpm run lint, pnpm run typecheck, and pnpm run test.
3. Regenerate Worker types after Wrangler binding changes:
   • pnpm run gen:cf-types