phone

type Capability = Phone

type Config struct {
	// Provider delivers transactional SMS/voice messages.
	Provider PhoneProvider

	// TTL defines the lifespan of an issued OTP code. Default: 5 minutes.
	TTL time.Duration

	// OTPLength defines the numeric digit count of the OTP. Default: 6.
	OTPLength int

	// MaxAttempts defines the maximum failed attempts permitted before locking the OTP. Default: 3.
	MaxAttempts int

	// AllowSignUp allows automatic creation of accounts for unknown phone numbers upon verification. Default: true.
	AllowSignUp bool

	// RevokePreviousOnRequest revokes active OTPs for the phone prior to issuing a new code. Default: true.
	RevokePreviousOnRequest bool

	// RateLimit holds rate limiting and cooldown rules.
	RateLimit RateLimitConfig

	// CacheTTL defines the TTL for ephemeral phone lookups. Default: 15 minutes.
	CacheTTL time.Duration

	// Normalizer normalizes raw phone strings into canonical E.164 format.
	Normalizer Normalizer

	// Validator validates canonical phone strings.
	Validator Validator

	// MessageBuilder formats message body and delivery parameters.
	MessageBuilder MessageBuilder

	// Hooks provides workflow extension points.
	Hooks *Hooks
}

type ConfirmChangeInput struct {
	// UserID identifies the user. Required.
	UserID string

	// NewPhoneNumber is the new phone number to confirm. Required.
	NewPhoneNumber string

	// Code is the numeric verification code sent to the new phone number. Required.
	Code string
}

type ConfirmVerificationInput struct {
	// UserID identifies the user. Required.
	UserID string

	// PhoneNumber is the phone number to confirm. Required.
	PhoneNumber string

	// Code is the numeric OTP code received on the device. Required.
	Code string
}

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

type Message struct {
	// To is the destination phone number formatted in E.164.
	To string

	// Body is the rendered text body delivered to the recipient.
	Body string

	// Code is the raw numeric verification code.
	Code string

	// Purpose is the semantic action (e.g. "authenticate", "verify", "change").
	Purpose string

	// TTL is the active validity lifespan of the verification code.
	TTL time.Duration

	// Metadata carries optional vendor-specific or application-level parameters.
	Metadata map[string]string
}

type MessageBuilder func(to, code, purpose string, ttl time.Duration) Message

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

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

type Normalizer func(raw string) (string, error)

type OTPRecord struct {
	ID          string     `json:"id"`
	PhoneNumber string     `json:"phone_number"`
	Subject     string     `json:"subject"`
	Purpose     string     `json:"purpose"`
	OTPHash     string     `json:"otp_hash"`
	Salt        string     `json:"salt"`
	ExpiresAt   time.Time  `json:"expires_at"`
	MaxAttempts int        `json:"max_attempts"`
	Attempts    int        `json:"attempts"`
	UsedAt      *time.Time `json:"used_at,omitempty"`
	CreatedAt   time.Time  `json:"created_at"`
}

type OTPRejectedPayload struct {
	PhoneNumber string    `json:"phone_number"`
	Reason      string    `json:"reason"`
	Attempts    int       `json:"attempts"`
	Time        time.Time `json:"time"`
}

type OTPRequestedPayload struct {
	PhoneNumber string    `json:"phone_number"`
	Subject     string    `json:"subject"`
	Purpose     string    `json:"purpose"`
	ExpiresAt   time.Time `json:"expires_at"`
}

type OTPVerifiedPayload struct {
	UserID      string    `json:"user_id"`
	PhoneNumber string    `json:"phone_number"`
	SessionID   string    `json:"session_id,omitempty"`
	VerifiedAt  time.Time `json:"verified_at"`
}

type Option func(*Config)

