multisession

type Config struct {
	// MaximumSessions specifies the maximum number of active concurrent multi-sessions allowed on a single device.
	// Default: 5
	MaximumSessions int

	// CookiePrefix defines the prefix for multi-session cookies.
	// Default: "modular-auth"
	CookiePrefix string

	// Secret is the HMAC SHA-256 secret key used for signing and verifying multi-session cookies.
	Secret string

	// OnSessionActivated is an optional callback triggered after a session is set active.
	OnSessionActivated SessionActivatedCallback

	// OnSessionRevoked is an optional callback triggered after a session is revoked.
	OnSessionRevoked SessionRevokedCallback
}

type DeviceSession struct {
	Session  entity.Session `json:"session"`
	User     entity.User    `json:"user"`
	IsActive bool           `json:"isActive"`
}

type ListDeviceSessionsEventPayload struct {
	Params *ListDeviceSessionsParams
	Result *ListDeviceSessionsResult
	Extra  map[string]any
}

type ListDeviceSessionsParams struct {
	// Tokens is the slice of verified multi-session tokens present on the client device.
	Tokens []string `json:"tokens"`

	// ActiveToken optionally specifies the raw token string of the currently active primary session.
	ActiveToken string `json:"activeToken,omitempty"`
}

type ListDeviceSessionsResult struct {
	// DeviceSessions is the slice of valid, non-expired sessions on the device.
	DeviceSessions []DeviceSession `json:"deviceSessions"`

	// TotalCount is the total number of valid multi-sessions found.
	TotalCount int `json:"totalCount"`

	// ActiveSession points to the currently active primary session on the device, if present in the list.
	ActiveSession *DeviceSession `json:"activeSession,omitempty"`
}

type MultiSessionConfigInfo struct {
	MaximumSessions int    `json:"maximumSessions"`
	CookiePrefix    string `json:"cookiePrefix"`
}

type Option func(*Config)

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

type Repository interface {
	// GetSessionByToken retrieves a session entity by its unique session token string.
	//
	// Function:
	//   Used during session validation and active device count evaluation.
	//
	// Storage:
	//   Database (GORM / SQL) - Query sessions table by token column index.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - token: Session token string.
	//
	// Returns:
	//   - *entity.Session: Matching session entity if found.
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   SELECT id, user_id, token, expires_at, created_at, updated_at FROM sessions WHERE token = $1 LIMIT 1;
	GetSessionByToken(ctx context.Context, token string) (*entity.Session, error)

	// GetUserByID retrieves a user entity by its unique user ID.
	//
	// Function:
	//   Used to resolve user details linked to active multi-session tokens.
	//
	// Storage:
	//   Database (GORM / SQL) - Primary key lookup on users table.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: Unique user primary key ID.
	//
	// Returns:
	//   - *entity.User: Matching user entity if found.
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   SELECT id, email, name, avatar, role, created_at, updated_at FROM users WHERE id = $1 LIMIT 1;
	GetUserByID(ctx context.Context, id string) (*entity.User, error)

	// DeleteSession removes a single session by token string.
	//
	// Function:
	//   Called during individual session revocation or logout.
	//
	// Storage:
	//   Database (GORM / SQL) - Delete row matching token.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - token: Target session token string to revoke.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   DELETE FROM sessions WHERE token = $1;
	DeleteSession(ctx context.Context, token string) error

	// DeleteSessions removes multiple sessions by token strings.
	//
	// Function:
	//   Called during mass revocation or session limit enforcement.
	//
	// Storage:
	//   Database (GORM / SQL) - Batch delete rows where token IN ($1, $2, ...).
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - tokens: Slice of session token strings to revoke.
	//
	// Returns:
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   DELETE FROM sessions WHERE token IN ($1, $2, $3);
	DeleteSessions(ctx context.Context, tokens []string) error

	// FindSessionsByTokens returns all valid sessions and corresponding users for a given slice of session tokens.
	//
	// Function:
	//   Called during multi-session cookie evaluation to list all active accounts on a device.
	//
	// Storage:
	//   Database (GORM / SQL) - Join sessions and users where token IN ($1, $2, ...).
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - tokens: Slice of multi-session token strings.
	//
	// Returns:
	//   - []*entity.Session: List of active session entities.
	//   - []*entity.User: List of corresponding user entities.
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   SELECT s.id, s.user_id, s.token, s.expires_at, u.email, u.name FROM sessions s JOIN users u ON s.user_id = u.id WHERE s.token IN ($1, $2);
	FindSessionsByTokens(ctx context.Context, tokens []string) ([]*entity.Session, []*entity.User, error)
}

