phonenumber

type AESGCMCipher struct {
	// contains filtered or unexported fields
}

type CallbackOnVerificationFunc func(ctx context.Context, data OnVerificationData) error

type CheckVerificationOTPParams struct {
	// PhoneNumber is the target phone number.
	PhoneNumber string `json:"phone_number"`

	// Type specifies the OTP workflow type.
	Type OTPType `json:"type"`

	// OTP is the code to check.
	OTP string `json:"otp"`

	plugin.ExtraContainer
}

type CheckVerificationOTPResult struct {
	// Success indicates whether the OTP is currently valid.
	Success bool `json:"success"`
}

type Cipher interface {
	// Encrypt encrypts a plain text OTP into a secure string representation.
	Encrypt(plaintext string) (string, error)

	// Decrypt decrypts an encrypted string back into the original plain text OTP.
	Decrypt(ciphertext string) (string, error)
}

type Config struct {
	// SendOTP is the required SMS delivery callback.
	SendOTP SendOTPFunc

	// VerifyOTP is an optional delegated verification callback.
	VerifyOTP VerifyOTPFunc

	// SendPasswordResetOTP is an optional dedicated callback for password reset SMS OTPs.
	SendPasswordResetOTP SendOTPFunc

	// PhoneNumberValidator is an optional callback to validate phone number format.
	PhoneNumberValidator PhoneNumberValidatorFunc

	// CallbackOnVerification is an optional callback executed upon successful phone verification.
	CallbackOnVerification CallbackOnVerificationFunc

	// OnPasswordReset is an optional callback executed upon password reset confirmation.
	OnPasswordReset OnPasswordResetFunc

	// SignUpOnVerification configures temporary credentials for auto-created users.
	SignUpOnVerification *SignUpOnVerificationConfig

	// GenerateOTP is an optional custom OTP generator function.
	GenerateOTP GenerateOTPFunc

	// OTPLength is the number of digits in generated numeric OTPs (default: 6).
	OTPLength int

	// ExpiresIn is the duration after which an unverified OTP expires (default: 5 minutes).
	ExpiresIn time.Duration

	// AllowedAttempts is the maximum number of failed verification tries permitted before invalidating the code (default: 3).
	AllowedAttempts int

	// RequireVerification enforces that the phone number must already be verified before allowing password-based sign-in.
	RequireVerification bool

	// DisableSignUp prevents creating a new user if an account does not exist during phone verification.
	DisableSignUp bool

	// RevokeSessionsOnPasswordReset invalidates all active user sessions after a successful password reset (default: true).
	RevokeSessionsOnPasswordReset bool

	// MinPasswordLength is the minimum password length enforced during password resets (default: 8).
	MinPasswordLength int

	// MaxPasswordLength is the maximum password length enforced during password resets (default: 128).
	MaxPasswordLength int

	// StoreOTPMode defines how the OTP is persisted ("plain", "hashed", "encrypted", default: "plain").
	StoreOTPMode StoreOTPMode

	// SecretKey is the symmetric key used when StoreOTPMode is "encrypted".
	SecretKey string

	// ResendStrategy specifies behavior on resend requests ("rotate" or "reuse", default: "rotate").
	ResendStrategy ResendStrategy

	// CustomHasher is an optional custom Hasher implementation for "hashed" mode.
	CustomHasher Hasher

	// CustomCipher is an optional custom Cipher implementation for "encrypted" mode.
	CustomCipher Cipher
}

type CreateVerificationOTPParams struct {
	// PhoneNumber is the target phone number.
	PhoneNumber string `json:"phone_number"`

	// Type specifies the OTP workflow type.
	Type OTPType `json:"type"`

	plugin.ExtraContainer
}

type CreateVerificationOTPResult struct {
	// Success indicates if the OTP record was created.
	Success bool `json:"success"`

	// ExpiresAt indicates when the created OTP will expire.
	ExpiresAt time.Time `json:"expires_at"`
}

type DefaultSHA256Hasher struct{}