type Phone interface {
	// RequestOTP dispatches an authentication OTP code to the provided phone number.
	// If AllowSignUp is false and the phone number is unregistered, this method returns nil
	// without dispatching an SMS, protecting against user enumeration.
	RequestOTP(ctx context.Context, in RequestOTPInput) error

	// VerifyOTP validates and atomically consumes the single-use OTP code.
	// On success, it provisions or retrieves the user, links the phone account, and returns an AuthResult.
	// On failure (incorrect code, expired, replay, max attempts exceeded), it emits a rejection event
	// and returns a domain error.
	VerifyOTP(ctx context.Context, in VerifyOTPInput) (*auth.AuthResult, error)

	// RequestVerification dispatches an OTP to verify a user's ownership of a phone number.
	RequestVerification(ctx context.Context, in RequestVerificationInput) error

	// ConfirmVerification validates the OTP and marks the user's phone record as verified.
	ConfirmVerification(ctx context.Context, in ConfirmVerificationInput) (*Record, error)

	// RequestChange dispatches an OTP to a new phone number to begin changing the user's phone number.
	RequestChange(ctx context.Context, in RequestChangeInput) error

	// ConfirmChange validates the OTP sent to the new phone and atomically updates the user's phone number.
	ConfirmChange(ctx context.Context, in ConfirmChangeInput) (*Record, error)

	// Remove unlinks and removes the phone record for the specified user.
	Remove(ctx context.Context, in RemoveInput) error

	// GetByUserID retrieves the phone record associated with a Core user ID.
	GetByUserID(ctx context.Context, userID string) (*Record, error)

	// GetByPhone retrieves the phone record associated with a normalized phone number.
	GetByPhone(ctx context.Context, phoneNumber string) (*Record, error)

	// Normalize transforms and validates a raw phone string into canonical E.164 format.
	Normalize(raw string) (string, error)

	// Validate checks whether a normalized phone number complies with ITU-T E.164 format.
	Validate(normalized string) error
}

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

type PhoneChangedPayload struct {
	UserID    string    `json:"user_id"`
	OldPhone  string    `json:"old_phone"`
	NewPhone  string    `json:"new_phone"`
	ChangedAt time.Time `json:"changed_at"`
}

type PhoneProvider interface {
	Send(ctx context.Context, msg Message) error
}

type PhoneRecord struct {
	ID          string     `json:"id"`
	UserID      string     `json:"user_id"`
	PhoneNumber string     `json:"phone_number"` // Canonical E.164 string
	Verified    bool       `json:"verified"`
	VerifiedAt  *time.Time `json:"verified_at,omitempty"`
	CreatedAt   time.Time  `json:"created_at"`
	UpdatedAt   time.Time  `json:"updated_at"`
}

type PhoneRemovedPayload struct {
	UserID      string    `json:"user_id"`
	PhoneNumber string    `json:"phone_number"`
	RemovedAt   time.Time `json:"removed_at"`
}

type PhoneVerifiedPayload struct {
	UserID      string    `json:"user_id"`
	PhoneNumber string    `json:"phone_number"`
	VerifiedAt  time.Time `json:"verified_at"`
}

type RateLimitConfig struct {
	Enabled       bool
	Max           int
	Window        time.Duration
	Cooldown      time.Duration
	FailurePolicy cache.FailurePolicy
}

type Record = PhoneRecord

type RemoveInput struct {
	// UserID identifies the user whose phone record is being deleted. Required.
	UserID string
}

type RequestChangeInput struct {
	// UserID identifies the user changing their phone number. Required.
	UserID string

	// NewPhoneNumber is the replacement phone number. Required.
	NewPhoneNumber string

	// Metadata carries optional context.
	Metadata map[string]string
}

type RequestOTPInput struct {
	// PhoneNumber is the destination mobile number (E.164 or unformatted). Required.
	PhoneNumber string

	// Metadata carries optional application context or vendor tags.
	Metadata map[string]string
}

type RequestVerificationInput struct {
	// UserID identifies the user to whom the phone is being linked. Required.
	UserID string

	// PhoneNumber is the phone number to verify. Required.
	PhoneNumber string

	// Metadata carries optional context.
	Metadata map[string]string
}

type Validator func(normalized string) error

type VerificationError struct {
	Reason   string
	Attempts int
	Err      error
}

type VerifyOTPInput struct {
	// PhoneNumber is the phone number that requested the code. Required.
	PhoneNumber string

	// Code is the numeric OTP received by the user. Required.
	Code string

	// Email is an optional email address used when registering a new user upon first sign-in.
	Email string

	// Session holds optional IP address and User Agent metadata for the session.
	Session auth.SessionOptions
}