notion-exrate-worker/CLAUDE.md

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

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:

# Test scheduled handler
curl "http://localhost:8787/__scheduled?cron=0+*+*+*+*"

# Manual sync
curl "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
/	Info page

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

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.