# CLAUDE.md

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

## Project Overview

A Cloudflare Workers **Scheduled Worker** that fetches exchange rates from Open Exchange Rates API and updates a Notion database hourly. Also provides a currency conversion API.

## Commands

```bash
npm run dev          # Start local dev server with scheduled trigger testing
npm run deploy       # Deploy to Cloudflare Workers
npm run cf-typegen   # Regenerate TypeScript types after changing bindings
```

### Testing Locally

After `npm run dev`:
```bash
# Test scheduled handler
curl "http://localhost:8787/__scheduled?cron=0+*+*+*+*"

# Manual sync (requires token)
curl "http://localhost:8787/sync?token=YOUR_SYNC_TOKEN"
# or with Authorization header
curl -H "Authorization: Bearer YOUR_SYNC_TOKEN" "http://localhost:8787/sync"

# Currency conversion
curl "http://localhost:8787/convert?from=USD&to=CNY&amount=100"
```

## Architecture

- **Entry Point**: `src/index.ts` - exports an `ExportedHandler<Env>` with `fetch` and `scheduled` handlers
- **Configuration**: `wrangler.jsonc` - defines cron triggers and compatibility flags
- **TypeScript**: ES2024 target, strict mode, types in `worker-configuration.d.ts` and `src/env.d.ts`

### Cron Schedule

Hourly at minute 0 (`0 * * * *`).

### API Endpoints

| Endpoint | Description |
|----------|-------------|
| `/convert?from=USD&to=CNY&amount=100` | Convert currency (data from Notion database) |
| `/sync` | Manually trigger exchange rate sync from OXR to Notion |

### Environment Variables (Secrets)

Set via `wrangler secret put <NAME>` or `.dev.vars` for local development:

| Variable | Description |
|----------|-------------|
| `OXR_APP_ID` | Open Exchange Rates API App ID |
| `NOTION_TOKEN` | Notion Integration Token |
| `NOTION_DATABASE_ID` | Notion Database ID |
| `SYNC_TOKEN` | Token for manual sync endpoint authorization |

### Notion Database Structure

| Property | Type | Description |
|----------|------|-------------|
| `Code` | Title | Currency code (e.g., USD, EUR, CNY) |
| `Rate` | Number | Exchange rate against USD |
| `Updated At` | Date | Last update timestamp |

### Data Flow

1. **Sync** (hourly or manual): Fetch rates from OXR API → Update Notion database
2. **Convert**: Read rates from Notion database → Calculate conversion

## Node.js Compatibility

The `nodejs_compat` flag is enabled, allowing use of Node.js runtime APIs in the worker.

## Reference

See `AGENTS.md` for Cloudflare Workers documentation links and error handling guidance.