type GenerateOTPFunc func(ctx context.Context, phoneNumber string, otpType OTPType) (string, error)

type GetVerificationOTPParams struct {
	// PhoneNumber is the target phone number.
	PhoneNumber string `json:"phone_number"`

	// Type specifies the OTP workflow type.
	Type OTPType `json:"type"`

	plugin.ExtraContainer
}

type GetVerificationOTPResult struct {
	// OTP is the retrieved plain text code.
	OTP string `json:"otp"`
}

type Hasher interface {
	// Hash computes the one-way cryptographic hash of an OTP code.
	Hash(code string) (string, error)

	// Verify compares a plain text OTP against the stored hash in constant time.
	Verify(code, hashedCode string) bool
}

type OTPFailedPayload struct {
	PhoneNumber       string  `json:"phone_number"`
	Type              OTPType `json:"type"`
	AttemptsUsed      int     `json:"attempts_used"`
	AttemptsRemaining int     `json:"attempts_remaining"`
	Reason            string  `json:"reason"`
	plugin.ExtraContainer
}

type OTPSentPayload struct {
	PhoneNumber string    `json:"phone_number"`
	Type        OTPType   `json:"type"`
	ExpiresAt   time.Time `json:"expires_at"`
	plugin.ExtraContainer
}

type OTPType string

type OTPVerifiedPayload struct {
	UserID      string    `json:"user_id"`
	PhoneNumber string    `json:"phone_number"`
	Type        OTPType   `json:"type"`
	Timestamp   time.Time `json:"timestamp"`
	plugin.ExtraContainer
}

type OnPasswordResetFunc func(ctx context.Context, user *entity.User) error

type OnVerificationData struct {
	// PhoneNumber is the verified phone number.
	PhoneNumber string `json:"phone_number"`

	// User is the updated or newly created user entity.
	User *entity.User `json:"user"`

	// Extra holds dynamic metadata passed through event interceptors.
	Extra map[string]any `json:"extra,omitempty"`
}

type Option func(*Config)

type PasswordResetPayload struct {
	UserID      string    `json:"user_id"`
	PhoneNumber string    `json:"phone_number"`
	Timestamp   time.Time `json:"timestamp"`
	plugin.ExtraContainer
}

type PhoneNumberValidatorFunc func(ctx context.Context, phoneNumber string) (bool, error)

type Plugin struct {
	// contains filtered or unexported fields
}

