Documentation
¶
Overview ¶
Package team manages the people of a workspace (A5 §3.5, §5.8): members, invitations, role and scope changes, deactivation and removal. The last Owner can't be removed or demoted, and nobody can grant a permission they don't hold.
Index ¶
- Constants
- func Register(h huma.API, s *Service)
- type InvitationPathInput
- type ListFilter
- type MemberPathInput
- type Service
- func (s *Service) Bulk(ctx context.Context, ws *store.Workspace, p *authz.Principal, in TeamBulkInput) (TeamBulkResult, error)
- func (s *Service) ChangeRole(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) error
- func (s *Service) Deactivate(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (TeamDeactivateResult, error)
- func (s *Service) Get(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (TeamMemberDetail, error)
- func (s *Service) Invitations(ctx context.Context, ws *store.Workspace, p *authz.Principal) (TeamInvitationList, error)
- func (s *Service) Invite(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (TeamInviteResult, error)
- func (s *Service) Link(ctx context.Context, ws *store.Workspace, id uuid.UUID) (TeamInviteLink, error)
- func (s *Service) List(ctx context.Context, ws *store.Workspace, p *authz.Principal, f ListFilter) (TeamMemberList, error)
- func (s *Service) Options(ctx context.Context, ws *store.Workspace, p *authz.Principal) (TeamInviteOptions, error)
- func (s *Service) Reactivate(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) error
- func (s *Service) Remove(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) error
- func (s *Service) Resend(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (TeamResendResult, error)
- func (s *Service) Revoke(ctx context.Context, ws *store.Workspace, id uuid.UUID) error
- func (s *Service) SignOut(ctx context.Context, ws *store.Workspace, p *authz.Principal, ...) (TeamSignOutResult, error)
- type TeamBulkInput
- type TeamBulkResult
- type TeamCounts
- type TeamCreatedInvitation
- type TeamDeactivateInput
- type TeamDeactivateResult
- type TeamEffectivePermission
- type TeamInvitation
- type TeamInvitationList
- type TeamInviteInput
- type TeamInviteLink
- type TeamInviteOptions
- type TeamInviteResult
- type TeamInviteRole
- type TeamJITHint
- type TeamMember
- type TeamMemberAPIKey
- type TeamMemberActivity
- type TeamMemberApproval
- type TeamMemberChangeInput
- type TeamMemberDetail
- type TeamMemberList
- type TeamResendResult
- type TeamRoleRef
- type TeamSignOutResult
Constants ¶
const CodeNoSystemProvider = "no_system_provider"
CodeNoSystemProvider marks invite emails that couldn't be sent because no provider is assigned to the System stream; the response carries the links.
const DefaultInviteDays = 7
DefaultInviteDays is how long an invitation link works unless the inviter picks another expiry.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type InvitationPathInput ¶
type InvitationPathInput struct {
api.WorkspaceInput
InvitationID string `path:"invitationId" format:"uuid"`
}
InvitationPathInput is a path or query input shared by several operations.
type ListFilter ¶
type ListFilter struct {
Query string
Role string // role id or key
Status string // active | deactivated
TwoFA string // on | off | idp | required
}
ListFilter narrows the members list.
type MemberPathInput ¶
type MemberPathInput struct {
api.WorkspaceInput
MemberID string `path:"memberId" format:"uuid"`
}
MemberPathInput is a path or query input shared by several operations.
type Service ¶
type Service struct {
Pool *pgxpool.Pool
Q *store.Queries
Audit *audit.Logger
Box *secrets.Box
// Mail sends invitations through the System stream; mailer.ErrNoSystemProvider
// switches to copyable links.
Mail mailer.Sender
// PublicURL returns the externally reachable base URL for invite links.
PublicURL func(context.Context) string
Now func() time.Time
}
func (*Service) Bulk ¶
func (s *Service) Bulk(ctx context.Context, ws *store.Workspace, p *authz.Principal, in TeamBulkInput) (TeamBulkResult, error)
Bulk changes roles, requires two-factor now or deactivates several members in one transaction: all of them or none.
func (*Service) ChangeRole ¶
func (s *Service) ChangeRole(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID, in TeamMemberChangeInput) error
ChangeRole gives a member another role and scope.
func (*Service) Deactivate ¶
func (s *Service) Deactivate(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID, in TeamDeactivateInput) (TeamDeactivateResult, error)
Deactivate keeps the member's history, signs them out everywhere and keeps or revokes the API keys they created.
func (*Service) Get ¶
func (s *Service) Get(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID) (TeamMemberDetail, error)
Get returns the member detail.
func (*Service) Invitations ¶
func (s *Service) Invitations(ctx context.Context, ws *store.Workspace, p *authz.Principal) (TeamInvitationList, error)
Invitations lists pending invitations.
func (*Service) Invite ¶
func (s *Service) Invite(ctx context.Context, ws *store.Workspace, p *authz.Principal, in TeamInviteInput) (TeamInviteResult, error)
Invite creates one invitation per email, then emails them through the System stream. Without a System provider the links are returned instead.
func (*Service) Link ¶
func (s *Service) Link(ctx context.Context, ws *store.Workspace, id uuid.UUID) (TeamInviteLink, error)
Link returns the link of a pending invitation (the emailed link stays valid).
func (*Service) List ¶
func (s *Service) List(ctx context.Context, ws *store.Workspace, p *authz.Principal, f ListFilter) (TeamMemberList, error)
List returns the members of the workspace.
func (*Service) Options ¶
func (s *Service) Options(ctx context.Context, ws *store.Workspace, p *authz.Principal) (TeamInviteOptions, error)
Options returns what the invite dialog needs.
func (*Service) Reactivate ¶
func (s *Service) Reactivate(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID) error
Reactivate restores a deactivated member. A deactivated account (instance level) needs an instance admin.
func (*Service) Remove ¶
func (s *Service) Remove(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID) error
Remove deletes the membership. The audit log keeps naming the person; the API keys they created in this workspace are revoked.
func (*Service) Resend ¶
func (s *Service) Resend(ctx context.Context, ws *store.Workspace, p *authz.Principal, id uuid.UUID) (TeamResendResult, error)
Resend emails a pending invitation again and restarts its expiry.
type TeamBulkInput ¶
type TeamBulkInput struct {
MemberIDs []string `json:"memberIds" minItems:"1" maxItems:"200"`
Action string `json:"action" enum:"change_role,require_2fa,deactivate"`
RoleID string `json:"roleId,omitempty" doc:"For change_role"`
RevokeKeys bool `json:"revokeKeys,omitempty" doc:"For deactivate"`
Reason string `json:"reason,omitempty" maxLength:"500"`
}
TeamBulkInput applies one action to several members.
type TeamBulkResult ¶
type TeamBulkResult struct {
Changed int `json:"changed"`
// Skipped names members already in the requested state.
Skipped []string `json:"skipped"`
}
TeamBulkResult reports how many members changed.
type TeamCounts ¶
type TeamCounts struct {
Members int `json:"members"`
Active int `json:"active"`
Deactivated int `json:"deactivated"`
Invited int `json:"invited"`
}
TeamCounts feeds "6 members · 1 invited".
type TeamCreatedInvitation ¶
type TeamCreatedInvitation struct {
ID string `json:"id"`
Email string `json:"email"`
// Link is the invitation URL. It is shown to the inviter so it can be
// shared when email isn't available.
Link string `json:"link"`
Emailed bool `json:"emailed"`
}
TeamCreatedInvitation is one created invitation with its link.
type TeamDeactivateInput ¶
type TeamDeactivateInput struct {
// RevokeKeys revokes the API keys and agents the member created; false keeps them working.
RevokeKeys bool `json:"revokeKeys,omitempty"`
Reason string `json:"reason,omitempty" maxLength:"500" doc:"Recorded in the audit log"`
}
TeamDeactivateInput deactivates a member.
type TeamDeactivateResult ¶
type TeamDeactivateResult struct {
SessionsRevoked int64 `json:"sessionsRevoked"`
KeysRevoked []string `json:"keysRevoked"`
}
TeamDeactivateResult says what happened.
type TeamEffectivePermission ¶
type TeamEffectivePermission struct {
Key string `json:"key"`
Group string `json:"group"`
Label string `json:"label"`
Sensitive bool `json:"sensitive"`
Granted bool `json:"granted"`
// Source is "Role · Content Writer", "SSO group mapping · Marketing" or "not granted".
Source string `json:"source"`
// IncludedBy is the permission that brings this one in ("campaigns:edit").
IncludedBy string `json:"includedBy,omitempty"`
// Scope is "all lists", a list label, or "" when not granted.
Scope string `json:"scope"`
}
TeamEffectivePermission is one row of the member detail's permission table.
type TeamInvitation ¶
type TeamInvitation struct {
ID string `json:"id"`
Email string `json:"email"`
Role TeamRoleRef `json:"role"`
Scope access.ScopeSummary `json:"scope"`
Message string `json:"message"`
InvitedBy string `json:"invitedBy"`
// SentVia is the provider that delivered the email ("Postmark"); empty
// when the invite was only shared as a link.
SentVia string `json:"sentVia"`
CreatedAt time.Time `json:"createdAt"`
LastSentAt *time.Time `json:"lastSentAt,omitempty"`
ExpiresAt time.Time `json:"expiresAt"`
Expired bool `json:"expired"`
}
TeamInvitation is a pending invitation.
type TeamInvitationList ¶
type TeamInvitationList struct {
Items []TeamInvitation `json:"items"`
// DefaultDays is the default expiry ("Links work for 7 days by default").
DefaultDays int `json:"defaultDays"`
// JIT describes SSO domains whose people can join on their own.
JIT []TeamJITHint `json:"jit"`
// CanInvite reflects team:invite (resend, copy link and revoke are hidden without it).
CanInvite bool `json:"canInvite"`
}
TeamInvitationList is the pending invitations card.
type TeamInviteInput ¶
type TeamInviteInput struct {
Emails []string `json:"emails" minItems:"1" maxItems:"50"`
RoleID string `json:"roleId" format:"uuid"`
Scope *access.ScopeRequest `json:"scope,omitempty"`
ExpiresInDays int `json:"expiresInDays,omitempty" minimum:"1" maximum:"30" doc:"Defaults to 7"`
Message string `json:"message,omitempty" maxLength:"1000"`
// SendEmail false only creates the links (the "copy links" fallback).
SendEmail *bool `json:"sendEmail,omitempty"`
}
TeamInviteInput creates invitations.
type TeamInviteLink ¶
TeamInviteLink is a copyable invitation link.
type TeamInviteOptions ¶
type TeamInviteOptions struct {
Workspace string `json:"workspace"`
Roles []TeamInviteRole `json:"roles"`
// DefaultRoleID is Editor when grantable, otherwise the broadest grantable role.
DefaultRoleID string `json:"defaultRoleId"`
Lists []access.ScopedList `json:"lists"`
SenderDomains []string `json:"senderDomains"`
JIT []TeamJITHint `json:"jit"`
// SystemProvider names the provider of the System stream ("Postmark").
// Empty when invitations can't be emailed yet; the dialog then offers links.
SystemProvider string `json:"systemProvider"`
CanEmail bool `json:"canEmail"`
DefaultDays int `json:"defaultDays"`
ExpiryOptions []int `json:"expiryOptions"`
// SignInSummary is "Invitees pick a password or continue with Google, Microsoft or GitHub."
SignInSummary string `json:"signInSummary"`
}
TeamInviteOptions feeds the invite dialog.
type TeamInviteResult ¶
type TeamInviteResult struct {
Invitations []TeamCreatedInvitation `json:"invitations"`
Emailed bool `json:"emailed"`
// Fallback is "no_system_provider" when email couldn't be sent.
Fallback string `json:"fallback,omitempty"`
SentVia string `json:"sentVia,omitempty"`
}
TeamInviteResult reports what was created and whether email went out.
type TeamInviteRole ¶
type TeamInviteRole struct {
ID string `json:"id"`
Key string `json:"key"`
Name string `json:"name"`
Builtin bool `json:"builtin"`
Sensitive bool `json:"sensitive" doc:"Holders need two-factor"`
// Grantable is false when the inviter doesn't hold every permission of
// the role (or it is the Owner role, which only a transfer gives).
Grantable bool `json:"grantable"`
Reason string `json:"reason,omitempty"`
// Hint is "Editors can send; two-factor becomes required (7-day grace)."
Hint string `json:"hint"`
}
TeamInviteRole is a role offered in the invite dialog.
type TeamJITHint ¶
type TeamJITHint struct {
Domain string `json:"domain"`
Provider string `json:"provider"`
Preset string `json:"preset"`
RoleName string `json:"roleName"`
}
TeamJITHint is "acme.io users can also join automatically with Google Workspace".
type TeamMember ¶
type TeamMember struct {
ID string `json:"id" doc:"Membership id"`
UserID string `json:"userId"`
Name string `json:"name"`
Email string `json:"email"`
AvatarColor string `json:"avatarColor"`
Role TeamRoleRef `json:"role"`
Scope access.ScopeSummary `json:"scope"`
// Notes follow the role: "instance admin", "break-glass".
Notes []string `json:"notes"`
SignIn []access.MemberSignInMethod `json:"signIn"`
TwoFA access.MemberTwoFA `json:"twoFA"`
LastActiveAt *time.Time `json:"lastActiveAt,omitempty"`
Status string `json:"status" enum:"active,deactivated"`
// Deactivated members of the instance (not only of this workspace).
AccountDeactivated bool `json:"accountDeactivated"`
DeactivatedAt *time.Time `json:"deactivatedAt,omitempty"`
JoinedAt time.Time `json:"joinedAt"`
// Source is where the membership came from: invite, sso_jit, sso_group, install, transfer, self.
Source string `json:"source"`
// You is true for the signed-in person.
You bool `json:"you"`
// LastOwner is true when this is the only active Owner.
LastOwner bool `json:"lastOwner"`
}
TeamMember is one row of the members list.
type TeamMemberAPIKey ¶
type TeamMemberAPIKey struct {
ID string `json:"id"`
Kind string `json:"kind" enum:"api_key,mcp_agent"`
Name string `json:"name"`
Masked string `json:"masked"`
Permissions []string `json:"permissions"`
// Scope is "Weekly Digest" or "all lists".
Scope string `json:"scope"`
Status string `json:"status" enum:"active,expired,revoked"`
LastUsedAt *time.Time `json:"lastUsedAt,omitempty"`
}
TeamMemberAPIKey is a key or agent the member created.
type TeamMemberActivity ¶
type TeamMemberActivity struct {
ID string `json:"id"`
OccurredAt time.Time `json:"occurredAt"`
Action string `json:"action"`
Target string `json:"target"`
Result string `json:"result" enum:"allowed,denied,error"`
Reason string `json:"reason,omitempty"`
}
TeamMemberActivity is one recent audit entry by the member.
type TeamMemberApproval ¶
type TeamMemberApproval struct {
Campaign string `json:"campaign"`
CampaignID string `json:"campaignId,omitempty"`
Status string `json:"status" doc:"approve, request_changes, reject (given) or the request status (requested)"`
At time.Time `json:"at"`
}
TeamMemberApproval is an approval the member gave or requested.
type TeamMemberChangeInput ¶
type TeamMemberChangeInput struct {
RoleID string `json:"roleId" format:"uuid"`
Scope *access.ScopeRequest `json:"scope,omitempty"`
}
TeamMemberChangeInput changes a member's role and scope.
type TeamMemberDetail ¶
type TeamMemberDetail struct {
Member TeamMember `json:"member"`
Permissions []TeamEffectivePermission `json:"permissions"`
Groups []string `json:"groups"`
APIKeys []TeamMemberAPIKey `json:"apiKeys"`
// KeysNote explains an empty list ("Creating API keys needs apikeys:manage…").
KeysNote string `json:"keysNote,omitempty"`
ApprovalsGiven []TeamMemberApproval `json:"approvalsGiven"`
ApprovalsRequested []TeamMemberApproval `json:"approvalsRequested"`
CanApprove bool `json:"canApprove"`
Sessions int64 `json:"sessions"`
// ScheduledCampaigns counts scheduled sends the member created (they keep their schedule).
ScheduledCampaigns int64 `json:"scheduledCampaigns"`
// SSODomain is the email domain used with SSO ("acme.io").
SSODomain string `json:"ssoDomain,omitempty"`
// SignInMethods is every way the member signs in, linked SSO and social
// identities included (the list shows only the primary ones).
SignInMethods []access.MemberSignInMethod `json:"signInMethods"`
Activity []TeamMemberActivity `json:"activity"`
CanManage bool `json:"canManage"`
// Helpers are members who hold team:manage.
Helpers []string `json:"helpers"`
}
TeamMemberDetail is the member page (A5 §5.8 member detail).
type TeamMemberList ¶
type TeamMemberList struct {
Items []TeamMember `json:"items"`
Counts TeamCounts `json:"counts"`
// Roles available in the role filter and the bulk role select.
Roles []TeamRoleRef `json:"roles"`
// CanInvite / CanManage reflect the caller's team:invite and team:manage.
CanInvite bool `json:"canInvite"`
CanManage bool `json:"canManage"`
// Reason explains read-only access ("Inviting needs the team:invite permission…").
Reason string `json:"reason,omitempty"`
// Helpers are members who hold team:manage.
Helpers []string `json:"helpers"`
}
TeamMemberList is the members list with the caller's abilities.
type TeamResendResult ¶
type TeamResendResult struct {
Emailed bool `json:"emailed"`
SentVia string `json:"sentVia,omitempty"`
Link string `json:"link"`
ExpiresAt time.Time `json:"expiresAt"`
Fallback string `json:"fallback,omitempty"`
}
TeamResendResult reports a resend.
type TeamRoleRef ¶
type TeamRoleRef struct {
ID string `json:"id"`
Key string `json:"key"`
Name string `json:"name"`
Builtin bool `json:"builtin"`
}
TeamRoleRef names a member's role.
type TeamSignOutResult ¶
type TeamSignOutResult struct {
SessionsRevoked int64 `json:"sessionsRevoked"`
}
TeamSignOutResult reports a forced sign-out.