phone

type Event struct {
	Type EventType

	VerificationId string

	PhoneNumber   string
	PhoneMetadata *phone.Metadata

	CreatedAt time.Time
}

type EventType uint8

type LinkingToken struct {
	PhoneNumber       string
	Code              string
	CurrentCheckCount uint32
	MaxCheckCount     uint32
	ExpiresAt         time.Time
}

type OwnerAccountSetting struct {
	OwnerAccount  string
	IsUnlinked    *bool
	CreatedAt     time.Time
	LastUpdatedAt time.Time
}

type Settings struct {
	PhoneNumber    string
	ByOwnerAccount map[string]*OwnerAccountSetting
}

type Store interface {
	// SaveVerification upserts a verification. Updates will only occur on newer
	// verifications and won't lower existing permission levels.
	SaveVerification(ctx context.Context, v *Verification) error

	// GetVerification gets a phone verification for the provided owner account
	// and phone number pair.
	GetVerification(ctx context.Context, account, phoneNumber string) (*Verification, error)

	// GetLatestVerificationForAccount gets the latest verification for a given
	// owner account.
	GetLatestVerificationForAccount(ctx context.Context, account string) (*Verification, error)

	// GetLatestVerificationForNumber gets the latest verification for a given
	// phone number.
	GetLatestVerificationForNumber(ctx context.Context, phoneNumber string) (*Verification, error)

	// GetAllVerificationsForNumber gets all phone verifications for a given
	// phoneNumber. The returned value will be order by the last verification
	// time.
	//
	// todo: May want to consider using cursors, but for now we expect the number
	//       of owner accounts per number to be relatively small.
	GetAllVerificationsForNumber(ctx context.Context, phoneNumber string) ([]*Verification, error)

	// SaveLinkingToken uperts a phone linking token.
	SaveLinkingToken(ctx context.Context, token *LinkingToken) error

	// UseLinkingToken enforces the one-time use of the token if the phone number
	// and code pair matches.
	//
	// todo: Enforce one active code per phone number with a limited numer of checks,
	//       as a security measure.
	UseLinkingToken(ctx context.Context, phoneNumber, code string) error

	// FilterVerifiedNumbers filters phone numbers that have been verified.
	FilterVerifiedNumbers(ctx context.Context, phoneNumbers []string) ([]string, error)

	// GetSettings gets settings for a phone number. The implementation guarantee
	// an empty setting is returned if the DB entry doesn't exist.
	GetSettings(ctx context.Context, phoneNumber string) (*Settings, error)

	// SaveOwnerAccountSetting saves a phone setting for a given owner account.
	// Only non-nil settings will be updated.
	SaveOwnerAccountSetting(ctx context.Context, phoneNumber string, newSettings *OwnerAccountSetting) error

	// PutEvent stores a new phone event
	PutEvent(ctx context.Context, event *Event) error

	// GetLatestEventForNumberByType gets the latest event for a phone number by type
	GetLatestEventForNumberByType(ctx context.Context, phoneNumber string, eventType EventType) (*Event, error)

	// CountEventsForVerificationByType gets the count of events by type for a given verification
	CountEventsForVerificationByType(ctx context.Context, verification string, eventType EventType) (uint64, error)

	// CountEventsForNumberByType gets the count of events by type for a given phone number since a
	// timestamp
	CountEventsForNumberByTypeSinceTimestamp(ctx context.Context, phoneNumber string, eventType EventType, since time.Time) (uint64, error)

	// CountUniqueVerificationIdsForNumberSinceTimestamp counts the number of unique verifications a
	// phone number has been involved in since a timestamp.
	CountUniqueVerificationIdsForNumberSinceTimestamp(ctx context.Context, phoneNumber string, since time.Time) (uint64, error)
}

type Verification struct {
	PhoneNumber    string
	OwnerAccount   string
	CreatedAt      time.Time
	LastVerifiedAt time.Time
}