accounts

type AuthError struct {
	Code    string // "email_exists", "username_taken", "weak_password", "invalid_format", etc.
	Message string // Human-readable message
	Field   string // Which form field has the error (e.g., "email", "username", "password")
}

type AuthErrorHandler func(err *AuthError, w http.ResponseWriter, r *http.Request) bool

type BasicUser struct {
	ID          string
	ProfileData map[string]any
}

type Channel struct {
	Provider    string         `json:"provider"`     // "local", "google", "github"
	IdentityKey string         `json:"identity_key"` // "email:john@example.com"
	Credentials map[string]any `json:"credentials"`  // password_hash, access_token, etc.
	Profile     map[string]any `json:"profile"`      // optional data from provider
	CreatedAt   time.Time      `json:"created_at"`
	UpdatedAt   time.Time      `json:"updated_at"`
	ExpiresAt   time.Time      `json:"expires_at"` // when channel auth expires and needs re-auth
	Version     int            `json:"version"`    // optimistic locking version
}

type ChannelStore interface {
	// GetChannel gets or optionally creates a channel.
	GetChannel(provider string, identityKey string, createIfMissing bool) (channel *Channel, newCreated bool, err error)

	// SaveChannel creates or updates a channel (upsert).
	SaveChannel(channel *Channel) error

	// GetChannelsByIdentity returns all channels for an identity.
	GetChannelsByIdentity(identityKey string) ([]*Channel, error)
}

type CredentialsValidator func(username, password, usernameType string) (User, error)

type HandleUserFunc func(authtype string, provider string, token *oauth2.Token, userInfo map[string]any, w http.ResponseWriter, r *http.Request)

type Identity struct {
	Type      string    `json:"type"`     // "email", "phone"
	Value     string    `json:"value"`    // "john@example.com", "+1-555-1234"
	UserID    string    `json:"user_id"`  // which user owns this identity
	Verified  bool      `json:"verified"` // has any channel verified this identity?
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	Version   int       `json:"version"` // optimistic locking version
}

type IdentityStore interface {
	// GetIdentity gets or optionally creates an identity.
	GetIdentity(identityType, identityValue string, createIfMissing bool) (identity *Identity, newCreated bool, err error)

	// SaveIdentity creates or updates an identity (upsert).
	SaveIdentity(identity *Identity) error

	// SetUserForIdentity associates an identity with a user.
	SetUserForIdentity(identityType, identityValue string, newUserId string) error

	// MarkIdentityVerified marks an identity as verified.
	MarkIdentityVerified(identityType, identityValue string) error

	// GetUserIdentities returns all identities for a user.
	GetUserIdentities(userId string) ([]*Identity, error)
}

type User interface {
	Id() string
	Profile() map[string]any
}

type UserStore interface {
	// CreateUser creates a new user with the given ID and profile.
	CreateUser(userId string, isActive bool, profile map[string]any) (User, error)

	// GetUserById retrieves a user by their ID.
	GetUserById(userId string) (User, error)

	// SaveUser creates or updates a user (upsert).
	SaveUser(user User) error
}

type UsernameStore interface {
	// ReserveUsername reserves a username for a user (creates username -> userID mapping).
	// Returns error if username is already taken.
	ReserveUsername(username string, userID string) error

	// GetUserByUsername looks up a userID by username.
	// Returns error if username not found.
	GetUserByUsername(username string) (userID string, err error)

	// ReleaseUsername removes a username reservation.
	ReleaseUsername(username string) error

	// ChangeUsername atomically changes a username (release old, reserve new).
	// Returns error if new username is already taken.
	ChangeUsername(oldUsername, newUsername, userID string) error
}