type Repository interface {
	// FindVerificationValue retrieves an active verification record matching the given identifier.
	//
	// Function:
	//   Queries storage for an active SMS OTP verification record.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Ephemeral short-lived SMS OTP token data.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - identifier: The composite OTP key (e.g. "phone-verification-otp-+1234567890").
	//
	// Returns:
	//   - *VerificationRecord: The matching record if found.
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   SELECT id, identifier, value, expires_at, created_at, updated_at FROM verification_tokens WHERE identifier = $1 LIMIT 1;
	//
	// Example Cache (Redis):
	//   val, err := rdb.Get(ctx, "phoneotp:" + identifier).Bytes()
	FindVerificationValue(ctx context.Context, identifier string) (*VerificationRecord, error)

	// CreateVerificationValue creates or replaces a verification record in storage.
	//
	// Function:
	//   Persists a newly generated SMS OTP verification record.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Short-lived key-value with TTL equal to token validity.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - record: The VerificationRecord entity to persist.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO verification_tokens (id, identifier, value, expires_at, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6);
	//
	// Example Cache (Redis):
	//   err := rdb.Set(ctx, "phoneotp:" + record.Identifier, bytes, ttl).Err()
	CreateVerificationValue(ctx context.Context, record *VerificationRecord) error

	// UpdateVerificationValue updates the value and expiry of an existing verification record.
	//
	// Function:
	//   Updates attempts counter or regenerates SMS OTP code.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Key update with adjusted TTL.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - identifier: The composite OTP key.
	//   - value: The updated value payload (e.g. "<stored_otp>:<attempts>").
	//   - expiresAt: The updated expiration timestamp.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   UPDATE verification_tokens SET value = $1, expires_at = $2, updated_at = $3 WHERE identifier = $4;
	//
	// Example Cache (Redis):
	//   err := rdb.Set(ctx, "phoneotp:" + identifier, bytes, ttl).Err()
	UpdateVerificationValue(ctx context.Context, identifier, value string, expiresAt time.Time) error

	// DeleteVerificationValue removes a verification record from storage by identifier.
	//
	// Function:
	//   Explicit removal of an SMS OTP record upon invalidation.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Key eviction from memory/Redis.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - identifier: The composite OTP key.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   DELETE FROM verification_tokens WHERE identifier = $1;
	//
	// Example Cache (Redis):
	//   err := rdb.Del(ctx, "phoneotp:" + identifier).Err()
	DeleteVerificationValue(ctx context.Context, identifier string) error

	// ConsumeVerificationValue atomically retrieves and deletes a verification record in a single operation.
	// This ensures strictly single-use anti-replay protection under high concurrency.
	//
	// Function:
	//   Single-use SMS OTP verification and atomic consumption.
	//
	// Storage:
	//   Cache (Redis GETDEL / Memory) - Atomic read-and-delete operation.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - identifier: The composite OTP key.
	//
	// Returns:
	//   - *VerificationRecord: The consumed record if it existed and was not expired.
	//   - error: Nil on success, or database error if not found.
	//
	// Example SQL:
	//   DELETE FROM verification_tokens WHERE identifier = $1 AND expires_at > $2 RETURNING id, identifier, value, expires_at, created_at, updated_at;
	//
	// Example Cache (Redis):
	//   val, err := rdb.GetDel(ctx, "phoneotp:" + identifier).Bytes()
	ConsumeVerificationValue(ctx context.Context, identifier string) (*VerificationRecord, error)

	// GetUserByID retrieves a user entity matching the provided unique identifier.
	//
	// Function:
	//   Used to load user details by primary key ID.
	//
	// Storage:
	//   Database (GORM / SQL) - User primary key lookup.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: The user's primary key ID.
	//
	// Returns:
	//   - *entity.User: The matching user entity if found.
	//   - error: ErrUserNotFound if missing, or database error.
	//
	// Example SQL:
	//   SELECT id, name, email, phone_number, phone_number_verified, created_at, updated_at FROM users WHERE id = $1 LIMIT 1;
	GetUserByID(ctx context.Context, userID string) (*entity.User, error)

	// GetUserByPhoneNumber retrieves a user entity matching the provided phone number.
	//
	// Function:
	//   Used during SMS OTP sign-in or signup to locate user account.
	//
	// Storage:
	//   Database (GORM / SQL) - Phone number index query.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - phoneNumber: The normalized phone number to query.
	//
	// Returns:
	//   - *entity.User: The matching user entity if found.
	//   - error: ErrUserNotFound if missing, or database error.
	//
	// Example SQL:
	//   SELECT id, name, email, phone_number, phone_number_verified, created_at, updated_at FROM users WHERE phone_number = $1 LIMIT 1;
	GetUserByPhoneNumber(ctx context.Context, phoneNumber string) (*entity.User, error)

	// CreateUser persists a newly registered user in storage.
	//
	// Function:
	//   Called when a new user registers via phone number OTP.
	//
	// Storage:
	//   Database (GORM / SQL) - Relational insert of new User entity.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - params: Parameters containing name, email, phone number, and metadata.
	//
	// Returns:
	//   - *entity.User: The created user entity.
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO users (id, name, email, phone_number, phone_number_verified, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6, $7);
	CreateUser(ctx context.Context, params *dto.CreateUserParams) (*entity.User, error)

	// UpdateUser updates modified fields of an existing user profile (e.g. PhoneNumber, PhoneNumberVerified).
	//
	// Function:
	//   Called when updating user attributes or setting PhoneNumberVerified to true.
	//
	// Storage:
	//   Database (GORM / SQL) - Relational update.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - user: The modified user entity.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   UPDATE users SET phone_number = $1, phone_number_verified = $2, updated_at = $3 WHERE id = $4;
	UpdateUser(ctx context.Context, user *entity.User) error

	// GetAccountByUserIDAndProvider retrieves an account matching a given user and authentication provider.
	//
	// Function:
	//   Used to locate provider credentials for a user.
	//
	// Storage:
	//   Database (GORM / SQL) - Account credentials record lookup.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: The target user's ID.
	//   - providerID: The provider identifier (e.g. "credential").
	//
	// Returns:
	//   - *entity.Account: The matching account if found.
	//   - error: ErrCredentialAccountNotFound if missing, or database error.
	//
	// Example SQL:
	//   SELECT id, user_id, provider, created_at, updated_at FROM accounts WHERE user_id = $1 AND provider = $2 LIMIT 1;
	GetAccountByUserIDAndProvider(ctx context.Context, userID, providerID string) (*entity.Account, error)

	// CreateAccount associates a new provider authentication account with a user.
	//
	// Function:
	//   Persists account credential linking record.
	//
	// Storage:
	//   Database (GORM / SQL) - Account entity creation.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - account: The Account entity to persist.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO accounts (id, user_id, provider, created_at, updated_at) VALUES ($1, $2, $3, $4, $5);
	CreateAccount(ctx context.Context, account *entity.Account) error

	// UpdateAccountPassword updates the password hash on a user's credential account.
	//
	// Function:
	//   Called during password reset or credential update.
	//
	// Storage:
	//   Database (GORM / SQL) - Account password hash update.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: The target user's ID.
	//   - passwordHash: The newly calculated password hash string.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   UPDATE accounts SET password = $1, updated_at = $2 WHERE user_id = $3 AND provider = 'credential';
	UpdateAccountPassword(ctx context.Context, userID, passwordHash string) error

	// CreateSession persists a new active user session in storage.
	//
	// Function:
	//   Creates a new active session upon successful SMS OTP verification.
	//
	// Storage:
	//   Database (GORM / SQL) - Active session creation.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - params: Parameters containing userID, token, expiration, and metadata.
	//
	// Returns:
	//   - *entity.Session: The created session entity.
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO sessions (id, user_id, token, expires_at, ip_address, user_agent, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6, $7, $8);
	CreateSession(ctx context.Context, params *dto.CreateSessionParams) (*entity.Session, error)

	// DeleteSessionsByUserID invalidates all active sessions for a user (used upon password reset).
	//
	// Function:
	//   Bulk invalidation of user sessions.
	//
	// Storage:
	//   Database (GORM / SQL) - Bulk session removal.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: The target user's ID.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   DELETE FROM sessions WHERE user_id = $1;
	DeleteSessionsByUserID(ctx context.Context, userID string) error
}

