users

type EmailVerification struct {
	User      User
	Token     string
	CreatedAt time.Time
	ExpiresAt time.Time
}

type EmailVerificationRepository interface {
	// Save persists the EmailVerification.
	Save(ctx context.Context, verification EmailVerification) (string, error)

	// RetrieveByToken retrieves an EmailVerification based on its token.
	RetrieveByToken(ctx context.Context, token string) (EmailVerification, error)

	// Remove removes an EmailVerification from the database.
	Remove(ctx context.Context, token string) error
}

type Emailer interface {
	SendPasswordReset(To []string, redirectPath, token string) error
	SendEmailVerification(To []string, redirectPath, token string) error
	SendPlatformInvite(to []string, inv PlatformInvite, redirectPath string) error
}

type Hasher interface {
	// Hash generates the hashed string from plain-text.
	Hash(string) (string, error)

	// Compare compares plain-text version to the hashed one. An error should
	// indicate failed comparison.
	Compare(string, string) error
}

type Metadata map[string]any

type PageMetadata struct {
	Total    uint64
	Offset   uint64
	Limit    uint64
	Email    string
	Status   string
	Metadata Metadata
	Order    string
	Dir      string
}

type PageMetadataInvites struct {
	apiutil.PageMetadata
	State string `json:"state,omitempty"`
}

type PlatformInvite struct {
	ID           string
	InviteeEmail string
	CreatedAt    time.Time
	ExpiresAt    time.Time
	State        string
}

type PlatformInvites interface {
	// CreatePlatformInvite creates a pending platform Invite for the appropriate email address.
	// The user can optionally also be invited to an Organization with a certain role - the invites become visible once the user
	// completes registration via the platform invite. Only usable by the platform Root Admin.
	CreatePlatformInvite(ctx context.Context, token, redirectPath, email, orgID, role string) (PlatformInvite, error)

	// RevokePlatformInvite revokes a specific pending PlatformInvite. Only usable by the platform Root Admin.
	RevokePlatformInvite(ctx context.Context, token, inviteID string) error

	// ViewPlatformInvite retrieves a single PlatformInvite denoted by its ID. Only usable by the platform Root Admin.
	ViewPlatformInvite(ctx context.Context, token, inviteID string) (PlatformInvite, error)

	// ListPlatformInvites retrieves a list of platform invites. Only usable by the platform Root Admin.
	ListPlatformInvites(ctx context.Context, token string, pm PageMetadataInvites) (PlatformInvitesPage, error)

	// ValidatePlatformInvite checks if there exists a valid, pending, non-expired platform invite in the database that matches
	// the passed ID and user e-mail. If so, it marks that invite's state as 'accepted', and returns nil.
	// If no such valid platform invite is found in the database, it instead returns errors.ErrAuthorization.
	ValidatePlatformInvite(ctx context.Context, inviteID, email string) error

	// SendPlatformInviteEmail sends an e-mail notifying the invitee about the corresponding platform invite.
	SendPlatformInviteEmail(ctx context.Context, invite PlatformInvite, redirectPath string) error
}

type PlatformInvitesPage struct {
	Invites []PlatformInvite
	apiutil.PageMetadata
}

type PlatformInvitesRepository interface {
	// SavePlatformInvite saves one or more pending platform invites to the repository.
	SavePlatformInvite(ctx context.Context, invites ...PlatformInvite) error

	// RetrievePlatformInviteByID retrieves a single platform invite by its ID.
	RetrievePlatformInviteByID(ctx context.Context, inviteID string) (PlatformInvite, error)

	// RetrievePlatformInvites retrieves a list of platform invites.
	RetrievePlatformInvites(ctx context.Context, pm PageMetadataInvites) (PlatformInvitesPage, error)

	// UpdatePlatformInviteState updates the state of a specific platform invite denoted by its ID.
	UpdatePlatformInviteState(ctx context.Context, inviteID, state string) error
}

