@plyaz/types 1.25.0 → 1.25.2

package/dist/auth/types.d.ts

@@ -1,7 +1,9 @@
 import type { WithExpiration, WithAuthTokens } from '../common/types';
+import type { USER_ROLE_STATUS } from './enums';
 /**
  * AuthToken Interface.
  * @description Represents an authentication token set returned after a successful login or refresh.
+ * @interface AuthToken
  */
 export interface AuthToken extends WithExpiration, WithAuthTokens {
     /**
@@ -10,22 +12,33 @@ export interface AuthToken extends WithExpiration, WithAuthTokens {
     readonly tokenType: 'Bearer';
 }
 /**
- * Represents the credentials used for traditional email/password authentication.
+ * AuthCredentials.
+ * @description Represents the credentials used for traditional email/password authentication.
  * This is used for providers that handle this type of login directly.
  */
 export type AuthCredentials = {
+    /** The user's email address. */
     email: string;
+    /** The user's password (optional, used in traditional login flows). */
     password?: string;
+    /**
+     * One-Time Password (OTP) or magic link token.
+     * This could be extended with other credential types as needed.
+     */
     otp?: string;
 };
 /**
- * A standardized representation of a user's context.
+ * UserContext.
+ * @description A standardized representation of a user's context.
  * This ensures that regardless of the underlying authentication provider (Clerk, Supabase, etc.),
  * your application's internal code can interact with a consistent user object.
  */
 export type UserContext = {
+    /** A unique identifier for the user (e.g., a UUID from Supabase). */
     id: string;
+    /** The user's primary email address. */
     email: string;
+    /** Timestamp when the user was created. */
     createdAt: Date;
 };
 /**
@@ -35,6 +48,8 @@ export type UserContext = {
  *
  * Any provider implementing this interface must handle user lookup, creation,
  * and issuance of the necessary internal tokens (like the Supabase RLS JWT).
+ *
+ * @interface AuthServiceProvider
  */
 export interface AuthServiceProvider {
     /**
@@ -44,6 +59,7 @@ export interface AuthServiceProvider {
      * an external provider to ensure the user exists in the local database,
      * update their metadata, and issue an internal authorization token (e.g., RLS JWT).
      *
+     * @param clerkJwt The JWT received from the external provider (e.g., Clerk).
      * @param externalId The unique identifier from the external authentication provider (e.g., Clerk's 'sub').
      * @param email The user's primary email address from the external provider.
      * @returns A Promise resolving to an object containing the internal UserContext and the provider-specific RLS JWT.
@@ -62,3 +78,604 @@ export interface AuthServiceProvider {
      */
     getUserById(userId: string): Promise<UserContext | null>;
 }
+/**
+ * B2C User Info (public schema).
+ * @description Represents platform users: fans, athletes, clubs, scouts, agents.
+ * * @interface UserInfo
+ * @property {string} id - Unique user identifier (UUID).
+ * @property {string} email - User email address (unique).
+ * @property {string} [clerkUserId] - Clerk provider user ID.
+ * @property {string} authProvider - Authentication provider used.
+ * @property {string} [firstName] - User first name.
+ * @property {string} [lastName] - User last name.
+ * @property {string} displayName - Display name (required).
+ * @property {string} [avatarUrl] - Avatar image URL.
+ * @property {string} [phoneNumber] - Phone number.
+ * @property {boolean} isActive - Account active status.
+ * @property {boolean} isVerified - Email verification status.
+ * @property {Date} createdAt - Account creation timestamp.
+ * @property {Date} updatedAt - Last update timestamp.
+ * @property {Date} [lastLoginAt] - Last login timestamp.
+ */
+export interface UserInfo {
+    id: string;
+    email: string;
+    clerkUserId?: string;
+    authProvider: string;
+    firstName?: string;
+    lastName?: string;
+    displayName: string;
+    avatarUrl?: string;
+    phoneNumber?: string;
+    isActive: boolean;
+    isVerified: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    lastLoginAt?: Date;
+}
+/**
+ * B2B User (backoffice schema).
+ * @description Represents internal staff: admins, moderators, support, finance, compliance.
+ * * @interface BackofficeUser
+ * @property {string} id - Unique user identifier (UUID).
+ * @property {string} email - User email address (unique).
+ * @property {string} passwordHash - Hashed password.
+ * @property {string} [clerkUserId] - Clerk provider user ID.
+ * @property {string} authProvider - Authentication provider used.
+ * @property {string} [firstName] - User first name.
+ * @property {string} [lastName] - User last name.
+ * @property {string} displayName - Display name (required).
+ * @property {string} [avatarUrl] - Avatar image URL.
+ * @property {string} [phoneNumber] - Phone number.
+ * @property {boolean} isActive - Account active status.
+ * @property {boolean} isVerified - Email verification status.
+ * @property {boolean} isSuspended - Account suspension status.
+ * @property {string} [suspensionReason] - Reason for suspension.
+ * @property {Date} [suspendedAt] - Suspension timestamp.
+ * @property {Date} createdAt - Account creation timestamp.
+ * @property {Date} updatedAt - Last update timestamp.
+ * @property {Date} [lastLoginAt] - Last login timestamp.
+ */
+export interface BackofficeUser {
+    id: string;
+    email: string;
+    passwordHash: string;
+    clerkUserId?: string;
+    authProvider: string;
+    firstName?: string;
+    lastName?: string;
+    displayName: string;
+    avatarUrl?: string;
+    phoneNumber?: string;
+    isActive: boolean;
+    isVerified: boolean;
+    isSuspended: boolean;
+    suspensionReason?: string;
+    suspendedAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+    lastLoginAt?: Date;
+}
+/**
+ * B2C Session (public schema).
+ * @description Tracks authenticated user sessions with device and activity info.
+ * * @interface Session
+ * @property {string} id - Unique session identifier.
+ * @property {string} userId - ID of the user owning the session.
+ * @property {string} provider - Authentication provider used.
+ * @property {string} [providerSessionId] - External provider's session ID (if applicable).
+ * @property {Date} expiresAt - Session expiration timestamp.
+ * @property {Date} createdAt - Session creation timestamp.
+ * @property {Date} lastActivityAt - Last activity timestamp for the session.
+ * @property {string} [ipAddress] - IP address used when the session was created/last used.
+ * @property {string} [userAgent] - User agent string of the client.
+ * @property {Record<string, unknown>} [metadata] - Arbitrary metadata related to the session.
+ */
+export interface Session {
+    id: string;
+    userId: string;
+    provider: string;
+    providerSessionId?: string;
+    expiresAt: Date;
+    createdAt: Date;
+    lastActivityAt: Date;
+    ipAddress?: string;
+    userAgent?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * B2B Session (backoffice schema).
+ * @description Tracks authenticated backoffice user sessions.
+ * * @interface BackofficeSession
+ * @property {string} id - Unique session identifier.
+ * @property {string} backofficeUserId - ID of the backoffice user owning the session.
+ * @property {string} provider - Authentication provider used.
+ * @property {string} [providerSessionId] - External provider's session ID (if applicable).
+ * @property {Date} expiresAt - Session expiration timestamp.
+ * @property {Date} createdAt - Session creation timestamp.
+ * @property {Date} lastActivityAt - Last activity timestamp for the session.
+ * @property {string} [ipAddress] - IP address used when the session was created/last used.
+ * @property {string} [userAgent] - User agent string of the client.
+ * @property {Record<string, unknown>} [metadata] - Arbitrary metadata related to the session.
+ */
+export interface BackofficeSession {
+    id: string;
+    backofficeUserId: string;
+    provider: string;
+    providerSessionId?: string;
+    expiresAt: Date;
+    createdAt: Date;
+    lastActivityAt: Date;
+    ipAddress?: string;
+    userAgent?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Connected Account (provider linking).
+ * @description Links external OAuth/Web3 provider accounts to users.
+ * Supports OAuth providers (Clerk, Google, etc.) and Web3 wallets.
+ * * @interface ConnectedAccount
+ * @property {string} id - Unique connected account identifier.
+ * @property {string} userId - ID of the internal user account.
+ * @property {string} providerType - Category of the provider (e.g., 'oauth', 'web3').
+ * @property {string} provider - Specific provider name (e.g., 'google', 'metamask').
+ * @property {string} providerAccountId - Unique ID from the external provider.
+ * @property {string} [walletAddress] - Wallet address for Web3 accounts.
+ * @property {string} [accessTokenEncrypted] - Encrypted access token for the provider.
+ * @property {boolean} isPrimary - Flag indicating if this is the user's primary login account.
+ * @property {Date} linkedAt - Timestamp when the account was linked.
+ */
+export interface ConnectedAccount {
+    id: string;
+    userId: string;
+    providerType: string;
+    provider: string;
+    providerAccountId: string;
+    providerEmail?: string;
+    providerUsername?: string;
+    providerDisplayName?: string;
+    providerAvatarUrl?: string;
+    providerProfileUrl?: string;
+    providerMetadata?: Record<string, unknown>;
+    walletAddress?: string;
+    chainId?: string;
+    accessTokenEncrypted?: string;
+    refreshTokenEncrypted?: string;
+    tokenExpiresAt?: Date;
+    tokenScope?: string;
+    isPrimary: boolean;
+    isVerified: boolean;
+    isActive: boolean;
+    linkedAt: Date;
+    linkedIpAddress?: string;
+    linkedUserAgent?: string;
+    lastUsedAt?: Date;
+    lastUsedIpAddress?: string;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Authentication tokens returned after successful login.
+ * * @interface AuthTokens
+ * @property {string} accessToken - The main access token (JWT or similar).
+ * @property {string} [refreshToken] - Token used to refresh the access token.
+ * @property {number} expiresIn - Access token expiration time in seconds.
+ * @property {string} tokenType - Type of the token, usually 'Bearer'.
+ */
+export interface AuthTokens {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn: number;
+    tokenType: string;
+}
+/**
+ * B2C Role (public schema).
+ * @description Defines user roles: FAN, ATHLETE, SCOUT, AGENT, CLUB, DEVELOPER, ADMIN.
+ * * @interface Role
+ * @property {string} id - Unique role identifier.
+ * @property {string} code - Machine-readable role code (e.g., 'ATHLETE').
+ * @property {string} name - Human-readable role name.
+ * @property {number} hierarchy - Numeric value for role hierarchy/priority.
+ * @property {boolean} isSystem - True if the role is system-defined and cannot be deleted.
+ */
+export interface Role {
+    id: string;
+    code: string;
+    name: string;
+    description?: string;
+    hierarchy: number;
+    canCreateCampaigns?: boolean;
+    canContribute?: boolean;
+    requiresKyc?: boolean;
+    isActive: boolean;
+    isSystem: boolean;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * B2B Role (backoffice schema).
+ * @description Defines staff roles: SUPER_ADMIN, ADMIN, MODERATOR, FINANCE, COMPLIANCE, SUPPORT.
+ * * @interface BackofficeRole
+ * @property {string} id - Unique role identifier.
+ * @property {string} code - Machine-readable role code (e.g., 'SUPER_ADMIN').
+ * @property {string} name - Human-readable role name.
+ * @property {number} hierarchy - Numeric value for role hierarchy/priority.
+ * @property {boolean} canManageUsers - Permission to manage user accounts.
+ * @property {boolean} canViewAllData - Permission to view all data regardless of ownership.
+ */
+export interface BackofficeRole {
+    id: string;
+    code: string;
+    name: string;
+    description?: string;
+    hierarchy: number;
+    canApproveCampaigns: boolean;
+    canApproveKyc: boolean;
+    canApprovePayouts: boolean;
+    canManageUsers: boolean;
+    canManageRoles: boolean;
+    canViewAllData: boolean;
+    isActive: boolean;
+    isSystem: boolean;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Permission (backoffice only).
+ * @description Fine-grained permissions for backoffice users.
+ * * @interface Permission
+ * @property {string} id - Unique permission identifier.
+ * @property {string} code - Machine-readable permission code (e.g., 'USER_READ').
+ * @property {string} resource - The resource the permission applies to (e.g., 'USER', 'CAMPAIGN').
+ * @property {string} action - The action the permission allows (e.g., 'READ', 'DELETE').
+ */
+export interface Permission {
+    id: string;
+    code: string;
+    name: string;
+    description?: string;
+    resource: string;
+    action: string;
+    isActive: boolean;
+    isSystem: boolean;
+    metadata?: Record<string, unknown>;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Role-Permission mapping (backoffice only).
+ * @description Links permissions to roles.
+ * * @interface RolePermission
+ * @property {string} id - Unique mapping identifier.
+ * @property {string} roleId - ID of the role.
+ * @property {string} permissionId - ID of the permission granted.
+ * @property {Date} grantedAt - Timestamp when the permission was assigned to the role.
+ */
+export interface RolePermission {
+    id: string;
+    roleId: string;
+    role: string;
+    permissionId: string;
+    grantedAt: Date;
+    grantedBy?: string;
+}
+/**
+ * User-Permission mapping (backoffice only).
+ * @description Grants/revokes specific permissions to users, overriding role permissions.
+ * * @interface UserPermission
+ * @property {string} id - Unique mapping identifier.
+ * @property {string} backofficeUserId - ID of the backoffice user.
+ * @property {string} permissionId - ID of the permission.
+ * @property {boolean} isGranted - True to grant, false to explicitly revoke.
+ */
+export interface UserPermission {
+    id: string;
+    backofficeUserId: string;
+    permissionId: string;
+    isGranted: boolean;
+    expiresAt?: Date;
+    grantedAt: Date;
+    grantedBy?: string;
+    reason?: string;
+}
+/**
+ * B2C User-Role assignment.
+ * @description Links users to roles with status tracking.
+ * * @interface UserRole
+ * @property {string} userId - ID of the B2C user.
+ * @property {string} roleId - ID of the role assigned.
+ * @property {boolean} isPrimary - True if this is the user's main, active role.
+ * @property {USER_ROLE_STATUS} status - Current status of the role assignment (e.g., ACTIVE, PENDING).
+ */
+export interface UserRole {
+    id: string;
+    userId: string;
+    roleId: string;
+    role: string;
+    isPrimary: boolean;
+    status: USER_ROLE_STATUS;
+    assignedBy?: string;
+    assignedReason?: string;
+    expiresAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * B2B User-Role assignment.
+ * @description Links backoffice users to roles.
+ * * @interface BackofficeUserRole
+ * @property {string} backofficeUserId - ID of the backoffice user.
+ * @property {string} roleId - ID of the role assigned.
+ * @property {boolean} isPrimary - True if this is the user's main, active role.
+ * @property {USER_ROLE_STATUS} status - Current status of the role assignment.
+ */
+export interface BackofficeUserRole {
+    id: string;
+    backofficeUserId: string;
+    roleId: string;
+    role: string;
+    isPrimary: boolean;
+    status: USER_ROLE_STATUS;
+    assignedBy?: string;
+    assignedReason?: string;
+    expiresAt?: Date;
+    createdAt: Date;
+    updatedAt: Date;
+}
+/**
+ * Authentication provider adapter interface.
+ * @description Defines contract for provider-agnostic authentication interactions.
+ * * @interface AuthProviderAdapter
+ * @property {string} name - The name of the authentication provider (e.g., 'clerk', 'auth0').
+ */
+export interface AuthProviderAdapter {
+    name: string;
+    /**
+     * Verifies an external authentication token (e.g., a JWT).
+     * @param token The token to verify.
+     * @returns A Promise resolving to the verified token result.
+     */
+    verifyToken(token: string): Promise<VerifiedToken>;
+    /**
+     * Retrieves user profile information from the external provider using a token.
+     * @param token The access token.
+     * @returns A Promise resolving to the provider's user information.
+     */
+    getUserInfo(token: string): Promise<ProviderUserInfo>;
+    /**
+     * Refreshes an expired access token using a refresh token (optional method).
+     * @param refreshToken The token used for refreshing.
+     * @returns A Promise resolving to a new set of authentication tokens.
+     */
+    refreshToken?(refreshToken: string): Promise<AuthTokens>;
+    /**
+     * Invalidates a token on the provider's side (e.g., logout, optional method).
+     * @param token The token to revoke.
+     * @returns A Promise that resolves when the token is successfully revoked.
+     */
+    revokeToken?(token: string): Promise<void>;
+}
+/**
+ * Verified token result.
+ * @description Data returned after successful token verification.
+ * * @interface VerifiedToken
+ * @property {string} userId - The user's ID from the external provider.
+ * @property {string} provider - The name of the provider.
+ * @property {string} providerAccountId - The provider's unique account ID.
+ */
+export interface VerifiedToken {
+    userId: string;
+    provider: string;
+    providerAccountId: string;
+    email?: string;
+    expiresAt?: Date;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Provider user information.
+ * @description User profile data fetched from an external provider.
+ * * @interface ProviderUserInfo
+ * @property {string} providerAccountId - Unique ID from the external provider.
+ * @property {string} [email] - The user's email address from the provider.
+ */
+export interface ProviderUserInfo {
+    providerAccountId: string;
+    email?: string;
+    displayName?: string;
+    firstName?: string;
+    lastName?: string;
+    avatarUrl?: string;
+    phoneNumber?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * User repository interface.
+ * @description Defines data access methods for B2C user management.
+ * * @interface UserRepositoryInterface
+ */
+export interface UserRepositoryInterface {
+    /** Find a user by their internal ID. */
+    findById(id: string): Promise<UserInfo | null>;
+    /** Find a user by their primary email address. */
+    findByEmail(email: string): Promise<UserInfo | null>;
+    /** Find a user linked to a specific external provider account. */
+    findByProviderAccount(provider: string, providerAccountId: string): Promise<UserInfo | null>;
+    /** Create a new user record. */
+    create(data: CreateUserData): Promise<UserInfo>;
+    /** Update an existing user record. */
+    update(id: string, data: UpdateUserData): Promise<UserInfo>;
+    /** Delete a user record. */
+    delete(id: string): Promise<void>;
+}
+/**
+ * Session repository interface.
+ * @description Defines data access methods for B2C session management.
+ * * @interface SessionRepositoryInterface
+ */
+export interface SessionRepositoryInterface {
+    /** Create a new session record. */
+    create(data: CreateSessionData): Promise<Session>;
+    /** Find a session by its ID. */
+    findById(id: string): Promise<Session | null>;
+    /** Find all active sessions for a given user ID. */
+    findByUserId(userId: string): Promise<Session[]>;
+    /** Validate if a session ID is current and not expired. */
+    validate(sessionId: string): Promise<Session | null>;
+    /** Invalidate (log out) a specific session. */
+    invalidate(sessionId: string): Promise<void>;
+    /** Invalidate (log out) all sessions for a user. */
+    invalidateAllForUser(userId: string): Promise<void>;
+    /** Update the last activity timestamp for a session. */
+    updateActivity(sessionId: string): Promise<void>;
+}
+/**
+ * Connected account repository interface.
+ * @description Defines data access methods for provider account linking.
+ * * @interface ConnectedAccountRepositoryInterface
+ */
+export interface ConnectedAccountRepositoryInterface {
+    /** Create a new connected account link. */
+    create(data: CreateConnectedAccountData): Promise<ConnectedAccount>;
+    /** Find a connected account by its internal ID. */
+    findById(id: string): Promise<ConnectedAccount | null>;
+    /** Find all connected accounts linked to a user. */
+    findByUserId(userId: string): Promise<ConnectedAccount[]>;
+    /** Find a connected account by provider and account ID. */
+    findByProvider(provider: string, providerAccountId: string): Promise<ConnectedAccount | null>;
+    /** Update an existing connected account record. */
+    update(id: string, data: UpdateConnectedAccountData): Promise<ConnectedAccount>;
+    /** Delete a connected account link. */
+    delete(id: string): Promise<void>;
+}
+/**
+ * DTO for creating B2C users.
+ * @interface CreateUserData
+ */
+export interface CreateUserData {
+    email: string;
+    clerkUserId?: string;
+    authProvider?: string;
+    firstName?: string;
+    lastName?: string;
+    displayName: string;
+    avatarUrl?: string;
+    phoneNumber?: string;
+    isVerified?: boolean;
+}
+/**
+ * DTO for creating B2B users.
+ * @interface CreateBackofficeUserData
+ */
+export interface CreateBackofficeUserData {
+    email: string;
+    passwordHash: string;
+    clerkUserId?: string;
+    authProvider?: string;
+    firstName?: string;
+    lastName?: string;
+    displayName: string;
+    avatarUrl?: string;
+    phoneNumber?: string;
+    isVerified?: boolean;
+}
+/**
+ * DTO for updating B2C users.
+ * @interface UpdateUserData
+ */
+export interface UpdateUserData {
+    email?: string;
+    clerkUserId?: string;
+    authProvider?: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    avatarUrl?: string;
+    phoneNumber?: string;
+    isActive?: boolean;
+    isVerified?: boolean;
+    lastLoginAt?: Date;
+}
+/**
+ * DTO for updating B2B users.
+ * @interface UpdateBackofficeUserData
+ */
+export interface UpdateBackofficeUserData {
+    email?: string;
+    passwordHash?: string;
+    clerkUserId?: string;
+    authProvider?: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
+    avatarUrl?: string;
+    phoneNumber?: string;
+    isActive?: boolean;
+    isVerified?: boolean;
+    isSuspended?: boolean;
+    suspensionReason?: string;
+    suspendedAt?: Date;
+    lastLoginAt?: Date;
+}
+/**
+ * DTO for creating sessions.
+ * @interface CreateSessionData
+ */
+export interface CreateSessionData {
+    userId: string;
+    provider: string;
+    providerSessionId?: string;
+    expiresAt: Date;
+    ipAddress?: string;
+    userAgent?: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * DTO for creating connected accounts.
+ * @interface CreateConnectedAccountData
+ */
+export interface CreateConnectedAccountData {
+    userId: string;
+    providerType: string;
+    provider: string;
+    providerAccountId: string;
+    providerEmail?: string;
+    providerUsername?: string;
+    providerDisplayName?: string;
+    providerAvatarUrl?: string;
+    providerProfileUrl?: string;
+    providerMetadata?: Record<string, unknown>;
+    walletAddress?: string;
+    chainId?: string;
+    accessTokenEncrypted?: string;
+    refreshTokenEncrypted?: string;
+    tokenExpiresAt?: Date;
+    tokenScope?: string;
+    isPrimary?: boolean;
+    isVerified?: boolean;
+    isActive?: boolean;
+    linkedIpAddress?: string;
+    linkedUserAgent?: string;
+}
+/**
+ * DTO for updating connected accounts.
+ * @interface UpdateConnectedAccountData
+ */
+export interface UpdateConnectedAccountData {
+    providerEmail?: string;
+    providerUsername?: string;
+    providerDisplayName?: string;
+    providerAvatarUrl?: string;
+    providerProfileUrl?: string;
+    providerMetadata?: Record<string, unknown>;
+    accessTokenEncrypted?: string;
+    refreshTokenEncrypted?: string;
+    tokenExpiresAt?: Date;
+    tokenScope?: string;
+    isPrimary?: boolean;
+    isVerified?: boolean;
+    isActive?: boolean;
+    lastUsedAt?: Date;
+    lastUsedIpAddress?: string;
+}