Trips and members

Goals

1. An organizer starts a trip and has everyone on it within a few minutes.
2. Each person sees exactly the trips they are on, and what their role lets them do there.
3. A trip never ends up without an organizer, and never shows itself to someone who is not on it.
4. Later features need only ask "what is this person's role on this trip?" to decide what to show.

Non-goals

• Creating accounts. Sign-up is closed (the API's TRAVEL_SIGNUP_OPEN=0); accounts still come from an admin's or an organization admin's invitation. A trip invitation to an address with no account waits until that person has one.
• The trip's contents: legs, days, bookings and photos are steps 2 to 5.

Roles on a trip

	Organizer	Co-planner	Traveler	Follower
See the trip and who is on it	yes	yes	yes	yes
See members' email addresses	yes	yes	no	no
Change the name, dates and description	yes	yes	no	no
Invite, remove, change roles	yes	no	no	no
Add a traveler without an account	yes	yes	no	no
Delete the trip	yes	no	no	no
Leave	yes, unless the last organizer	yes	yes	yes

• A trip can have several organizers; the last one can neither leave nor be demoted or removed. Making someone else organizer first is the way out.
• Roles here are separate from the site's ladder (customer, staff, admin, superadmin). A site admin has no trip role and sees no trips but their own.
• Followers are on the trip but not traveling: they will see the plan and the album, not documents or locations, when those exist.

Invitations

1. An organizer types an email address and picks a role. The address may or may not have a Travel account yet.
2. The invitation is a pending member of the trip: the organizer sees it in the member list as "invited", and can change its role or withdraw it.
3. The invited person sees it at the top of their Trips page, with who invited them and as what, and accepts or declines. Only the account with that email address can answer it.
4. Accepting makes them a member under their account's name. Declining removes the invitation; the organizer can invite again.

If no account exists for the address, the organizer is told so beside the button: the invitation is kept and will show once the person has an account, which an admin creates from the people pages.

Invitation notices

• A new invitation to an address with an account puts a notice in that person's bell and sends them an email, each saying who invited them, to which trip and as what, with a link to their Trips page. The email goes whether or not they turned on notification email: an invitation needs an answer, as a page invitation in Help does.
• An address with no account is sent nothing: they could not sign in to answer. The organizer sees the message above.
• The organizer is told what became of the email, beside the button, in the words the mailer's answer calls for: sent, on its way, held (this server's email is in test mode, so nobody receives it), not sent to an address that refuses mail, or could not be sent. Held mail is never called sent.
• Once the invitation is answered or withdrawn, its notice leaves the bell, so it never points at an invitation that is gone.
• An accepted invitation puts a notice in the bell of the organizer who sent it, linking to the trip, if they are still on it. It is mailed only as the notifications' own email copy, to an organizer who turned notification email on: an acceptance asks nothing of them, and a big trip would otherwise fill their inbox. Declining tells nobody.

Travelers without an account

Children, and some older relatives, have no email address (the main PRD's open question 2). They are still on the trip: on its segments, in its rooms, in its photos. So a planner adds them by name, and a member with an account becomes their guardian: the one who acts for them and, later, holds their documents. The person adding them is the guardian unless they pick another member.

They show on the trip as travelers, marked "no account". They cannot sign in. When such a person later gets an account, linking it is a later step; until then the guardian removes them and the person is invited normally.

This answers the main PRD's open question 2 for trips, provisionally; see Open questions.

Privacy

• A trip, its members and its invitations are visible only to its members and to the person invited. Anyone else asking for a trip gets 404, the same as for a trip that does not exist, so a trip's existence is not revealed.
• There is no staff or admin view of trips. A support case is answered by the organizer adding someone, not by anyone looking in.
• Your data: the account export lists the trips you are on with your role and their members' names, and the travelers you are guardian of. Deleting your account removes your memberships and your invitations, and the travelers you are guardian of. A trip you were the last organizer of passes to the longest-standing co-planner, then traveler, then follower; a trip with nobody else on it is deleted.

What was built

Piece	Where
Tables travel.trips, travel.trip_members	services/api/src/db/schema.ts, migration 0006_trips
API, every rule above	services/api/src/trips.ts, under /api/v1/trips
Invitation notices: bell and email for an invitation, bell for an acceptance	services/api/src/trips.ts (tellInvited, tellAccepted), on the site's notifications and mailer
Tests	services/api/test/trips.test.ts, services/api/test/trip-notices.test.ts
Pages: Trips (yours, your invitations, a new trip) and a trip's own page	apps/web/app/trips

The API, for the features that follow:

Route	Who
GET /api/v1/trips	your trips and the invitations waiting for you
POST /api/v1/trips	anyone signed in; they become its organizer
GET /api/v1/trips/:id	its members
PATCH /api/v1/trips/:id	organizers and co-planners
DELETE /api/v1/trips/:id	organizers
POST /api/v1/trips/:id/members	organizers invite (email, role); organizers and co-planners add a traveler without an account (name, optional guardianMemberId)
PATCH /api/v1/trips/:id/members/:memberId	organizers change a role
DELETE /api/v1/trips/:id/members/:memberId	organizers remove anyone; you remove yourself (leave), or a traveler you are guardian of
POST /api/v1/trips/invitations/:memberId/accept, .../decline	the invited account

Phasing

1. This draft: trips, members, invitations, roles, travelers without an account.
2. Mail and notices (built): an email and a bell notice for a new invitation, a bell notice for an accepted one, through the site's notifications.
3. Trip contents: the skeleton (step 2) and the days (step 3), each checking the trip role.
4. Linking an account to a traveler who was added by name, keeping their place on the trip.

Open questions

Answer each question in place; your answers are saved for everyone reading this page.