EasyBookFair

Book fair consignment platform. See docs/spec.md for the full design, docs/MANUAL.md for intended usage, and docs/CHANGELOG.md for what's shipped so far.

Status: v0.1.0 — Phases 1-5 of the build plan are done and working end-to-end: foundation (schema/ledger), admin catalog and allocation, Stripe Connect, and the org portal/storefront with four working ways to buy (a physical Stripe Terminal reader at the table (/admin/fairs/<id>/checkout), a public online storefront with same-day pickup at the fair (/fairs/<id>), a parent-funded student wallet a kid spends down independently (/fairs/<id>/wallet, schools only), and a "Charge $X in cash" button right on the checkout screen), all writing through the same channel-agnostic record_sale()/ledger core — plus settlement/close-out (payout statements, Stripe Transfer/Payment Link, reconciliation). Self-serve org and author onboarding, event requests, a marketing toolkit, and self-serve admin/org-staff invites have all shipped since, ahead of where the original build plan put them. Phase 6 is done too — lead-time-aware allocation checks and the restock_orders "reorder now" flow already existed from earlier allocation work, and QR labels (configurable label-sheet templates, batch-printed per fair at packing time) are now built as well. Only Phase 7 (multi-tenant SaaS, deliberately last) remains. See docs/spec.md's "Build plan" for the full phase list and docs/CHANGELOG.md for the complete history.

An org staff portal (/org) now exists too: an org requests a fair (with each buyer payment option explained before they choose it) instead of an admin creating one directly, and an admin reviews/approves it from /admin/fair-requests — approving copies the requested dates and payment choices into a real fairs row, sends the requester an email pointing them at their dashboard, and (if they asked for the in-person reader) sets an equipment rental fee that's netted against their payout. Payment options are enforced per fair (online/wallet/in-person can each be turned off), not just decorative — both the org portal and the fair's admin edit page show the actual buyer-facing links.

Org staff can now also run their own fair day-of, not just request and track it: /org/fairs/<id>/{checkout,pickup,wallets,sales} (migration 0046) mirror the admin equivalents exactly — same CheckoutClient, same Server Actions — because the underlying RPCs (record_cash_sale, spend_from_wallet, mark_checkout_picked_up, close_wallets_for_fair) now check app.can_operate_fair() (a platform admin, or an org member whose org owns that specific fair) instead of admin-only. A different org's staff, or a non-member, still gets rejected — both at the RPC layer and by requireFairStaff() (lib/auth.ts), the shared page/action gate both route trees call.

A live sales feed (/admin/fairs/<id>/sales, /org/fairs/<id>/sales) shows every completed sale for a fair — item, channel, price, timestamp — plus a running units/revenue total, refreshing every few seconds (polling getRecentSales(), diffed by row id rather than a sold_at cursor — two sales can land in the same instant, since record_cash_sale/spend_from_wallet insert one row per unit in a tight loop). No new schema or RLS needed — sales_select (migration 0005) already scoped this correctly for both admin and org staff.

The same action also computes a live payout estimate — close_fair()'s own formula (migration 0036: the credit balance of Org Payable 2000, minus the debit balance of A/R 1300, minus the fair's equipment rental fee), read straight from journal_entries/journal_lines rather than waiting for the fair to actually close. Verified against close_fair() directly (recorded a card and a cash sale, read the live estimate, closed the fair, confirmed settlements.net_payout matched exactly). Once a settlements row exists for the fair, the feed shows that locked-in figure instead and labels it "Final payout" rather than an estimate.

Org staff also get a marketing toolkit (/org/fairs/<id>/marketing, mirrored for admins at /admin/fairs/<id>/marketing — both routes render the same MarketingToolkitContent, gated by requireFairStaff(), the same admin-or-that-fair's-org-staff check used for checkout/pickup/ wallets/sales) for each fair — the storefront/wallet links with copy buttons, a QR code for each (qrcode package, rendered as a data: image, no external service), a printable one-page flyer (its own route, so window.print() prints only the flyer — same reasoning as the wallet donation receipt page), and ready-to-copy social-media/email text templated from the fair's real name, dates, and links. Linked from /org's "Share with buyers" column, and from the admin fairs list/edit/demo screens alongside the same buyer-facing links they already show.

Orgs can also request an author reading or book signing (event_requests, migration 0049) for a book already allocated to one of their fairs, from /org/events/request — mirrors the fair_requests review pattern exactly (org proposes, admin reviews at /admin/event-requests, no authenticated update policy). A composite foreign key ties (fair_id, catalog_item_id) straight to allocations, so a request for a book that isn't actually at that fair is rejected at the database level. The admin screen reverse-looks-up the author via author_submissions for display, but never auto-emails them — coordinating the actual event is a manual step for the admin. That lookup falls back to optional author_name/author_email/author_phone columns directly on catalog_items (migration 0051) for a book an admin added without an author submission, so there's still a contact on file to reach — those same three fields (plus a new phone on authors/author_submissions) are editable from the catalog item's create/edit forms and the author submission form respectively.

A catalog-only author like that has no real account and can't be "viewed as" the way /admin/organizations lets an admin preview any org — authors.user_id is a foreign key to auth.users, so a row can only exist for a real, already-invited account. /admin/authors (migration 0052) now lists these catalog-only contacts in a second section, "no account yet," with a "Create account & view as" button that invites them (same invite-or-find logic approveAuthorSubmission already used, extracted to lib/authors.ts) and drops the admin straight into /author as them. That invite only fires on this explicit click, never just from saving contact info on a catalog item. The author portal itself now also shows books linked only by catalog_items.author_email (not just real submissions), and a new RLS policy (sales_select_author_catalog) lets a genuinely logged-in author — not just an admin viewing as them — see sales for those books too.

A big batch pulling several later-phase pieces forward at once:

• Promotions/bundle discounts (/admin/fairs/<id>/promotions): percent-off or "any N for $X" bundle deals, scoped per fair, applied automatically — not buyer-chosen — across all four checkout paths (online, in-person, wallet, cash). See lib/promotions.ts. Each promotion has an Edit button, not just activate/deactivate/delete — reopens the same form, prefilled, as an update instead of a new row.

• Closing a fair (/admin/fairs/<id>/edit): a real, if deliberately scoped-down, close_fair() — computes payout (or amount owed) straight from the ledger, nets the equipment rental fee, and locks it. A button right there then actually moves the money: Send payout fires a Stripe Transfer to the org's Connect account (net payout owed to them), or Create payment link generates a one-time Stripe Payment Link and emails it to the org (net amount they owe the platform). Missing- inventory cost still isn't computed (no returns-recording feature exists to drive it).

• Wallet close-out donation notice: closing a fair's wallets now emails each parent with unspent balance a link to a printable/downloadable receipt (/fairs/<id>/wallet/receipt/<walletId>).

• A demo/training fair (/admin/demo), seeded and resettable, for clicking through catalog/allocation/checkout/storefront/wallet flows without touching real data.

• An onboarding tour in both /admin and /org — auto-shows once per browser, and stays reachable afterward from a "🎓 Take the tour" nav link.

• Author submissions (/author/submit, public, no login): authors submit books/merchandise with a suggested retail price (65% wholesale auto-calculated), plus a required front cover, back cover, and interior PDF for admin review (migrations 0047/0048 — NOT NULL at the schema level, not just required by the form); admin review at /admin/author-submissions shows both covers and a link to the interior PDF; approving invites the author to a real account and adds the item to the catalog using the front cover as its image. A minimal author portal (/author) shows submission status and, once approved, units sold/revenue.

• Organization signups (/join, public, no login; migration 0045): the organization-side equivalent — a school or org expresses interest with no account, admin review at , approving creates the real row, invites the contact to a real account, and adds them as org staff so lets them in immediately to request their first fair. Deliberately at , not under — the middleware gates every path behind an existing session, so a public, no-login form can't live there. The landing page () — a fundraising-focused page covering how it works, feature highlights, who it's for, and an FAQ — links to both this and author submissions, alongside admin/org staff sign-in.

Still ahead: Tap to Pay/Bluetooth-reader support (needs a native mobile companion app — not reachable from a browser), and missing-inventory cost as part of closing a fair (needs a real returns-recording feature first).

Stack

Next.js (App Router) + Supabase (Postgres, Auth, RLS). See docs/spec.md for the full architecture, including why business logic is split between Postgres (invariants like ledger balance) and application/Edge Function code (everything that needs to be unit-tested).

Local setup

1. Install dependencies:

   npm install
   

2. Point the app at a Supabase project — copy .env.example to .env.local and fill in the values from your project's API settings.
3. Apply the schema — either via the Supabase CLI against that project (supabase db push), or by running the files in supabase/migrations/ against it directly, in order:
   • 0001_extensions_and_enums.sql
   • 0002_core_tables.sql
   • 0003_ledger.sql
   • 0004_seed_chart_of_accounts.sql
   • 0005_rls.sql
   • 0006_stock_and_allocation.sql
   • 0007_seed_carton_specs.sql
   • 0008_catalog_image_uploads.sql
   • 0009_receive_stock.sql
   • 0010_checkout_and_record_sale.sql
   • 0011_catalog_item_dimensions.sql
   • 0012_deallocate_inventory.sql
   • 0013_restock_order_date.sql
   • 0014_fair_terminal_location.sql
   • 0015_organizations_is_school.sql
   • 0016_sale_channel_wallet.sql
   • 0017_wallet_liability_account.sql
   • 0018_student_wallets.sql
   • 0019_wallet_fundings.sql
   • 0020_record_sale_wallet_channel.sql
   • 0021_spend_from_wallet.sql
   • 0022_close_wallets_for_fair.sql
   • 0023_checkout_sessions_pickup.sql
   • 0024_fair_storefront_items.sql
   • 0025_public_fair_and_order_lookup.sql
   • 0026_fair_storefront_items_category.sql
   • 0027_checkout_sessions_by_email.sql
   • 0028_wallet_fundings_parent_email.sql
   • 0029_fair_payment_options.sql
   • 0030_fair_requests.sql
   • 0031_fair_public_info_payment_options.sql
   • 0032_fair_storefront_items_allow_online.sql
   • 0033_fair_requests_email.sql
   • 0034_fairs_equipment_rental_fee.sql
   • 0035_demo_fair.sql

Stripe setup

1. From your Stripe dashboard (test mode), grab the secret key (Developers → API keys) for STRIPE_SECRET_KEY, and the publishable key (same page) for NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY — the public storefront/wallet pages need it client-side for Stripe.js (Elements).
2. Create a webhook endpoint (Developers → Webhooks) pointing at <your-deployment-url>/api/webhooks/stripe, subscribed to at least account.updated, payment_intent.succeeded, checkout.session. completed, and transfer.reversed (the last two back settlement reconciliation — see step 9 below). Its signing secret is STRIPE_WEBHOOK_SECRET. Stripe can't reach localhost directly — use the Stripe CLI (stripe listen --forward-to localhost:3000/api/webhooks/stripe) for local dev, or test against a deployed URL.
3. Org onboarding: on /admin/organizations/<id>/edit, "Start Stripe onboarding" creates a Connect Express account and sends you to Stripe's hosted flow. charges_enabled/payouts_enabled only update once the account.updated webhook actually confirms them — not just from clicking through the link. If they still show "not enabled" after completing onboarding, click "Refresh from Stripe" on the same card — it fetches the account's live status directly from Stripe's API instead of waiting on the webhook, which is the fix when the webhook endpoint isn't reachable yet (not configured, wrong signing secret, or account.updated isn't in its subscribed events).
4. In-person checkout (physical reader): on a fair's Edit page (/admin/fairs/<id>/edit), the "Terminal setup" card creates a Stripe Terminal Location for that fair's venue, then registers a physical reader to it using the registration code shown on the reader's own screen. Only internet-connected readers work here — BBPOS WisePOS E or Stripe Reader S700. Bluetooth readers (BBPOS Chipper 2X BT, Stripe Reader M2) and Tap to Pay on iPhone/Android need Stripe's native iOS/Android Terminal SDKs, which this web app doesn't use — not reachable from a browser at all. Once a reader shows online, /admin/fairs/<id>/checkout builds a cart from that fair's allocated stock and charges it (or spends from a student wallet — see below).
5. Online storefront (/fairs/<id>, public, no login): buyers browse a fair's allocated stock (cover images, search, category filter, sort — a "↻ Refresh availability" button reloads the count in case someone else just bought the last copy) and check out with Stripe Elements as a guest. Paid orders are for pickup at the fair, not shipped; the confirmation page () shows an order code and a confirmation email is sent (see step 7). If a buyer loses both, looks orders up by the email given at checkout. Admins redeem orders at , which now shows the actual titles in the cart, not just a count.

Deploying

Also deployable to Vercel: import the repo, set the Production Branch (Project Settings → Git) to claude/new-session-dm851x since that's where this project's work lives, and add the variables from .env.example under Project Settings → Environment Variables — NEXT_PUBLIC_* ones (including NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY/NEXT_PUBLIC_TURNSTILE_SITE_KEY) can use the "Config" type, SUPABASE_SERVICE_ROLE_KEY/STRIPE_SECRET_KEY/ STRIPE_WEBHOOK_SECRET/RESEND_API_KEY/TURNSTILE_SECRET_KEY should stay "Secret". Every push to that branch triggers a new deployment automatically.

Set CRON_SECRET (any random string, e.g. openssl rand -hex 32) too — vercel.json registers a daily cron job (/api/cron/transition-fairs, moves a scheduled fair to active on its start date, then to return_window the morning after its end date; see "Fair status" in docs/MANUAL.md) that Vercel authenticates with this value. Vercel picks up vercel.json automatically on deploy; nothing else to configure. Without CRON_SECRET set, the job runs every day and gets a 401 every time — fairs just never auto-transition.

Set NEXT_PUBLIC_SITE_URL once you have a real domain (custom or Vercel's own) — siteUrl() (lib/email.ts) falls back sensibly without it, but an explicit value is the most reliable option. Without it, on a project with no production domain configured, links (email links, and the org marketing toolkit's storefront QR code) can fall all the way back to the current deployment's own unique URL (VERCEL_URL), which Vercel's Deployment Protection commonly puts behind a login wall — a buyer scanning that QR code would hit a Vercel login page instead of the storefront.

Also update Supabase's own Auth URL Configuration (Supabase dashboard → Authentication → URL Configuration) once you have a real domain — app/login/page.tsx's magic link passes emailRedirectTo: <your-domain>/auth/callback (app/auth/callback/route.ts), but Supabase only honors that override if it's listed under Redirect URLs; otherwise it silently falls back to the project's Site URL instead. If that fallback still points at localhost or an old preview domain (or if the Site URL itself is just the bare domain with no path), a magic link click lands on / with no session ever established — indistinguishable from "the sign-in link didn't work." Add <your-domain>/auth/callback and <your-domain>/auth/invite (plus both's http://localhost:3000 equivalents for local dev) to Redirect URLs, and set Site URL to your real production domain, whenever the domain changes. /auth/invite (app/auth/invite/page.tsx) is a second, separate callback used only by every admin-generated invite link (authors, org-signup approval, platform-admin/org-staff invites — anything created via inviteOrFindAccount, lib/accounts.ts) — it exists because inviteUserByEmail() always delivers its session as a URL fragment (#access_token=...), never as /auth/callback's ?code=..., so it needs its own client-side page to read that fragment instead of a server Route Handler (confirmed directly from Supabase's Auth Logs: an invite link's login_method is "implicit", while /login's own magic link is "pkce"). Both routes need to be allow-listed for invites and magic links to work at all.

Watch for a www vs. bare-domain mismatch — a real case that hit this exact failure mode: the site was reachable at both https://yourdomain.com and https://www.yourdomain.com, but only the bare domain was in Redirect URLs. emailRedirectTo is built from window.location.origin (app/login/page.tsx), so a visitor on the www version requests https://www.yourdomain.com/auth/callback — a different origin than the allowlisted one — and Supabase falls back to Site URL exactly as above. Either add both variants to Redirect URLs, or better, pick one canonical domain (Vercel → Project → Settings → Domains, set one as primary so the other 308-redirects to it) and make Site URL/Redirect URLs/NEXT_PUBLIC_SITE_URL all agree with it.

Design system

components/ui/ holds the shared primitives (Button, Input, Select, Textarea, Card, Badge, PageHeader, Field) — build new screens on top of these rather than raw Tailwind classes, so the app stays visually consistent as it grows. Colors, fonts, and radius are defined once in tailwind.config.ts (playful orange/purple palette, warm cream background, a rounded heading font loaded via next/font/google in app/layout.tsx). Badge's statusTone() helper maps the various status/type enum strings used across the schema to a consistent color meaning — reuse it rather than inventing new colors per page.

Known gaps

• lib/supabase/types.ts is still the Phase 1 placeholder — a couple of joined-column reads in the allocation/fairs pages use an as unknown as cast to work around it. Regenerate real types once a project exists (command's in that file) and those casts should come out.
• Order/wallet-funding confirmation emails (Resend, lib/email.ts) are best-effort — a delivery failure is only logged, never surfaced to the buyer or retried. If RESEND_API_KEY/EMAIL_FROM aren't set, sending throws and is caught the same way, so email is silently skipped rather than breaking checkout — the confirmation page and /fairs/<id>/orders lookup remain the reliable fallback either way.
• Available-to-sell checks (online checkout, wallet spending, in-person checkout) aren't row-locked the way allocate_inventory is — two carts finishing at the same instant for the last unit of an item could both pass. Fine for one checkout station/reader at a time in practice, not safe for high-concurrency simultaneous checkouts without adding real locking.
• No Tap to Pay or Bluetooth-reader (M2, Chipper) support — both need Stripe's native iOS/Android Terminal SDK, unreachable from a browser. Would need a separate native (or React Native) companion app talking to the same backend.
• platform_admins and org_members now have self-serve invite screens (/admin/platform-admins for a super admin adding another admin, /org/staff for an org admin adding their own staff — migration 0053), but there's still no removal flow for either — demoting is self-serve (re-invite or the per-row promote/demote button), fully taking away someone's access is still a manual delete against the database. The very first platform admin ever still needs one manual insert too (see "Local setup" above) — there's no bootstrap-free path for the account that doesn't exist yet to invite itself.
• close_fair() (migration 0036, extended by 0055) nets the equipment rental fee, cash-sale wholesale owed, and — now that /admin/fairs/<id>/returns exists to record quantity_returned — missing-inventory cost too: whatever was allocated but neither sold nor physically received back, billed at the item's current cost. Moving the money is a real button now (sendSettlementPayout/ createSettlementPaymentLink, app/admin/fairs/actions.ts), and both are reconciled: a Transfer is marked confirmed synchronously (it has no separate pending state), with transfer.reversed catching the rare later clawback; a Payment Link's payment_link_paid_at only ever gets set by the webhook event actually firing — if that event isn't subscribed on the Stripe webhook endpoint (see "Stripe setup" step 2), a paid link will sit showing "⏳ Awaiting payment" forever even though the org already paid. There's also no idempotency key on the Transfer/Price/Payment Link calls themselves — the disabled-once-sent button is the real guard against a double-send, not a network-level safeguard, which is fine at this app's one-admin-clicking-once scale.

Database notes

• app is a non-public schema holding RLS predicate helpers (app.is_platform_admin(), app.current_org_ids()) and the ledger posting function (app.post_journal_entry()). It's deliberately not exposed over the API (see supabase/config.toml) — call post_journal_entry only from trusted server-side code over a direct Postgres connection, never from the browser.
• Every ledger write should go through app.post_journal_entry(), which validates debits equal credits before writing anything. A deferred constraint trigger on journal_lines enforces the same invariant independently, in case something ever writes to that table directly.
• RLS is default-deny: tables with no policy for a given role/command (e.g. sales has no insert policy for authenticated) are intentionally locked down — those writes only happen via the service-role key from trusted server code (webhook handlers, close-fair logic), not this app's RLS-governed client.
• record_sale() is the channel-agnostic sale writer — one write path for cash, online/in_person (card), and wallet, branching only which account gets debited (A/R for cash, Stripe Clearing for card/online, the Buyer Wallet Liability account for a wallet spend — migration 0020) and whether an Org Payable margin line applies (cash doesn't get one). record_checkout_sale() wraps it to process an entire cart atomically from the webhook — a for update lock plus a status check on checkout_sessions is what actually makes a redelivered payment_intent.succeeded event safe to reprocess, not the webhook_events table alone (see the comment on record_checkout_sale in migration 0010 for the one gap that tradeoff leaves: a failed attempt needs manual reconciliation, not automatic retry).
• Student wallets (migrations 0016–0022) are a second, parallel money path: funding a wallet debits Stripe Clearing and credits Buyer Wallet Liability (1400) — money collected but not yet earned as revenue, same shape as a retail gift-card liability — while spend_from_wallet() relieves that liability the same way a sale relieves inventory. Overdraft protection is the table's own check (balance >= 0) constraint, not application logic: a spend that would overdraw aborts the whole call (every record_sale() in it included) rather than needing its own explicit balance check. Wallets are scoped to one fair, not carried across fairs/years, because unused balance becomes that fair's org payout at close-out () rather than the student's own credit for next time.