type RequestPasswordResetParams struct {
	// PhoneNumber is the account phone number requesting a password reset.
	PhoneNumber string `json:"phone_number"`

	plugin.ExtraContainer
}

type RequestPasswordResetResult struct {
	// Success indicates if the reset OTP was successfully dispatched.
	Success bool `json:"success"`
}

type ResendStrategy string

type ResetPasswordParams struct {
	// PhoneNumber is the account phone number.
	PhoneNumber string `json:"phone_number"`

	// OTP is the reset code submitted by the user.
	OTP string `json:"otp"`

	// NewPassword is the new password string to set.
	NewPassword string `json:"new_password"`

	plugin.ExtraContainer
}

type ResetPasswordResult struct {
	// Success indicates if the password was successfully reset.
	Success bool `json:"success"`
}

type SendOTPData struct {
	// PhoneNumber is the destination recipient phone number.
	PhoneNumber string `json:"phone_number"`

	// Code is the raw numeric OTP verification code to deliver.
	Code string `json:"code"`

	// Type indicates the specific operation requiring verification ("phone-verification", "phone-password-reset").
	Type OTPType `json:"type"`

	// Extra holds dynamic metadata passed through event interceptors.
	Extra map[string]any `json:"extra,omitempty"`
}

type SendOTPFunc func(ctx context.Context, data SendOTPData) error