type RevokeAllSessionsParams struct {
	// DeviceTokens specifies all verified multi-session tokens present on the device.
	DeviceTokens []string `json:"deviceTokens"`
}

type RevokeAllSessionsResult struct {
	// Status indicates if the revocation succeeded.
	Status bool `json:"status"`

	// RevokedTokens is the list of all tokens removed from the database.
	RevokedTokens []string `json:"revokedTokens"`

	// Count is the number of sessions revoked.
	Count int `json:"count"`
}

type RevokeDeviceSessionEventPayload struct {
	Params *RevokeDeviceSessionParams
	Result *RevokeDeviceSessionResult
	Extra  map[string]any
}

type RevokeDeviceSessionParams struct {
	// SessionToken specifies the target session token to revoke.
	SessionToken string `json:"sessionToken,omitempty"`

	// RevokeAll if true indicates all device sessions should be revoked.
	RevokeAll bool `json:"revokeAll,omitempty"`

	// RevokeOther if true indicates all device sessions EXCEPT the active session should be revoked.
	RevokeOther bool `json:"revokeOther,omitempty"`

	// DeviceTokens specifies the list of all multi-session tokens registered on the device.
	DeviceTokens []string `json:"deviceTokens,omitempty"`

	// ActiveTokenInReq specifies the token of the session currently marked as active in the request.
	ActiveTokenInReq string `json:"activeTokenInReq,omitempty"`
}

type RevokeDeviceSessionResult struct {
	// Status indicates if the revocation operation succeeded.
	Status bool `json:"status"`

	// RevokedToken contains the single token revoked (if single session revocation).
	RevokedToken string `json:"revokedToken,omitempty"`

	// RevokedTokens contains the list of all tokens revoked during mass/other revocation.
	RevokedTokens []string `json:"revokedTokens,omitempty"`

	// WasActive indicates whether the revoked session was the currently active session.
	WasActive bool `json:"wasActive"`

	// NewActiveSession points to the next available session to set as active, if applicable.
	NewActiveSession *entity.Session `json:"newActiveSession,omitempty"`

	// ClearActiveSession indicates whether the primary session cookie should be cleared.
	ClearActiveSession bool `json:"clearActiveSession,omitempty"`
}

type RevokeOtherSessionsParams struct {
	// DeviceTokens specifies all verified multi-session tokens present on the device.
	DeviceTokens []string `json:"deviceTokens"`

	// ActiveToken specifies the token of the currently active session to keep.
	ActiveToken string `json:"activeToken"`
}

type RevokeOtherSessionsResult struct {
	// Status indicates if the revocation succeeded.
	Status bool `json:"status"`

	// RevokedTokens is the list of non-active tokens removed from the database.
	RevokedTokens []string `json:"revokedTokens"`

	// Count is the number of non-active sessions revoked.
	Count int `json:"count"`
}

type SessionActivatedCallback func(ctx context.Context, res *SetActiveSessionResult) error

type SessionCreatedEventPayload struct {
	Session *entity.Session
	Extra   map[string]any
}

type SessionRevokedCallback func(ctx context.Context, res *RevokeDeviceSessionResult) error

type SetActiveSessionEventPayload struct {
	Params *SetActiveSessionParams
	Result *SetActiveSessionResult
	Extra  map[string]any
}

type SetActiveSessionParams struct {
	// SessionToken specifies the target session token to set as active.
	SessionToken string `json:"sessionToken"`
}

type SetActiveSessionResult struct {
	// DeviceSession holds the newly activated session and user details.
	DeviceSession DeviceSession `json:"deviceSession"`

	// ActiveToken holds the verified token string of the active session.
	ActiveToken string `json:"activeToken"`

	// ExpiresAt specifies when the active session expires.
	ExpiresAt time.Time `json:"expiresAt"`

	// Status indicates if the activation operation succeeded.
	Status bool `json:"status"`
}

type SignOutEventPayload struct {
	RevokedTokens []string
	Extra         map[string]any
}

type StatusResponse struct {
	Status bool `json:"status"`
}