The Vocho shop,
built to cost less.

                         ┌────────────────────────────────────────────┐
                         │            Cloudflare network                │
Visitor browser  ──────▶ │                                            │
                         │   Pages / Worker (static assets + API)      │
                         │        │             │            │         │
                         │        ▼             ▼            ▼         │
                         │    ┌──────┐     ┌──────┐     ┌───────┐      │
                         │    │  D1  │     │  R2  │     │  KV   │      │
                         │    │ SQL  │     │images│     │tokens │      │
                         │    │orders│     │      │     │sessions│     │
                         │    └──────┘     └──────┘     └───────┘      │
                         │        │                                    │
                         │        ▼   (server-side webhooks, never     │
                         │    ┌──────────────────┐     browser-only)   │
                         │    │  Stripe API +    │                     │
                         │    │  PayPal Partner  │                     │
                         │    └──────────────────┘                     │
                         └────────────────────────────────────────────┘
                                    │
                                    ▼
                        Email (order + stock alerts)

Admin owner  ──▶ /admin  gated by  Cloudflare Access (Zero Trust)
                 (email-link login, no public password to leak)

CREATE TABLE vehicles (
  id         INTEGER PRIMARY KEY AUTOINCREMENT,
  slug       TEXT UNIQUE NOT NULL,   -- 'vocho','combi','brasilia','caribe','safari'
  name       TEXT NOT NULL,          -- 'Vocho'
  full_name  TEXT,                   -- 'Volkswagen Tipo 1 (Sedan)'
  year_start INTEGER,
  year_end   INTEGER
);

CREATE TABLE vehicle_variants (
  id         INTEGER PRIMARY KEY AUTOINCREMENT,
  vehicle_id INTEGER NOT NULL REFERENCES vehicles(id) ON DELETE CASCADE,
  label      TEXT NOT NULL,          -- 'Vocho 1500','Combi Bay','Brasilia 1600'
  year_start INTEGER,
  year_end   INTEGER
);