type SendOTPParams struct {
	// PhoneNumber is the destination recipient phone number (required).
	PhoneNumber string `json:"phone_number"`

	plugin.ExtraContainer
}

type SendOTPResult struct {
	// Success indicates if the OTP was successfully generated and dispatched.
	Success bool `json:"success"`

	// ExpiresAt indicates when the dispatched OTP code will expire.
	ExpiresAt time.Time `json:"expires_at"`
}

type SignInParams struct {
	// PhoneNumber is the registered user's phone number.
	PhoneNumber string `json:"phone_number"`

	// Password is the plain text password.
	Password string `json:"password"`

	// RememberMe extends session lifespan if set to true.
	RememberMe *bool `json:"remember_me,omitempty"`

	plugin.ExtraContainer
}

type SignInResult struct {
	// User is the authenticated user entity.
	User *entity.User `json:"user"`

	// SessionToken is the raw session token.
	SessionToken string `json:"session_token"`

	// Session is the persisted active session entity.
	Session *entity.Session `json:"session"`
}

type SignInSuccessPayload struct {
	User      *entity.User    `json:"user"`
	Session   *entity.Session `json:"session,omitempty"`
	IsNewUser bool            `json:"is_new_user"`
	plugin.ExtraContainer
}

type SignUpOnVerificationConfig struct {
	// GetTempEmail resolves a fallback email for auto-created users given their phone number.
	GetTempEmail func(phoneNumber string) string

	// GetTempName resolves a fallback display name for auto-created users given their phone number.
	GetTempName func(phoneNumber string) string
}

type StoreOTPMode string

type VerificationRecord struct {
	// ID is the unique database record identifier.
	ID string `json:"id"`

	// Identifier is the composite lookup key (e.g. "phone-verification-otp-+1234567890").
	Identifier string `json:"identifier"`

	// Value stores the code and attempt counter formatted as "<stored_otp>:<attempts>".
	Value string `json:"value"`

	// ExpiresAt specifies the exact timestamp after which this verification value is invalid.
	ExpiresAt time.Time `json:"expires_at"`

	// CreatedAt records when the verification record was initialized.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt records when the verification record was last modified.
	UpdatedAt time.Time `json:"updated_at"`
}

type VerifyOTPData struct {
	// PhoneNumber is the destination recipient phone number.
	PhoneNumber string `json:"phone_number"`

	// Code is the verification code submitted by the user.
	Code string `json:"code"`

	// Extra holds dynamic metadata passed through event interceptors.
	Extra map[string]any `json:"extra,omitempty"`
}

type VerifyOTPFunc func(ctx context.Context, data VerifyOTPData) (bool, error)

type VerifyParams struct {
	// PhoneNumber is the phone number being verified (required).
	PhoneNumber string `json:"phone_number"`

	// Code is the verification code submitted by the user (required).
	Code string `json:"code"`

	// UserID is the ID of the authenticated user (required if UpdatePhoneNumber is true).
	UserID string `json:"user_id,omitempty"`

	// UpdatePhoneNumber indicates whether to attach the verified phone number to an existing user session.
	UpdatePhoneNumber bool `json:"update_phone_number,omitempty"`

	// DisableSession prevents creating an active authentication session upon successful verification.
	DisableSession bool `json:"disable_session,omitempty"`

	plugin.ExtraContainer
}

type VerifyResult struct {
	// Success indicates successful phone verification.
	Success bool `json:"success"`

	// User is the authenticated, newly provisioned, or updated user entity.
	User *entity.User `json:"user"`

	// SessionToken is the raw session token if a session was created.
	SessionToken string `json:"session_token,omitempty"`

	// Session is the active session entity if created.
	Session *entity.Session `json:"session,omitempty"`
}