Memberships — Behavior

State machines

Membership status (memberships.status, enum membership_status)

MEMBERSHIP_ACTIVATED event fires whenever a row transitions into active from any other state (including the create-with-active path).

Membership role (membership_role)

owner > admin > coach > member. Service-level rules (in createInvitation / updateMembership):

• Only owners can invite or promote-to owners.
• Owners and admins can invite or promote-to admins.
• Coaches and members cannot invite anyone.
• Cannot demote the last owner to a non-owner role (single-owner protection).

Payment status (membership_payment_status)

none | current | past_due | debt. Set by the payments / subscriptions layer, not this module. Read here only on listMember responses.

Invariants

• UNIQUE(user_id, organization_id) — at most one membership per (user, org), regardless of status.
• Last-owner safety — updateMembership blocks demoting the last owner+active row, and blocks setting it to suspended or cancelled.
• Tier-aware invite — non-staff invites count against maxMembers; staff invites bypass.
• Activation event invariant — MEMBERSHIP_ACTIVATED is emitted exactly once per transition to active. (Consumers must be idempotent — webhook retries are possible.)
• Cache invalidation — requireMembership cache has 30s TTL. Direct membership writes don’t auto-invalidate; callers that mutate must call invalidateMembershipCache(orgId, userId) (TODO: verify whether updateMembership actually invokes it — appears not to in the read code).
• Invitation expiry — INVITE_EXPIRY_DAYS = 7. Checked only at accept time.
• Search across users + memberships — listMembers filters by ilike against users.first_name, users.last_name, users.email.

Golden paths

G1 — Owner invites a single member

1. POST /:orgId/invitations with {email, role:'member'}.
2. Service:
   • requireMembership check (owner/admin).
   • Role gating (cannot invite owner unless caller is owner).
   • Tier check (skip for staff roles).
   • Reject if existing membership in active/pending/invited state.
   • Reject if pending invitation already exists for this email in this org.
   • Call Clerk invitations.createInvitation (sends email).
   • INSERT invitations row.
   • INSERT memberships shell with status='pending_invitation' (creates shell user if needed).
3. Returns the invitation row.

G2 — New user accepts invitation

1. User clicks email, signs up at Clerk.
2. Webhook user.created lands at the API.
3. findOrCreateFromClerk either creates or links the user row.
4. acceptPendingInvitations(clerkId):
   • Find all invitations matching the user’s email (case-insensitive) with status='pending'.
   • For each: if expired, mark expired and continue. Otherwise transaction: if a membership row exists (pending_invitation), flip it to active. Else insert a fresh memberships row. Mark invitation accepted with accepted_at.
   • Emit MEMBERSHIP_ACTIVATED for each new activation.

G3 — Bulk invite imported members

1. Owner has 50 imported members with clerk_id=NULL. POST /:orgId/members/bulk-invite with their membershipIds.
2. Service fetches each (membership_id, user_id, role, email, clerk_id), and the org’s pending invitations.
3. For each: skip if clerk_id exists or pending invite exists (with reason strings). Otherwise call Clerk + INSERT invitations.
4. Returns {sent, skipped, failed, summary:{total, sent, skipped, failed}}.

G4 — Member self-stats

1. GET /:orgId/members/me/stats.
2. Service computes classesThisMonth and totalClasses by joining bookings → class_sessions → class_types → programs with programs.organization_id=orgId and bookings.membership_id=callerMembershipId.

G5 — Update role/status/profile

1. Owner PATCH /:orgId/members/:id with {role: 'coach'}.
2. Service: requireMembership (owner/admin); load target; if target is owner, run owner-protection guards.
3. Optional: if updates.profile present, call usersService.updateProfile(target.userId, updates.profile).
4. UPDATE the membership row.

Edge cases & error states

Side effects

Permissions

Members can list and get-by-id other members in the same org (e.g. for community feed UX). They cannot read or write profile/stats of others, and they cannot invite.