@plyaz/types 1.39.4 → 1.39.5

package/dist/auth/adapter-interface.d.ts

@@ -0,0 +1,140 @@
+import type { AUTHPROVIDER } from "./enums";
+import type { ConnectedAccount } from "./types";
+/**
+ * Represents an authenticated user within the system.
+ */
+export interface AuthAdapterUser {
+    /** Unique user identifier */
+    id: string;
+    /** Primary email address of the user */
+    email: string;
+}
+/**
+ * Represents a user session.
+ */
+export interface AuthSession {
+    /** Unique session identifier */
+    id: string;
+    /** Associated user identifier */
+    userId: string;
+    /** Session expiration timestamp */
+    expiresAt: Date;
+}
+/**
+ * Represents authentication tokens.
+ */
+export interface Tokens {
+    /** Access token used for authenticated requests */
+    accessToken: string;
+    /** Optional refresh token for session renewal */
+    refreshToken?: string;
+}
+/**
+ * AuthProviderAdapter
+ *
+ * Unified contract for all authentication providers (Clerk, NextAuth, Custom).
+ * Implementations must conform to this interface so that the application
+ * remains provider-agnostic.
+ */
+export interface AuthProviderAdapter {
+    /**
+     * Sign in an existing user.
+     *
+     * @param provider - Authentication provider identifier
+     * @param credentials - Provider-specific credentials
+     * @returns Auth result containing user, session, and tokens
+     */
+    signIn(provider: AUTHPROVIDER, credentials?: unknown): Promise<{
+        user: AuthAdapterUser;
+        session: AuthSession;
+        tokens: Tokens;
+    }>;
+    /**
+     * Register a new user.
+     *
+     * Depending on the provider, this may be handled externally
+     * (e.g., Clerk UI) or internally (custom implementation).
+     *
+     * @param provider - Authentication provider identifier
+     * @param credentials - Provider-specific credentials
+     * @param data - Optional additional user data
+     * @returns Auth result or void if handled externally
+     */
+    signUp(provider: AUTHPROVIDER, credentials: unknown, data?: unknown): Promise<{
+        user: AuthAdapterUser;
+        session: AuthSession;
+        tokens: Tokens;
+    }> | Promise<void>;
+    /**
+     * Sign out a user session.
+     *
+     * @param sessionId - Session identifier
+     */
+    signOut(sessionId: string): Promise<void>;
+    /**
+     * Retrieve a session by its identifier.
+     *
+     * @param sessionId - Session identifier
+     * @returns Session or null if not found or expired
+     */
+    getSession(sessionId: string): Promise<AuthSession | null>;
+    /**
+     * Validate a session.
+     *
+     * @param sessionId - Session identifier
+     * @returns True if session is valid, otherwise false
+     */
+    validateSession(sessionId: string): Promise<boolean>;
+    /**
+     * Refresh an existing session using a refresh token.
+     *
+     * @param refreshToken - Refresh token
+     * @returns New session and tokens, or void if not supported
+     */
+    refreshSession(refreshToken: string): Promise<{
+        session: AuthSession;
+        tokens: Tokens;
+    } | void>;
+    /**
+     * Generate an OAuth authorization URL.
+     *
+     * @param provider - OAuth provider
+     * @param redirectUri - Redirect URI after authentication
+     * @returns Authorization URL or void if handled externally
+     */
+    getOAuthUrl(provider: AUTHPROVIDER, redirectUri: string): Promise<string | void>;
+    /**
+     * Handle OAuth callback after provider authentication.
+     *
+     * @param provider - OAuth provider
+     * @param code - Authorization code returned by provider
+     * @returns Provider account data or void if handled externally
+     */
+    handleOAuthCallback(provider: AUTHPROVIDER, code: string): Promise<{
+        providerAccountId: string;
+        profile: unknown;
+    } | void>;
+    /**
+     * Link an external provider account to an existing user.
+     *
+     * @param userId - Local user identifier
+     * @param provider - Authentication provider
+     * @param data - Connected account metadata
+     * @returns Connected account or void if handled externally
+     */
+    linkAccount(userId: string, provider: AUTHPROVIDER, data: ConnectedAccount): Promise<ConnectedAccount | void>;
+    /**
+     * Unlink an external provider account from a user.
+     *
+     * @param userId - Local user identifier
+     * @param accountId - Connected account identifier
+     */
+    unlinkAccount(userId: string, accountId: string): Promise<void>;
+}
+/**
+ * Credentials object used for email/password authentication.
+ */
+export type Credentials = {
+    email: string;
+    password: string;
+};