CREATE TABLE products (
  id                INTEGER PRIMARY KEY AUTOINCREMENT,
  sku               TEXT UNIQUE NOT NULL,   -- 'VO-113-501-041-NOS'
  part_number       TEXT NOT NULL,          -- OEM / cross number '113 501 041'
  name              TEXT NOT NULL,
  short_description TEXT,
  long_description  TEXT,
  category          TEXT NOT NULL,          -- 'suspension','electrical','engine'...
  condition         TEXT NOT NULL
                    CHECK (condition IN ('NOS','reproduction','used')),
  brand             TEXT,
  weight_grams      INTEGER,
  active            INTEGER NOT NULL DEFAULT 1,
  created_at        TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE INDEX idx_products_condition ON products(condition);
CREATE INDEX idx_products_category   ON products(category);

-- a part fits many vehicles/variants
CREATE TABLE product_compat (
  product_id INTEGER NOT NULL REFERENCES products(id) ON DELETE CASCADE,
  vehicle_id INTEGER NOT NULL REFERENCES vehicles(id)  ON DELETE CASCADE,
  variant_id INTEGER REFERENCES vehicle_variants(id)   ON DELETE CASCADE,
  note       TEXT,         -- 'front left','with ball joints'...
  PRIMARY KEY (product_id, vehicle_id, variant_id)
);

CREATE TABLE inventory (
  id               INTEGER PRIMARY KEY AUTOINCREMENT,
  product_id       INTEGER NOT NULL REFERENCES products(id) ON DELETE CASCADE,
  location         TEXT NOT NULL DEFAULT 'stockroom',
  quantity_on_hand INTEGER NOT NULL DEFAULT 0,
  quantity_reserved INTEGER NOT NULL DEFAULT 0,
  reorder_point    INTEGER NOT NULL DEFAULT 0
);

-- A reservation holds stock for an in-flight checkout and auto-expires.
CREATE TABLE reservations (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  reserve_key TEXT UNIQUE NOT NULL,     -- deterministic idempotency key
  order_id    INTEGER REFERENCES orders(id),
  created_at  TEXT NOT NULL DEFAULT (datetime('now')),
  expires_at  TEXT NOT NULL             -- e.g. paid by +15 minutes
);
CREATE TABLE reservation_items (
  reservation_id INTEGER NOT NULL REFERENCES reservations(id) ON DELETE CASCADE,
  inventory_id   INTEGER NOT NULL REFERENCES inventory(id),
  quantity       INTEGER NOT NULL CHECK (quantity > 0),
  PRIMARY KEY (reservation_id, inventory_id)
);

CREATE TABLE product_images (
  id         INTEGER PRIMARY KEY AUTOINCREMENT,
  product_id INTEGER NOT NULL REFERENCES products(id) ON DELETE CASCADE,
  r2_key     TEXT NOT NULL,            -- path inside the R2 bucket
  alt_text   TEXT,
  sort_order INTEGER NOT NULL DEFAULT 0,
  is_primary INTEGER NOT NULL DEFAULT 0
);

-- Store both currencies; keep the exchange snapshot for reporting only.
CREATE TABLE prices (
  id             INTEGER PRIMARY KEY AUTOINCREMENT,
  product_id     INTEGER NOT NULL REFERENCES products(id) ON DELETE CASCADE,
  currency       TEXT NOT NULL CHECK (currency IN ('MXN','USD')),
  amount_minor   INTEGER NOT NULL,     -- smallest monetary unit, never a float
  fx_rate_to_usd REAL,                 -- snapshot at update time
  updated_at     TEXT NOT NULL DEFAULT (datetime('now')),
  UNIQUE (product_id, currency)
);

CREATE TABLE customers (
  id         INTEGER PRIMARY KEY AUTOINCREMENT,
  email      TEXT NOT NULL,
  name       TEXT,
  phone      TEXT,
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE TABLE addresses (
  id          INTEGER PRIMARY KEY AUTOINCREMENT,
  customer_id INTEGER NOT NULL REFERENCES customers(id) ON DELETE CASCADE,
  kind        TEXT NOT NULL CHECK (kind IN ('shipping','billing')),
  line1       TEXT NOT NULL,
  line2       TEXT,
  postal_code TEXT NOT NULL,
  city        TEXT NOT NULL,
  state       TEXT,
  country     TEXT NOT NULL DEFAULT 'MX',
  is_default  INTEGER NOT NULL DEFAULT 0
);

-- Weight per part drives carrier quotes; store it on products (see 02).

CREATE TABLE orders (
  id                  INTEGER PRIMARY KEY AUTOINCREMENT,
  order_number        TEXT UNIQUE NOT NULL,   -- friendly, e.g. 'A-1042'
  customer_id         INTEGER REFERENCES customers(id),
  email               TEXT NOT NULL,
  status              TEXT NOT NULL CHECK (status IN (
     'pending','payment_processing','paid','reserved','fulfilling',
     'shipped','delivered','cancelled','refund_pending','refunded','failed')),
  shipping_address_id INTEGER REFERENCES addresses(id),
  currency            TEXT NOT NULL,
  total_minor         INTEGER NOT NULL,
  created_at          TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at          TEXT NOT NULL DEFAULT (datetime('now'))
);
CREATE INDEX idx_orders_status ON orders(status);

CREATE TABLE order_items (
  id               INTEGER PRIMARY KEY AUTOINCREMENT,
  order_id         INTEGER NOT NULL REFERENCES orders(id) ON DELETE CASCADE,
  product_id       INTEGER NOT NULL REFERENCES products(id),
  inventory_id     INTEGER REFERENCES inventory(id),
  sku              TEXT NOT NULL,
  name             TEXT NOT NULL,
  quantity         INTEGER NOT NULL CHECK (quantity > 0),
  unit_price_minor INTEGER NOT NULL,   -- frozen at checkout
  currency         TEXT NOT NULL
);

CREATE TABLE payments (
  id                INTEGER PRIMARY KEY AUTOINCREMENT,
  provider          TEXT NOT NULL CHECK (provider IN ('stripe','paypal')),
  provider_event_id TEXT,              -- Stripe event id / PayPal webhook id
  provider_payment_id TEXT NOT NULL,   -- Stripe PaymentIntent / PayPal capture
  order_id          INTEGER NOT NULL REFERENCES orders(id),
  amount_minor      INTEGER NOT NULL,
  currency          TEXT NOT NULL,
  status            TEXT NOT NULL,     -- pending/succeeded/failed/refunded/partial
  idempotency_key   TEXT UNIQUE,
  created_at        TEXT NOT NULL DEFAULT (datetime('now')),
  UNIQUE (provider, provider_event_id)
);

// Client -> server. Returns the same order on retry.
const res = await createCheckout({ data: {
  reserveKey: cartReserveKey,      // UUID the client already generated
  items, shippingAddress, email
}});

// Server handler
if (alreadyReserved(reserveKey)) return existingOrder(reserveKey);
reserveStock(reserveKey, items, expiresAt = now + 15min);  // rows_inv.reserved += qty
return newOrderWithStatus('payment_processing', reserveKey);

import Stripe from "stripe";
const stripe = new Stripe(env.STRIPE_SECRET_KEY);

// 1. Verify the signature, check timestamp skew, throw on fraud.
let event;
try {
  event = stripe.webhooks.constructEvent(
    rawBody, sigHeader, env.STRIPE_WEBHOOK_SECRET);
} catch { return respond(400, "invalid signature"); }

// 2. Idempotency: one outcome per (provider, event id).
if (paymentExists(event.id)) return respond(200, "already handled");

// 3. Act on known events.
switch (event.type) {
  case "checkout.session.completed":
  case "payment_intent.succeeded":
    commitPayment(event.id, paymentId, orderId, amount, currency);
    break;
  case "charge.refunded":
    recordRefund(orderId, amount);
    break;
}
return respond(200);

// PayPal sends you a signature to verify against their public key:
//   PAYPAL-TRANSMISSION-ID / -SIG / -CERT-URL / -AUTH-ALGO / -TIME, CRYPTO
// 1. Fetch the cert at PAYPAL-TRANSMISSION-CERT-URL, verify CRYPTO signature,
//    confirm the certificate resolves to *.paypal.com, check TIME skew.
// 2. Verify the event was NOT already applied (idempotency by event id).
// 3. Then act on event types: CHECKOUT.ORDER.APPROVED /
//    PAYMENT.CAPTURE.COMPLETED / PAYMENT.CAPTURE.REFUNDED.

// Simpler and robust: keep the JS SDK "Orders" flow, and at each step
// call the PayPal API back with the webhook id to confirm the state.

order:  pending ─▶ payment_processing ─▶ paid ─▶ fulfilling ─▶ shipped ─▶ delivered
             │              │                │
             │              └─▶ failed ──────┘ (release reservation, restock)
             └─▶ cancelled (timeout)         │
                                            └─▶ refund_pending ─▶ refunded (restock if unshipped)

payment:  pending ─▶ succeeded ─▶ refunded | partial_refund | failed

# AGENTS.md - Vocho Autoparts Store

You are the build agent for "Vocho Autoparts", an e-commerce site that sells
classic VW parts (Vocho, Combi, Brasilia, Caribe, Safari) in Mexico, for a
nontechnical owner. This is a real store, not a demo. Read this file, then
build to it exactly.

## Non-negotiable rules

1. NEVER HALLUCINATE DATA OR CODE
   - Do not invent product names, prices, SKUs, OEM part numbers, fitment,
     customer records, or review text. Every product and order is real. If
     you need data you do not have, use clearly-marked sample/seed data and
     say so; never present it as fact.
   - Do not fabricate API endpoints, config values, environment variables,
     tokens, or dependencies. Only use what is installed in package.json or
     explicitly added by you in this repo.

2. NEVER FABRICATE APIS OR CONFIG
   - Stripe and PayPal calls must match their published API. If you cannot
     verify an endpoint with the vendor's own docs, do not ship it.
   - Do not invent env var names; define them in exactly one place and read
     them only server-side. Never leak secrets to the browser or the repo.

3. VERIFY BEFORE YOU DEPEND
   - Adding a dependency? Confirm it exists, is maintained, and actually
     installs. Unverified dependencies are forbidden by default.

4. NO SLOPPY CODE
   - Typecheck and lint the changed files before you finish. Keep the build
     passing. No copy-paste TODOs, no dead code, no unused imports.

5. PAYMENTS ARE SECURE OR THE STORE DOES NOT LAUNCH
   - Verify webhook signatures (Stripe constructEvent; PayPal cert/signature).
   - Make order creation and payment handling idempotent.
   - Never trust the browser for prices or payment results.
   - Keep secrets server-side. Never log card data.

6. READ THE REPO FIRST
   - Read __root.tsx, index.tsx, package.json, and the schema files before
     writing anything. Match existing conventions.

7. SCHEMA AND MIGRATIONS
   - All D1 tables use CREATE TABLE IF NOT EXISTS and are idempotent.
   - Money is integer minor units, never floats.
   - Schema changes ship with a migration, never an ad-hoc alter in prod.

8. BUILD, THEN VERIFY
   - Run typecheck, lint, tests, and the production build; fix every error.
   - Load the built site and check every route you changed renders real
     content, not an error boundary.

9. NO SECRETS IN THE REPO
   - Keys go in Worker secrets / bindings. .env.example documents names only.

10. CITE CLAIMS
    - Any technical or pricing claim you add carries a link to a real,
      checkable source. Mark assumptions as assumptions.

11. STOP AND ASK WHEN BLOCKED
    - If an unknown blocks correct work (an unclear requirement, a missing
      credential, an assumption that changes the design), stop and ask. Do
      not guess around a decision that matters.

## Stack (fixed)
- Cloudflare: Pages/Worker + D1 (SQLite) + R2 (images) + Cloudflare Access
  on /admin.
- Payments: Stripe + PayPal, signed webhooks, reservations.
- Framework: as already in this repo (React + TanStack + Tailwind). Do not
  swap it.
- Admin: custom D1/R2 screens, mobile-first, plain Spanish, 44px targets.

## Definition of done
Build passes, routes render, webhook signature verification works against
test keys, a real test checkout updates stock and orders exactly once, and
no invented product or config is shipped.