Workspaces, members and invites
51 files3 packages1 dependency
This pack adds workspaces to your API as JSON endpoints, so your users can work together with their team in shared spaces.
- Workspaces with members and roles, powered by the Permissions package.
- A personal workspace for every new user, created at signup.
- Users can belong to as many workspaces as they need.
- Every route and query scoped to the current workspace.
- Email invites. New users accept them by signing up, and existing users by signing in.
- Member management. Owners can change roles and remove members, and any member can leave.
- Workspace settings, where owners can rename the workspace.
Depends on Auth
This pack builds on the Auth pack's User model, login, signup and email setup, so apply the Auth pack first.
Apply the workspaces pack with Flow. Start a new session in your selected coding agent and execute the following slash command inside it.
$ npx @adonisplus/flow apply --pack=workspaces --agent=claude
$ npx @adonisplus/flow apply --pack=workspaces --agent=codex
$ npx @adonisplus/flow apply --pack=workspaces --agent=cursor
$ npx @adonisplus/flow apply --pack=workspaces --agent=opencode
After applying, Flow will make the following changes to your app.
- Find the guard your app uses to log users in: access tokens or sessions.
- Add an endpoint that tells your frontend which workspace to open after login: the first one the user joined.
- Install the packages the pack needs.
- Add the workspace tables, models and roles, and the authorization checks that decide who can do what.
- Add the workspace, member and invite endpoints, plus the invite email.
- Create a personal workspace at signup, and let users accept an invite after they sign up or log in.
- Run the tests, call each endpoint, and give you a brief your frontend can build against.
Delta will differ
Flow adapts the pack to your app, so the exact set of created and edited files depends on what you already have and which guard you authenticate with. This is the shape of an apply onto the API starter kit with the auth pack in place.
Permissions
permissions.tsstart/permissions.tsDefines the workspace, member and invite permissions.createdpermissions.tstypes/permissions.tsThe type of a permission key.createdworkspace-context.md.flow/custom/docs/workspace-context.mdTells your coding agent what the workspace middleware loads.created
Migrations
xxxx_create_workspaces_table.tsdatabase/migrations/xxxx_create_workspaces_table.tsCreates theworkspacestable.createdxxxx_create_memberships_table.tsdatabase/migrations/xxxx_create_memberships_table.tsCreates themembershipstable.createdxxxx_create_roles_table.tsdatabase/migrations/xxxx_create_roles_table.tsCreates therolestable.createdxxxx_create_membership_roles_table.tsdatabase/migrations/xxxx_create_membership_roles_table.tsCreates themembership_rolestable.createdxxxx_create_invitations_table.tsdatabase/migrations/xxxx_create_invitations_table.tsCreates theinvitationstable.createdschema_rules.tsdatabase/schema_rules.tsTypes a role's permissions as a list of keys.edited
Models & seeder
workspace.tsapp/models/workspace.tsAdds invites, and makes sure every workspace keeps an owner.createdmembership.tsapp/models/membership.tsA user in a workspace, with their roles.createdrole.tsapp/models/role.tsA role with its permissions.createduser.tsapp/models/user.tsAdds the memberships and the workspace queries.editedrole_seeder.tsdatabase/seeders/role_seeder.tsCreates the owner and member roles.created
Transformers
workspace_transformer.tsapp/transformers/workspace_transformer.tsSerializes a workspace.createdmember_transformer.tsapp/transformers/member_transformer.tsSerializes a member, with the actions the signed-in user can take on them.createdinvitation_transformer.tsapp/transformers/invitation_transformer.tsSerializes a pending invite.createdrole_transformer.tsapp/transformers/role_transformer.tsSerializes a role.created
Policy & validators
member_policy.tsapp/policies/member_policy.tsDecides who can change a membership, remove a member or leave.createdworkspace.tsapp/validators/workspace.tsValidates the create and rename forms.createdmember.tsapp/validators/member.tsValidates a role change.createduser.tsapp/validators/user.tsAdds the invite field to login and signup, and the invite validator.editedinvitation_roles_missing_exception.tsapp/exceptions/invitation_roles_missing_exception.tsRaised when an invite names a role that no longer exists.created
Middleware
workspace_middleware.tsapp/middleware/workspace_middleware.tsLoads the workspace and the signed-in user's membership.createdinitialize_bouncer_middleware.tsapp/middleware/initialize_bouncer_middleware.tsChecks permissions against the user's membership.createdauthorize_middleware.tsapp/middleware/authorize_middleware.tsRejects a request when the user lacks the route's permission.created
Controllers
landing_workspace_controller.tsapp/controllers/landing_workspace_controller.tsReturns the workspace the user joined first.createdworkspaces_controller.tsapp/controllers/workspaces_controller.tsLists, creates, shows and renames workspaces.createdmembers_controller.tsapp/controllers/members_controller.tsLists members, changes their role and removes them.createdmembership_controller.tsapp/controllers/membership_controller.tsLets the signed-in user leave the workspace.createdinvitations_controller.tsapp/controllers/invitations_controller.tsSends, resends and revokes invites.createdinvites_controller.tsapp/controllers/invites_controller.tsShows an invite and accepts it.createdroles_controller.tsapp/controllers/roles_controller.tsLists the roles.creatednew_account_controller.tsapp/controllers/new_account_controller.tsCreates the personal workspace, and skips verification for an invited email.edited
Mailer & email template
invitation_provision.tsapp/mails/invitation_provision.tsThe invite email.createdinvitation.edgeresources/views/emails/invitation.edgeThe body of the invite email.created
Routes
routes.tsstart/routes.tsAdds the workspace, member and invite routes.edited
Tests
bootstrap.tstests/bootstrap.tsSeeds the roles before the tests.editeduser_factory.tsdatabase/factories/user_factory.tsGives each user a personal workspace.editedworkspaces.tstests/helpers/workspaces.tsHelpers to add members and invites.createdlogin.spec.tstests/functional/auth/login.spec.tsLogin lands the user in a workspace.editedsignup.spec.tstests/functional/auth/signup.spec.tsSignup creates a personal workspace.editedemail_verification.spec.tstests/functional/auth/email_verification.spec.tsEmail verification lands the user in a workspace.editedcreate.spec.tstests/functional/workspaces/create.spec.tsCreating a workspace, with and without invites.createdgeneral.spec.tstests/functional/workspaces/general.spec.tsRenaming a workspace.createdmembers.spec.tstests/functional/workspaces/members.spec.tsChanging roles, removing members and leaving.createdinvitations.spec.tstests/functional/workspaces/invitations.spec.tsSending, resending and revoking invites.createdaccept.spec.tstests/functional/workspaces/accept.spec.tsAccepting an invite, and links that have stopped working.createdaccept_guest.spec.tstests/functional/workspaces/accept_guest.spec.tsSigning up and logging in through an invite.createdaccess.spec.tstests/functional/workspaces/access.spec.tsNon-members, and members without the required permission.createdswitcher.spec.tstests/functional/workspaces/switcher.spec.tsListing workspaces and the landing endpoint.created
Configuration
Section titled "Configuration"The withInvitations() mixin on the Workspace model stores the invites. Every option is optional.
expiresInstring | number7 days.tablestringinvitations.withInvitations<{ roleIds: number[] }>({ expiresIn: '3 days' })Owner and member roles
Section titled "Owner and member roles"The pack ships with two roles, owner and member. Owners can rename the workspace, manage members and send invites. Members can use the workspace and leave it. You can add as many roles and permissions as your app needs.
To add a permission, define it in start/permissions.ts and check it in your code with Bouncer. See Bouncer integration.
export const permissions = definePermissions({
workspace: {
update: 'Rename the workspace',
delete: 'Delete the workspace',
},
})To add a role or change a role's permissions, edit the role seeder and run it again. The roles endpoint lists every role in the table. See Managing roles and Defining permissions.
await Role.updateOrCreateMany('name', [
{ name: 'owner', permissions: [, /* ... */ 'workspace.delete'] },
{ name: 'member', permissions: [] },
{ name: 'billing', permissions: ['invitation.view'] },
])Every user gets a personal workspace
Section titled "Every user gets a personal workspace"Signup creates a workspace named after the user's first name, or after their email if they didn't give a name. A user who leaves their last workspace gets a new personal one.
Only members can open a workspace
Section titled "Only members can open a workspace"Workspace endpoints live under /w/<slug>. Anyone who isn't a member of the workspace gets a 404. The slug is generated from the name when the workspace is created, and renaming the workspace doesn't change it, so existing links keep working.
The landing endpoint returns the first workspace
Section titled "The landing endpoint returns the first workspace"After login, your frontend asks the landing endpoint which workspace to open. It returns the first workspace the user joined. If the user has no workspace left, they get a new one.
A workspace always keeps an owner
Section titled "A workspace always keeps an owner"The last owner can't leave the workspace or lose the owner role. If two owners try to leave at the same moment, only one of them succeeds. The members response tells your frontend whether each member can leave, so it can hide the leave button.
Members can't change their own role
Section titled "Members can't change their own role"A request to change your own role or remove yourself gets a 403. To leave a workspace, a member calls the leave endpoint.
Invite links only work for the invited email
Section titled "Invite links only work for the invited email"A wrong, expired or revoked invite token gets a 404, and so does a signed-in user with a different email. Resending an invite creates a new link and invalidates the old one. If the invite went out less than a minute ago, resending it doesn't send another email.
Invited users skip email verification
Section titled "Invited users skip email verification"Opening the invite link already proves the user owns the email address, so signing up through it doesn't send a verification email.
Added in Flow 1.1.0.