Photo in, validated JSON out.

# 1. Clone
git clone https://github.com/sarmakska/receipt-scanner.git
cd receipt-scanner

# 2. Install (pnpm lockfile is committed)
pnpm install

# 3. Configure
cp .env.example .env.local
# then edit .env.local and set:
#   ANTHROPIC_API_KEY=sk-ant-...
# optional, enables R2 originals + deduplication:
#   R2_ACCOUNT_ID=...
#   R2_ACCESS_KEY_ID=...
#   R2_SECRET_ACCESS_KEY=...
#   R2_BUCKET=...

# 4. Run
pnpm dev

# 5. Visit http://localhost:3000
#    - drop in one receipt or fifty
#    - see parsed tables
#    - click Export OFX to download a statement

Full walkthrough including env var reference and first scan: Quick-Start wiki page.

// lib/vision.ts (the one place the vision call lives)
import Anthropic from '@anthropic-ai/sdk'
import { RECEIPT_JSON_SCHEMA } from './schema'

const client = new Anthropic()

export async function scanReceipt(imageJpeg: Buffer): Promise<unknown> {
  const response = await client.messages.create({
    model: process.env.VISION_MODEL ?? 'claude-opus-4-7',
    max_tokens: 4096,
    system: [
      {
        type: 'text',
        text: SYSTEM_PROMPT,
        cache_control: { type: 'ephemeral' }, // prompt caching
      },
    ],
    messages: [
      {
        role: 'user',
        content: [
          {
            type: 'image',
            source: {
              type: 'base64',
              media_type: 'image/jpeg',
              data: imageJpeg.toString('base64'),
            },
          },
        ],
      },
    ],
    // Structured-output constraint: model must emit the schema
    response_format: {
      type: 'json_schema',
      json_schema: { name: 'Receipt', schema: RECEIPT_JSON_SCHEMA },
    },
  })

  return response.content[0]?.type === 'text'
    ? JSON.parse(response.content[0].text)
    : null
}

// lib/schema.ts (the Zod contract every scan must satisfy)
import { z } from 'zod'

export const LineItemSchema = z.object({
  description: z.string().nullable(),
  quantity: z.number().nullable(),
  unit_price: z.number().nullable(),
  total: z.number().nullable(),
})

export const ReceiptSchema = z.object({
  vendor: z.object({
    name: z.string().nullable(),
    address: z.string().nullable(),
  }),
  transaction: z.object({
    date: z.string().nullable(),    // ISO 8601
    time: z.string().nullable(),    // HH:MM:SS
  }),
  currency: z.string().length(3).nullable(), // ISO 4217
  line_items: z.array(LineItemSchema),
  subtotal: z.number().nullable(),
  tax: z.number().nullable(),
  tip: z.number().nullable(),
  total: z.number().nullable(),
  payment_method: z.string().nullable(),
})

export type Receipt = z.infer<typeof ReceiptSchema>

export type StoredReceipt = Receipt & {
  id: string
  image_key: string | null     // R2 key, null when R2 is not configured
  image_sha256: string         // always computed, used as content address
  created_at: string
}