# Higgler.org — Full Reference for LLM Agents

> Caribbean digital marketplace combining themed e-commerce storefronts with a crypto wallet (CBC tokens on Hyperledger Besu / Quorum). Vendors create stores; customers fund wallets via Stripe and pay vendors with crypto or pay-with-card directly.

Site: https://higgler.org
API base: https://api.higgler.org (production), https://api-dev.higgler.org (dev)
Frontend repo: React 18 + Vite 6 + TypeScript 5 + Tailwind CSS 3 (dark theme default).
Backend repo: Fastify + MongoDB; generic CRUD via `common.js` plus domain modules (stripe, blockchain, order, upload, kyc, …).
Blockchain: Hyperledger Besu (Quorum), MoneyTransfer contract with 2% fee via FeeUtility.

---

## 1. Store themes

10 specialized themes drive layout, cart shape, and checkout flow.

| Theme | Shipping (Crawfty Couriers drop-ship) | Local delivery (Uber Direct) | Distinguishing features |
|---|---|---|---|
| food | No | Yes | Sizes, customizations, delivery / takeout / dine-in |
| retail | Yes | Yes | US drop-ship via Crawfty Couriers |
| default | Yes | Yes | Generic physical goods |
| events | No | Yes | Ticket types, add-ons, venue layout, gallery |
| hotel | No | No | Room types, amenities, calendar booking |
| services | No | No | GPS booking, calendar, travel/call-out fee |
| transportation | No | Yes | Rides + package delivery |
| rentals | No | Yes | Equipment / vehicles, pricing tiers, deposits |
| recreation | No | No | Activities at venue |
| digitalmedia | No | No | Watermarked samples, license management |

Theme is set per store on creation and drives `ThemeRenderer` (`src/components/store/themes/ThemeRenderer.tsx`).

---

## 2. URL taxonomy

### Customer-facing
- `/` — storefronts directory
- `/storefronts` — alias of `/`
- `/map` — geo-located store map
- `/store/{storeName}` — store landing page (theme-specific)
- `/store/{storeName}/products` — generic product grid
- `/store/{storeName}/categories` — category list
- `/store/{storeName}/category/{categoryId}` — products in category
- `/store/{storeName}/menu` — food theme menu
- `/store/{storeName}/events` — events theme listing
- `/store/{storeName}/calendar` — hotel theme availability
- `/store/{storeName}/venues` — hotel theme venues
- `/store/{storeName}/content` — digital media catalog
- `/store/{storeName}/about|contact|deals` — vendor CMS pages
- `/store/{storeName}/page/{slug}` — custom CMS page
- `/store/{storeName}/cart` — per-store cart
- `/store/{storeName}/checkout` — per-store checkout
- `/product/{id}` — single product
- `/checkout` — multi-store cart checkout
- `/payment/success?session_id=…` — Stripe redirect target
- `/wallet` — customer wallet dashboard, balance, transactions, fund button
- `/orders/{id}` — customer order receipt
- `/profile` — account settings
- `/profile/kyc` — KYC onboarding
- `/profile/messages` — messaging inbox

### Vendor-facing
- `/profile/vendor` — vendor dashboard
- `/profile/vendor/{storeSlug}` — single store admin
- `/profile/vendor/{storeSlug}/products` — product list
- `/profile/vendor/{storeSlug}/products/edit/{id}?theme={themeType}` — product edit
- `/profile/vendor/orders/{id}` — vendor order details

### Auth
- `/login` — OTP login (email or WhatsApp)
- `/devlogin` — email + authkey direct login (test only)

### Costco (platform-operated store)
- `/costco` — Costco storefront (drop-ship via Crawfty Couriers)
- `/costco/search` — Costco product search
- `/costco/product/{productId}` — Costco product detail
- `/costco/cart`, `/costco/checkout`

### NFTs
- `/nft/marketplace` — public marketplace
- `/nft/{id}` — NFT detail

---

## 3. Authentication

Two parallel mechanisms:

