Client reference
TeamsClient methods in the current development API.
Import TeamsClient from @clipin/convex-teams and pass the generated components.teams reference. These methods run inside host Convex functions.
The API targets the first stable version, 1.0.0. See the typed client source for exact argument types.
Queries
| Method | Arguments after ctx | Purpose |
|---|---|---|
listTeams | userId, paginationOpts | Page through accessible teams. |
getTeamState | teamPublicId | Trusted host lookup of live metadata. Does not grant resource access. |
getTeamBySlug | userId, teamSlug | Read an accessible team. |
getActiveTeam | userId | Resolve the active preference. |
getDefaultTeam | userId | Resolve the default preference. |
listMembers | userId, teamSlug, paginationOpts | Page through team members. |
listPendingInvites | userId, teamSlug, paginationOpts | Page through pending invitations. Requires owner or admin. |
Trusted migration mutations
These methods are for internal migration jobs. They do not authenticate a caller. Keep them behind trusted host functions and freeze membership writes until cutover. See Host responsibilities.
| Method | Purpose |
|---|---|
importTeam(ctx, args) | Preserve a public ID and create the owner. Returns the component team ID and open or complete. |
importMembers(ctx, args) | Import 1 to 100 memberships per batch. Reject role conflicts. |
finishImport(ctx, teamPublicId) | Verify ownership and the expected count, then close the import. |
Workspace mutations
| Method | Purpose |
|---|---|
createTeam(ctx, userId, teamName) | Create a workspace with the actor as owner. |
prepareMembershipCount(ctx, userId, teamSlug) | Prepare older records in bounded batches. Owner-only. Returns counting or ready. |
ensurePersonalTeam(ctx, args) | Find or create the actor's personal workspace. |
setActiveTeam(ctx, userId, teamSlug) | Select an accessible workspace. |
setDefaultTeam(ctx, userId, teamId) | Set the default preference. |
updateTeamProfile(ctx, args) | Update the workspace profile. |
updateMemberRole(ctx, args) | Explicitly change a non-owner role. |
transferOwnership(ctx, args) | Atomically transfer ownership to an existing member. |
addMember(ctx, args) | Grant membership through trusted provisioning. |
removeMember(ctx, args) | Remove a non-owner member. |
leaveTeam(ctx, userId, teamSlug) | Leave as a non-owner member. |
deleteTeam(ctx, userId, teamPublicId) | Deny access and schedule bounded cleanup. |
Invitation methods
| Method | Purpose |
|---|---|
createInvite(ctx, args) | Issue an invitation scoped to the team. |
resendInvite(ctx, userId, inviteId) | Rotate a token and return the current invitation ID. |
revokeInvite(ctx, userId, inviteId) | Revoke an invitation. |
acceptInvite(ctx, args) | Accept and grant membership in one transaction. |
recordDeliveryAttempt(ctx, args) | Record safe delivery metadata. |
pruneInvitations(ctx, limit?) | Run bounded retention maintenance. |
Package exports
| Export | Purpose |
|---|---|
@clipin/convex-teams | Client and public types. |
@clipin/convex-teams/convex.config.js | Component configuration to mount in the host. |
@clipin/convex-teams/types | Public result types. |
@clipin/convex-teams/test | Register teams and its invite child with convex-test. |
The scoped package includes these exports. See the installation guide and current release status.