Groups API

Group creation, listing, detail, and join-code workflows.

Behavior summary

Group routes manage lifecycle and membership. Core rules:

Creator becomes OWNER automatically.
joinCode is 6-char uppercase alphanumeric.
Duplicate membership is blocked by DB uniqueness.
Group capacity is bounded by maxMembers.

Endpoints

Creates a group and adds the caller as owner in one transaction.

Body

{
  "name": "Roommates Premium",
  "maxMembers": 6
}

Validation

name: string, 1-100 chars
maxMembers: integer, 2-10 (default 6)

Success

Status: 201
Returns newly created group object

Failure cases

401 UNAUTHORIZED
400 VALIDATION_ERROR

Returns all groups where current user has membership.

Success

Status: 200
Array of groups (typically with role and membership metadata)

Failure cases

401 UNAUTHORIZED

Returns detail view for one group.

Includes

Group metadata
Member list
Subscription association (if selected)

Failure cases

401 UNAUTHORIZED
403 FORBIDDEN when caller is not a member
404 NOT_FOUND

Joins a group by invite code.

Body

{
  "code": "AB12CD"
}

Validation

code: fixed length 6

Failure cases

400 GROUP_FULL when maxMembers reached
409 ALREADY_MEMBER for duplicate joins
404 INVALID_JOIN_CODE

Transaction note

POST /api/groups must be atomic. If either group creation or owner membership insertion fails, no partial write should remain.