Convex component for team workspaces with owner/admin/member roles, invitations, seat limits, ownership transfer, and workspace preferences.
npm install @clipin/convex-teamsTeams adds shared and personal workspaces to Convex applications. It manages team identity, owner/admin/member roles, invitations, seat limits, ownership transfer, and workspace preferences. A TeamsClient connects host functions to the component. The host supplies authenticated user identity and controls billing, message delivery, and access to application content.
@clipin/convex-teams mounts as a Convex component and exposes a TeamsClient that accepts host function contexts. It provides fixed owner, admin, and member roles with a role-permission matrix enforced at the component level. The host wraps component methods to control which operations authenticated users can call.
@clipin/convex-teams handles the full invitation lifecycle through its bundled convex-invite dependency, including tokens, expiry, resend, and revocation. On each acceptInvite or addMember call, the host passes the current seatLimit from its own configuration, and the component checks a stored membership count to reject grants that would exceed capacity. Pending invitations do not reserve seats, and concurrent grants contend on the team record to prevent oversubscription.
@clipin/convex-teams provides a transferOwnership method that updates the owner record and both membership roles in a single transaction. The former owner is automatically demoted to admin. Only the current owner can initiate a transfer, and personal team ownership cannot be transferred.
listTeams, listMembers, and listPendingInvites in @clipin/convex-teams all require paginationOpts and return page, isDone, and continueCursor following Convex pagination conventions. Each page accepts 1 to 100 rows, and the host should continue until isDone is true even after receiving an empty page. The convex-helpers pagination hook works directly with these responses for reactive UI.
@clipin/convex-teams version 1.0.0 requires Convex >=1.43.0 and <2.0.0. The host mounts only the teams component, which internally mounts convex-invite@0.1.1 as a child component. No separate installation of convex-invite is needed.
@clipin/convex-teams does not handle authentication, verified email checks, billing, or content permissions. The host application is responsible for deriving the actor from authentication and verifying the invitation recipient has a confirmed email before calling component methods. Component functions become internal references in the host, and host wrappers determine which operations clients can invoke.
@clipin/convex-teams uses a stored membership count on the team record rather than scanning all members to check capacity. Concurrent grant attempts contend on the same team record inside a Convex transaction, so only one can succeed when the final seat is available. Creation, grants, removal, and leave all update the count in the same transaction.
@clipin/convex-teams provides trusted import methods: importTeam preserves an existing public team ID and creates its owner, importMembers accepts batches of 1 to 100 memberships, and finishImport verifies ownership and expected count before closing the import. These methods are intended for internal migration jobs, not public user endpoints. Imported teams are active immediately, and the host is responsible for enforcing any migration freeze on consumer access.
Calling deleteTeam immediately marks the team deleted, which denies all access and invalidates invitation grants. Background cleanup removes memberships and repairs affected workspace preferences in batches of 50, giving each user a fallback workspace they can access or no workspace. A null redirect from preference lookup can be temporary while cleanup continues. The host must run its own content and subscription cleanup using the immutable teamPublicId as a reference, since @clipin/convex-teams does not delete host content or cancel subscriptions.