team

package
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: AGPL-3.0 Imports: 27 Imported by: 0

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

View Source
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.

View Source
const DefaultInviteDays = 7

DefaultInviteDays is how long an invitation link works unless the inviter picks another expiry.

Variables

This section is empty.

Functions

func Register

func Register(h huma.API, s *Service)

Register adds the team operations.

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

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

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

Invite creates one invitation per email, then emails them through the System stream. Without a System provider the links are returned instead.

Link returns the link of a pending invitation (the emailed link stays valid).

func (*Service) List

List returns the members of the workspace.

func (*Service) Options

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

Resend emails a pending invitation again and restarts its expiry.

func (*Service) Revoke

func (s *Service) Revoke(ctx context.Context, ws *store.Workspace, id uuid.UUID) error

Revoke cancels a pending invitation; its link stops working.

func (*Service) SignOut

func (s *Service) SignOut(ctx context.Context, ws *store.Workspace, p *authz.Principal, memberID uuid.UUID) (TeamSignOutResult, error)

SignOut ends every session of the member.

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"`
	// Language is the invitation email's and the page's; the instance
	// default when omitted. Once they sign in, members pick their own.
	Language string `json:"language,omitempty" enum:"en,vi"`
}

TeamInviteInput creates invitations.

type TeamInviteLink struct {
	Link      string    `json:"link"`
	ExpiresAt time.Time `json:"expiresAt"`
}

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"`
	// Languages an invitation can be written in, and the instance default
	// the dialog starts on.
	Languages       []applang.LanguageOption `json:"languages,omitempty"`
	DefaultLanguage string                   `json:"defaultLanguage,omitempty" example:"en"`
}

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 ("None. This role can't create API keys.").
	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 ("Your role can't invite people…").
	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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL