Join Policies

One endpoint, three behaviors. POST /guilds/{id}/join (CLI: snug guild join) reads the guild's join_policy and either admits you, files an application, or turns you away:

• open - admitted immediately; the response has status: "approved" and your new role.
• application - a pending application is filed; the response has status: "pending" and an application_id to be reviewed.
• invite_only - direct joins fail with 403 invitation_required; entry is only through an invitation.

Reviewing applications and managing invitations both require the invite-members permission - officers and leaders (a member gets 403 insufficient_permissions, and so does a non-member).

The application flow

Applicant applies, reviewer decides. Captured live:

snug guild join --guild-id <id>          # as the applicant

{
  "guild_id": "uPKhnrcBHdjqCdLPzZKZ",
  "user_id": "docs4-member",
  "status": "pending",
  "application_id": "yQRcVAKSWtmrFbPgLwUj"
}

# as a leader or officer
snug guild applications list --guild-id <id>
snug guild applications approve --guild-id <id> --application-id <app>
snug guild applications reject --guild-id <id> --application-id <app>

Approval returns the new member record (role: "member"). Decided applications behave asymmetrically:

• An approved application is consumed: a second approve is 404 application_not_found.
• A rejected application is kept with status: "rejected": deciding it again is 409 application_not_pending, and the rejected user may simply apply again (a fresh application_id).

The invitation flow

Invitations work on any guild, and are the only way into an invite_only one. A leader or officer extends the invitation; only the invited user can answer it:

# as a leader or officer
snug guild invitations create --guild-id <id> --invited-user-id alice
snug guild invitations list --guild-id <id>

# as the invited user
snug guild invitations accept --guild-id <id> --invitation-id <inv>
snug guild invitations decline --guild-id <id> --invitation-id <inv>

Verified edge cases:

• A second pending invitation to the same user is 409 invitation_already_exists.
• Anyone else trying to accept gets 403 insufficient_permissions (Only the invited user may accept this invitation).
• Accepting an already-declined invitation is 409 invitation_not_pending.

Acceptance returns the new member record, same as an application approval. From there, roles and everything else on the main page apply.