1. **OTP** (production users): email or WhatsApp delivers a 6-digit code → exchanged for an `authkey` token. Sent on every authenticated request as `authkey: <token>`.
2. **Dev login** (test only, `/devlogin`): email + authkey pair, no OTP. For test accounts under `support+*@byllkreate.com`.

Most routes also accept `Authorization: Bearer <token>` for compatibility.

```
POST /otp/login        body: { email | phone }       → sends OTP
POST /otp/verify       body: { email | phone, code } → { token, user }
```

---

## 4. Key API endpoints

### Storefronts (public)
```
GET  /blockchain/storefronts
GET  /blockchain/store/{storeName}
GET  /product?storeName={name}
GET  /product/{id}
```

### Wallet (auth)
```
GET  /blockchain/wallet                       # create wallet (idempotent)
GET  /blockchain/my-wallet                    # list user wallets
GET  /blockchain/balance/{address}            # CBC balance
POST /blockchain/transactions                 # transaction history
POST /blockchain/transfer-by-contact          # P2P transfer
```

### Orders (auth)
```
PUT  /order/create                            # create pending order
POST /order/pay                               # blockchain transfer + finalize
GET  /order                                   # list user orders
GET  /order/{id}                              # order detail (receipt)
```

### Stripe payments (auth)
```
POST /stripe/create-customer                  # auth
POST /stripe/create-price                     # auth + server-side bounds (1¢ … $10,000)
POST /stripe/create-checkout-session          # auth, requires priceId → returns hosted URL
POST /stripe/fund-wallet                      # auth, returns PaymentIntent
POST /stripe/confirm-wallet-funding           # auth, finalizes after PaymentIntent
GET  /stripe/funding-status/{paymentIntentId} # auth
POST /stripe/customer-portal                  # auth, billing self-service
POST /stripe/webhook                          # signature-verified, credits wallet on checkout.session.completed
```

### Logistics
```
POST /uber/delivery/create                    # local delivery (Jamaica)
POST /location/find-location                  # reverse-geocoding for delivery address
```

### Uploads
```
POST /upload                                  # multipart, returns { _id, files: [{ url: "/upload/<id>/public" }] }
GET  /upload/{id}/public                      # serve file (no auth)
```

Important: product fetches return `upload$upload` populated as raw upload documents (`{_id, path, mimeType}`), without `url`. Frontend hydrates by deriving `url = ${API_URL}/upload/${_id}/public`.

### Costco
```
GET  /costco/products                         # via VITE_COSTCO_API_KEY
```

---

## 5. AI agent purchase flow

```
1. POST /otp/login                          → OTP delivered to email
2. POST /otp/verify                         → { token }
3. GET  /blockchain/storefronts             → discover stores
4. GET  /blockchain/store/{storeName}       → product catalog
5. PUT  /order/create
   body: {
     "product$product": [{ _id, quantity, price, title }],
     "paymentMethod": "wallet" | "crypto",
     "account$account": { _id: <userId> },
     "sender$account":  { _id: <userId>, wallet: <addr> },
     "recipient$account": { _id: <storeId>, wallet: <vendorWallet> },
     "metadata": { items_subtotal, tax_amount, tip_amount, delivery_fee, travel_fee, total_paid, ... }
   }
6. If wallet has insufficient funds:
     POST /stripe/create-price          → returns priceId (server bounds amount $1–$10k)
     POST /stripe/create-checkout-session
       body: { priceId, quantity:1, successUrl, cancelUrl, metadata: { walletAddress, userId } }
       → { url: "https://checkout.stripe.com/..." }
   Redirect user; webhook credits wallet on checkout.session.completed.
7. POST /order/pay                          → on-chain MoneyTransfer (2% vendor-side fee)
8. GET  /order/{id}                         → receipt with metadata (financial breakdown)
```

Order metadata is the **single source of truth** for the financial breakdown:
- `items_subtotal` — sum of `price * quantity` for cart items
- `tax_amount`, `tax_label` — Jamaica GCT (15% / 10% / 25% / 0% per category)
- `tip_amount`, `delivery_fee`, `travel_fee` (call-out / on-site fee), `setup_fee`, `insurance_fee`
- `total_paid` — what the customer actually paid (drives wallet history + receipts)
- For rental "deposit + balance" flows: `deposit_amount`, `balance_due_later`, `final_payment_due`, `orderGroupId`, `groupRole`

