types

type Account struct {
	// ID is the unique identifier for this account
	ID string `json:"id"`

	// UserID links this account to a User
	UserID string `json:"userId"`

	// Provider identifies the authentication method (e.g., "credentials", "google", "github")
	Provider string `json:"provider"`

	// ProviderAccountID is the provider-specific user identifier
	// (e.g., email for credentials, OAuth provider user ID for OAuth)
	ProviderAccountID string `json:"providerAccountId"`

	// PasswordHash stores the hashed password for credential-based accounts.
	// Never returned in JSON responses (json:"-").
	PasswordHash string `json:"-"`

	// AccessToken stores the OAuth access token (OAuth providers only)
	AccessToken string `json:"accessToken,omitempty"`

	// RefreshToken stores the OAuth refresh token (OAuth providers only)
	RefreshToken string `json:"refreshToken,omitempty"`

	// ExpiresAt indicates when the access token expires (OAuth providers only)
	ExpiresAt time.Time `json:"expiresAt,omitempty"`

	// CreatedAt is when this account was created
	CreatedAt time.Time `json:"createdAt"`

	// UpdatedAt is when this account was last modified
	UpdatedAt time.Time `json:"updatedAt"`

	// Metadata stores custom JSON data for provider-specific attributes
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

type AccountStore interface {
	// Create persists a new account to storage.
	// Returns an error if an account with the same provider and provider
	// account ID already exists.
	Create(ctx context.Context, account Account) error

	// GetByID retrieves an account by its unique identifier.
	// Returns sql.ErrNoRows or equivalent if no account is found.
	GetByID(ctx context.Context, id string) (Account, error)

	// GetByUserID retrieves all accounts belonging to a specific user.
	// Returns an empty slice if the user has no accounts.
	GetByUserID(ctx context.Context, userID string) ([]Account, error)

	// GetByProvider retrieves an account by provider name and provider-specific user ID.
	// This is used during login to find an existing account for a provider.
	// Returns sql.ErrNoRows or equivalent if no matching account is found.
	GetByProvider(ctx context.Context, provider, providerAccountID string) (Account, error)

	// Update modifies an existing account's data (e.g., updating OAuth tokens).
	// Returns an error if the account does not exist.
	Update(ctx context.Context, account Account) error

	// Delete removes an account from storage.
	// Returns an error if the account does not exist.
	Delete(ctx context.Context, id string) error
}

type Dialect string

type Session struct {
	// ID is the unique identifier for this session
	ID string `json:"id"`

	// UserID links this session to a User
	UserID string `json:"userId"`

	// Token is the session authentication token used in requests
	Token string `json:"token"`

	// RefreshToken is an optional long-lived token for obtaining new sessions
	RefreshToken string `json:"refreshToken,omitempty"`

	// ExpiresAt indicates when this session becomes invalid
	ExpiresAt time.Time `json:"expiresAt"`

	// CreatedAt is when this session was created
	CreatedAt time.Time `json:"createdAt"`

	// IPAddress of the client that created this session
	IPAddress string `json:"ipAddress,omitempty"`

	// UserAgent of the client that created this session
	UserAgent string `json:"userAgent,omitempty"`

	// Metadata stores custom JSON data for session-specific attributes
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

type SessionStore interface {
	// Create persists a new session to storage.
	Create(ctx context.Context, session Session) error

	// Get retrieves a session by its unique identifier.
	// Returns sql.ErrNoRows or equivalent if no session is found.
	Get(ctx context.Context, id string) (Session, error)

	// GetByToken retrieves a session by its authentication token.
	// This is the primary method used during request authentication.
	// Returns sql.ErrNoRows or equivalent if no session is found.
	GetByToken(ctx context.Context, token string) (Session, error)

	// GetByRefreshToken retrieves a session by its refresh token.
	// Used in refresh token flows to generate new sessions.
	// Returns sql.ErrNoRows or equivalent if no session is found.
	GetByRefreshToken(ctx context.Context, refreshToken string) (Session, error)

	// GetByUserID retrieves a paginated list of active sessions for a specific user.
	// Returns an empty slice if the user has no active sessions.
	GetByUserID(ctx context.Context, userID string, offset, limit int) ([]Session, error)

	// CountByUserID returns the total number of active sessions for a user.
	CountByUserID(ctx context.Context, userID string) (int, error)

	// Update modifies an existing session's data (e.g., extending expiration).
	// Returns an error if the session does not exist.
	Update(ctx context.Context, session Session) error

	// Delete removes a specific session (used during logout).
	Delete(ctx context.Context, id string) error

	// DeleteByUserID removes all sessions for a user (used during password change
	// or when forcing all sessions to be logged out).
	DeleteByUserID(ctx context.Context, userID string) error

	// CleanupExpired removes all expired sessions.
	// This should be called periodically to prevent storage bloat.
	CleanupExpired(ctx context.Context) error
}

type User struct {
	// ID is the unique identifier for this user (typically a ULID or UUID)
	ID string `json:"id"`

	// Avatar is the URL to the user's profile picture
	Avatar string `json:"avatar,omitempty"`

	// Name is the user's display name
	Name string `json:"name,omitempty"`

	// Email is the user's email address (optional for OAuth-only users)
	Email string `json:"email,omitempty"`

	// CreatedAt is when the user account was created
	CreatedAt time.Time `json:"createdAt"`

	// UpdatedAt is when the user account was last modified
	UpdatedAt time.Time `json:"updatedAt"`

	// Disabled indicates if the user account has been deactivated
	Disabled bool `json:"disabled"`

	// Metadata stores custom JSON data for application-specific attributes
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

type UserStore interface {
	// Create persists a new user to storage.
	// Returns the created user with any storage-assigned fields populated.
	// Returns an error if a user with the same email already exists.
	Create(ctx context.Context, user User) (User, error)

	// GetByEmail retrieves a user by their email address.
	// Returns sql.ErrNoRows or equivalent if no user is found.
	GetByEmail(ctx context.Context, email string) (User, error)

	// GetByID retrieves a user by their unique identifier.
	// Returns sql.ErrNoRows or equivalent if no user is found.
	GetByID(ctx context.Context, id string) (User, error)

	// Update modifies an existing user's data.
	// Returns an error if the user does not exist.
	Update(ctx context.Context, user User) error

	// Delete removes a user from storage (may be soft or hard delete).
	// Returns an error if the user does not exist.
	Delete(ctx context.Context, id string) error

	// List retrieves a paginated list of users.
	// The offset and limit parameters control pagination.
	List(ctx context.Context, offset, limit int) ([]User, error)

	// Count returns the total number of users in storage.
	Count(ctx context.Context) (int, error)
}

type Verification struct {
	// ID is the unique identifier for this verification
	ID string `json:"id"`

	// Identifier is the target of verification (e.g., email address, phone number)
	Identifier string `json:"identifier"`

	// Token is the secret verification code or token
	Token string `json:"token"`

	// Type categorizes the verification purpose (e.g., "email", "reset", "otp")
	Type string `json:"type"`

	// ExpiresAt indicates when this verification token expires
	ExpiresAt time.Time `json:"expiresAt"`

	// CreatedAt is when this verification was created
	CreatedAt time.Time `json:"createdAt"`

	// Metadata stores custom JSON data for verification-specific attributes
	Metadata json.RawMessage `json:"metadata,omitempty"`
}

type VerificationStore interface {
	// Create persists a new verification token to storage.
	Create(ctx context.Context, verification Verification) error

	// GetByToken retrieves a verification by its token value.
	// Returns sql.ErrNoRows or equivalent if no verification is found.
	GetByToken(ctx context.Context, token string) (Verification, error)

	// GetByIdentifier retrieves all verifications for a given identifier
	// (e.g., all pending verifications for an email address).
	// Returns an empty slice if no verifications exist for the identifier.
	GetByIdentifier(ctx context.Context, identifier string) ([]Verification, error)

	// InvalidateByIdentifier marks all verifications of a specific type for an
	// identifier as invalid/used. This is typically called after successful
	// verification to prevent token reuse.
	InvalidateByIdentifier(ctx context.Context, identifier, vType string) error

	// Delete removes a verification token from storage.
	Delete(ctx context.Context, id string) error

	// CleanupExpired removes all expired verification tokens.
	// This should be called periodically to prevent storage bloat.
	CleanupExpired(ctx context.Context) error
}