type Service interface {
	// SelfRegister carries out the first stage of own account registration: it
	// creates a pending e-mail verification entity and sends the user an e-mail
	// with a URL containing a token used to verify the e-mail address and complete
	// registration.
	SelfRegister(ctx context.Context, user User, redirectPath string) (string, error)

	// VerifyEmail completes the self-registration process by matching the provided
	// email verification token against the database. If the token is valid and not expired, the e-mail
	// is considered verified a new User is fully registered.
	// Returns the ID of the newly-registered User upon success.
	VerifyEmail(ctx context.Context, confirmationToken string) (string, error)

	// RegisterByInvite performs user registration based on a platform invite.
	// inviteID must correspond to a valid, pending and non-expired platform invite, and the user's supplied
	// e-mail address must match the e-mail address of that platform invite. Upon success, marks the associated
	// invite's state as 'accepted'. Returns the ID of the newly registered user.
	RegisterByInvite(ctx context.Context, user User, inviteID, orgInviteRedirectPath string) (string, error)

	// Register creates new user account. In case of the failed registration, a
	// non-nil error value is returned. The user registration is only allowed
	// for admin.
	Register(ctx context.Context, token string, user User) (string, error)

	// RegisterAdmin creates new root admin account. In case of the failed registration, a
	// non-nil error value is returned. The user registration is only allowed
	// for root admin.
	RegisterAdmin(ctx context.Context, user User) error

	// Login authenticates the user given its credentials. Successful
	// authentication generates new access token. Failed invocations are
	// identified by the non-nil error values in the response.
	Login(ctx context.Context, user User) (string, error)

	// ViewUser retrieves user info for a given user ID and an authorized token.
	ViewUser(ctx context.Context, token, id string) (User, error)

	// ViewProfile retrieves user info for a given token.
	ViewProfile(ctx context.Context, token string) (User, error)

	// ListUsers retrieves users list for a valid admin token.
	ListUsers(ctx context.Context, token string, pm PageMetadata) (UserPage, error)

	// ListUsersByIDs retrieves users list for the given IDs.
	ListUsersByIDs(ctx context.Context, ids []string, pm PageMetadata) (UserPage, error)

	// ListUsersByEmails retrieves users list for the given emails.
	ListUsersByEmails(ctx context.Context, emails []string) ([]User, error)

	// UpdateUser updates the user metadata.
	UpdateUser(ctx context.Context, token string, user User) error

	// GenerateResetToken email where mail will be sent.
	GenerateResetToken(ctx context.Context, email, redirectPath string) error

	// ChangePassword change users password for authenticated user.
	ChangePassword(ctx context.Context, token, email, password, oldPassword string) error

	// ResetPassword change users password in reset flow.
	// token can be authentication token or password reset token.
	ResetPassword(ctx context.Context, resetToken, password string) error

	// SendPasswordReset sends reset password link to email.
	SendPasswordReset(ctx context.Context, redirectPath, email, token string) error

	// EnableUser logically enables the user identified with the provided ID
	EnableUser(ctx context.Context, token, id string) error

	// DisableUser logically disables the user identified with the provided ID
	DisableUser(ctx context.Context, token, id string) error

	// Backup returns admin and all users. Only accessible by admin.
	Backup(ctx context.Context, token string) (User, []User, error)

	// Restore restores users from backup. Only accessible by admin.
	Restore(ctx context.Context, token string, admin User, users []User) error

	PlatformInvites
}

type User struct {
	ID       string
	Email    string
	Password string
	Metadata Metadata
	Status   string
	Role     string
}

type UserPage struct {
	Total uint64
	Users []User
}

type UserRepository interface {
	// Save persists the user account. A non-nil error is returned to indicate
	// operation failure.
	Save(ctx context.Context, u User) (string, error)

	// UpdateUser updates the user metadata.
	UpdateUser(ctx context.Context, u User) error

	// RetrieveByEmail retrieves user by its unique identifier (i.e. email).
	RetrieveByEmail(ctx context.Context, email string) (User, error)

	// RetrieveByID retrieves user by its unique identifier ID.
	RetrieveByID(ctx context.Context, id string) (User, error)

	// RetrieveByIDs retrieves all users for given array of userIDs.
	RetrieveByIDs(ctx context.Context, userIDs []string, pm PageMetadata) (UserPage, error)

	// UpdatePassword updates password for user with given email
	UpdatePassword(ctx context.Context, email, password string) error

	// ChangeStatus changes users status to enabled or disabled
	ChangeStatus(ctx context.Context, id, status string) error

	// BackupAll retrieves all users.
	BackupAll(ctx context.Context) ([]User, error)
}