---

## 6. Tax (Jamaica GCT)

Per-product `taxApplication`: `included` / `added` / `none`, plus `taxCategory`:
- `standard` — 15%
- `tourism` — 10%
- `standard_tourism` — 25%
- `telecom` — 25%
- `zero_rated` — 0%

For services with a travel/call-out fee, tax base = `(item.price + travelFee) * qty` so the math balances on the receipt.

---

## 7. Logistics

| Provider | Use | Triggered when |
|---|---|---|
| Uber Direct | Local delivery in Jamaica | Order metadata `delivery_fee > 0` AND theme supports local delivery |
| Crawfty Couriers | International freight (US → Jamaica) | Theme supports shipping (retail / default / Costco) AND shipping address provided |

Auto-dispatch on order create. Address from `MapPicker` (Leaflet) + `POST /location/find-location` reverse-geocoding.

---

## 8. Wallet model

- One wallet per user, created idempotently on first login.
- Address shape: 0x-prefixed Ethereum-style hex.
- Balance stored as CBC (Caribbean Blockchain Coin); displayed alongside USD.
- Funding paths:
  1. **Stripe-hosted Checkout** (default) — `/stripe/create-price` + `/stripe/create-checkout-session` → redirect → webhook credits wallet
  2. **PaymentIntent** (`/stripe/fund-wallet`) — for client-side Elements integration (not currently used)
- 2% MoneyTransfer fee deducted from the vendor's side, not the customer's.

---

## 9. KYC

- Customer-facing onboarding at `/profile/kyc`.
- Levels: `pending`, `submitted`, `under_review`, `approved`, `rejected`.
- Some store/product creation actions gated on `approved` status.

---

## 10. Messaging (vendor ↔ customer)

- Per-order thread, scoped by `(orderId, vendorId, customerId)`.
- Lives at `/profile/messages`; vendor sees inbox at `/profile/vendor/messages`.
- Optional SMS-on-receive via profile setting (`messaging.sms_on_receive`).
- Storefront pre-purchase widget lets customers ask before checkout (rate-limited to prevent spam).

---

## 11. Multi-store cart

`CartContext` keys cart entries by `storeId`. Each store gets its own checkout pass:
- Service type (food): delivery / takeout / dine-in
- Delivery address picker (Uber-eligible themes)
- Shipping address picker (Crawfty Couriers-eligible themes)
- Tip selector
- Tax line items per GCT category
- Final receipt grouped by store

---

## 12. Test accounts (dev only)

- `support+fulltest@byllkreate.com` — fresh user, no wallet, no KYC
- `support+vendor1@byllkreate.com` — vendor test account
- `support+buyer1@byllkreate.com` — customer test account
- `support+claudetest@byllkreate.com` — test automation
- Pattern `support+<anything>@byllkreate.com` — OTP delivered to shared support inbox.
- Test card: `4111 1111 1111 1111`, any future expiry, any 3-digit CVV.

---

## 13. Crawler guidance

- All public storefronts are crawlable (`robots.txt` allows `/`, `/store/*`, `/product/*`, `/nft/*`, `/costco/*`).
- Authenticated pages (`/profile`, `/wallet`, `/checkout`) and admin views (`/profile/vendor/*`) are not crawlable; they're served via JS-rendered React routes.
- Sitemap at `https://higgler.org/sitemap.xml`.
- Open Graph + JSON-LD `LocalBusiness` schema embedded on each storefront page.

---

## 14. Citation conventions

| Reference | URL pattern |
|---|---|
| Store | `https://higgler.org/store/{storeName}` |
| Product | `https://higgler.org/product/{id}` |
| Order receipt | `https://higgler.org/orders/{id}` (auth-gated) |
| NFT | `https://higgler.org/nft/{id}` |
| API endpoint | `https://api.higgler.org/{path}` |
| General | `https://higgler.org` |

Use the customer-facing `/store/{name}` URL (vs the API URL) when citing a vendor in human-facing output.