Timeshare Connect

Timeshare Connect is a Next.js + Supabase marketplace for owner-sourced resort stays. The core product idea is a staged, verified handoff: traveler request first, deposit second, owner booking and guest authorization third, proof review fourth, final payment last.

The platform also now captures staged legal acknowledgement at account access, listing publication, traveler request, and owner acceptance so there is a clear record that Timeshare Connect is the conduit only and that the underlying contract is between buyer and seller.

Start Here

If you are setting up or deploying this project, read these first:

• docs/RUNBOOK.md - local setup, env vars, SQL run order, troubleshooting.
• docs/SUPABASE_RUN_ORDER.md - exact SQL migration sequence for existing databases.
• docs/RELEASE_CHECKLIST.md - pre-deploy and post-deploy checks.
• docs/CHANGELOG_DEV.md - plain-language history of implemented changes.
• docs/PARKING_LOT.md - deferred items and future architecture decisions.
• docs/BETA_TESTER_GUIDE.md - script for testers and how to submit feedback.
• docs/PUBLISH_AND_SHARE_GUIDE.md - exact steps to publish and share beta builds.

Current Workflow

Traveler flow

1. Search listings and request a stay.
2. Wait for the owner to accept.
3. Pay the first 50% deposit to open the booking.
4. Wait while the owner books through their normal resort, HOA, club, or exchange channel.
5. Review transfer updates while the owner saves progress or submits proof.
6. Pay the final 50% only after transfer proof is verified.

Owner flow

1. Start from the dedicated owner onboarding path and create or access an owner account.
2. Save inventory templates with the booking channel you normally use, using the guided inventory wizard when you want a reusable setup.
3. Create a listing from AI or from a saved template, and explicitly choose the reservation transfer channel.
4. Accept a traveler request.
5. Wait for the traveler deposit before booking the stay.
6. For flexible inventory, enter the actual booked dates after you secure the reservation.
7. Save transfer progress if you are still waiting on proof or a guest certificate.
8. Submit confirmation details and proof for verification when the handoff is complete.

Verification rules

• Owners do not complete the handoff before the traveler deposit clears.
• Travelers do not complete final payment before proof is reviewed.
• Flexible traveler-requested dates are not treated as fully confirmed until the owner enters the booked dates.
• Transfer channels must be chosen explicitly for new inventory and listings so the booking workflow uses the right guidance.
• Rejected proof returns the booking to the owner with a refreshed deadline.

Legal acknowledgement rules

• Users must accept platform terms when signing in or signing up.
• Owners must acknowledge listing accuracy, transfer authority, and platform liability limits before publishing a listing.
• Travelers must acknowledge that a request starts a direct buyer-seller contract flow before submitting an offer.
• Owners must acknowledge direct delivery responsibility before accepting an offer into a booking.
• Acceptance timestamps and terms versions are stored in Supabase for profiles, listings, offers, and bookings.

Tech Stack

• Next.js App Router
• TypeScript
• Tailwind CSS
• Supabase auth, database, and storage
• Vercel for deployment

Core Product Areas

• Public browsing and search
• Dedicated owner onboarding and role-aware auth
• Owner inventory templates and listing creation
• Offer acceptance and staged booking flow
• Transfer workflow with channel playbooks and evidence uploads
• Admin verification and rejection handling
• Traveler trip tracking and staged payments

Current State

• Public home and owner acquisition flows have been updated so owners have a dedicated onboarding path instead of a traveler-only landing page.
• Auth now supports clearer owner/traveler intent selection, guided confirmation states, and social sign-in entry points.
• Terms and liability copy now has a dedicated public page plus enforced acceptance checkpoints across login, listing, request, and owner acceptance flows.
• Owner inventory has been simplified into a guided wizard with clearer transfer-channel guidance and earlier photo requirements.
• Owner workspace pages now share a more persistent navigation shell, and the dashboard doubles as a first-run owner home when no data exists yet.
• Supabase migration docs now include the newer messaging and transfer-workflow SQL files required by the current app.

Getting Started

Run the dev server:

npm run dev

Open http://localhost:3000.

Build for production:

npm run build

Important Routes

• app/page.tsx - public home page
• app/(public)/owners/page.tsx - dedicated owner onboarding landing page
• app/(public)/how-it-works/page.tsx - public workflow explanation
• app/(public)/terms/page.tsx - public platform terms and liability summary
• app/(auth)/login/page.tsx - traveler/owner auth entry with social sign-in and guided confirmation states
• app/(owner)/inventory/page.tsx - owner inventory templates
• app/(owner)/offers/page.tsx - owner request and booking queue
• app/(owner)/bookings/[bookingId]/page.tsx - owner/traveler booking timeline
• app/(traveler)/trips/page.tsx - traveler trip tracking
• app/(admin)/admin/page.tsx - admin booking review

Database Notes

The core workflow depends on these Supabase tables:

• profiles
• owner_inventory
• listings
• offers
• bookings
• transfer_channels
• booking_transfers
• booking_transfer_evidence
• booking_transfer_events

Run SQL in the order documented in docs/SUPABASE_RUN_ORDER.md.

Recent legal-tracking additions:

• supabase/legal_terms_liability_migration.sql adds staged legal acknowledgement columns.
• profiles stores account-level terms version and acceptance time.
• listings stores owner acknowledgement at publish time.
• offers stores traveler acknowledgement at request time.
• bookings stores owner acknowledgement at acceptance time.

Next Steps

1. Expand supabase/health_check.sql so it verifies the newer transfer-workflow tables, columns, and storage buckets directly.
2. Run a focused smoke test across the current production flow: owner onboarding, inventory creation, listing publish, offer acceptance, transfer proof submission, and traveler trip tracking.
3. Decide whether Google and Apple sign-in should remain enabled in the UI or be hidden until provider configuration is fully verified in Supabase Auth.
4. Continue tightening the owner first-run experience, especially around empty states on offers, bookings, and settings surfaces.