# Pewpros Groups Feature Guide

## Overview

Groups let instructors sell team/organization access to courses. An organization buys a block of seats, gets a group, and can invite members who automatically get access to all linked courses.

**Key advantage over LifterLMS:** A single group can grant access to *multiple* courses (LifterLMS limits to one).

## How It Works

### 1. Creating a Group

**Admin UI:** Navigate to `/admin/groups` → New Group. Fields:
- **Name** / **Description** / **Slug** (auto-generated)
- **Total Seats** — max members allowed
- **Visibility** — `private` (invite only), `open` (join link), or `closed` (no new members)
- **Pricing Model** — `per_seat` (price × quantity) or `fixed_tier` (flat price includes N seats)
- **Stripe Price ID** — links to a Stripe Price for checkout

**Via API:** `POST /api/v1/groups` with Bearer token authentication.

**Via Stripe Purchase:** A customer buys group access at `/courses/:slug/group-purchase`, picks seat count, names the group, and completes Stripe Checkout. The webhook automatically creates the group, makes the purchaser `primary_admin`, and links the course(s).

### 2. Linking Courses to a Group

**Admin UI:** On the group show page (`/admin/groups/:id`), scroll to "Add Course" — it lists all courses not yet linked. Click "Add" to link one.

**Via Stripe:** The group purchase checkout passes `course_ids` in Stripe metadata. On successful payment, those courses are auto-linked.

**Note:** Only *courses* are linkable to groups. Events are not currently supported.

### 3. Roles & Permissions

Four roles with hierarchical permissions:

| Role | Manage Members | Manage Managers | Manage Info | Manage Seats | View Reports | Delete Group |
|------|:-:|:-:|:-:|:-:|:-:|:-:|
| **primary_admin** | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| **admin** | ✓ | ✓ | ✓ | ✓ | ✓ | |
| **leader** | ✓ | | ✓ | | ✓ | |
| **member** | | | | | | |

- The group creator (or Stripe purchaser) is always `primary_admin`
- `primary_admin` cannot be demoted
- Admins can change roles for leaders/members
- Leaders can invite/remove members but can't manage other leaders/admins

### 4. Inviting Members

Two invitation types:

**Email Invitations:**
- Admin enters one or more emails (comma/space/newline separated) → batch invitations sent
- Each invited person receives an email with an "Accept Invitation" link
- The invitation is locked to that email address — only the matching account can accept
- Pending email invitations count toward seat usage (reserving the seat)
- Default expiry: 7 days

**Open Invitations (Join Links):**
- Generate a shareable URL at `/groups/join/:token`
- Anyone with the link can join (no email matching)
- One active open invitation per group at a time
- Open invitations do NOT count toward seat usage (seats are consumed on accept)
- Default expiry: 1 year
- Can be disabled/re-enabled by toggling

### 5. Accepting an Invitation

When a user visits `/groups/join/:token`:
1. Token is looked up → shows error if not found, expired, or already used
2. For email invitations: logged-in user's email must match the invitation email
3. Checks if user is already a member → shows "Already a Member" if so
4. Checks seat availability → shows "Group Full" if no seats left
5. If everything checks out → shows group info + "Accept & Join" button
6. On accept: creates an active seat for the user with `member` role, redirects to leader dashboard

### 6. Stripe Group Purchase Flow

Route: `/courses/:slug/group-purchase`

1. User selects seat count (or picks a tier) and names the group
2. Creates a Stripe Checkout Session with metadata:
   - `purchase_type: "group"`
   - `group_name`, `group_seats`, `course_ids`
   - Supports both `payment` (one-time) and `subscription` modes
3. On successful payment (webhook `checkout.session.completed`):
   - Creates the group with specified seats
   - Adds purchaser as `primary_admin`
   - Links specified courses
   - Stores `stripe_subscription_id` if subscription mode

### 7. Group Leader Dashboard

Route: `/my/groups` (index) and `/my/groups/:slug` (manage)

Available to users with `primary_admin`, `admin`, or `leader` role.

**Index page** shows:
- All groups where user has leader+ role
- Member count / total seats with progress bar
- Linked course count, pending invitation count

**Show page** has tabbed sections:
- **Overview** — group details, visibility, join link management (generate/copy/disable)
- **Members** — list with role badges, role change dropdowns, remove buttons
- **Invitations** — send batch invitations via textarea, list pending with revoke buttons
- **Courses** — linked courses with status badges

### 8. REST API Endpoints

All endpoints require Bearer token authentication (`Authorization: Bearer <token>`).

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/v1/groups` | List user's groups |
| `POST` | `/api/v1/groups` | Create a group |
| `GET` | `/api/v1/groups/:id` | Get group details |
| `PATCH` | `/api/v1/groups/:id` | Update group |
| `DELETE` | `/api/v1/groups/:id` | Delete group |
| `POST` | `/api/v1/groups/:token/accept-invitation` | Accept invitation by token |
| `GET` | `/api/v1/groups/:group_id/members` | List members |
| `GET` | `/api/v1/groups/:group_id/members/:id` | Get member details |
| `PATCH` | `/api/v1/groups/:group_id/members/:id` | Change member role |
| `DELETE` | `/api/v1/groups/:group_id/members/:id` | Remove member |
| `GET` | `/api/v1/groups/:group_id/invitations` | List invitations |
| `POST` | `/api/v1/groups/:group_id/invitations` | Create invitation(s) |
| `DELETE` | `/api/v1/groups/:group_id/invitations/:id` | Revoke invitation |
| `GET` | `/api/v1/groups/:group_id/seats` | Get seat info (total/used/available) |
| `PUT` | `/api/v1/groups/:group_id/seats` | Update total seats |

### 9. Seat Counting Logic

- **Used seats** = active seats + pending *email* invitations (open invitations don't reserve seats)
- **Available seats** = total_seats - used_seats
- A group is "full" when available_seats <= 0
- Changing `total_seats` can be done by users with `manage_seats` permission

### 10. Key Files

| Area | Files |
|------|-------|
| Schema | `lib/pewpros/groups/group.ex`, `group_seat.ex`, `group_invitation.ex` |
| Context | `lib/pewpros/groups.ex` |
| Email | `lib/pewpros/emails/group_invitation_email.ex` |
| Worker | `lib/pewpros/workers/group_invitation_worker.ex` |
| Join Page | `lib/pewpros_web/live/group_live/join.ex` + `.html.heex` |
| Purchase | `lib/pewpros_web/live/group_live/purchase.ex` + `.html.heex` |
| Dashboard | `lib/pewpros_web/live/group_live/dashboard/{index,show}.ex` + `.html.heex` |
| API | `lib/pewpros_web/controllers/api/v1/group_{controller,member_controller,invitation_controller,seat_controller}.ex` |
| Admin | `lib/pewpros_web/live/admin/group_live/{show,form_component}.ex` |
| Auth Plug | `lib/pewpros_web/plugs/group_authorization.ex` |
| Billing | `lib/pewpros/billing.ex` (group checkout + webhook handler) |