@lanonasis/oauth-client 1.2.7 → 2.0.0

package/dist/index.d.cts

@@ -13,6 +13,165 @@ declare class TerminalOAuthFlow extends BaseOAuthFlow {
     private checkDeviceCode;
 }
 
+/**
+ * Magic Link / OTP Flow
+ *
+ * Passwordless authentication supporting two modes:
+ * 1. OTP Code (type: 'email') - User receives 6-digit code to enter manually (CLI, mobile)
+ * 2. Magic Link (type: 'magiclink') - User clicks link in email (web, desktop)
+ *
+ * Usage:
+ * ```typescript
+ * // OTP Code Flow (CLI)
+ * const flow = new MagicLinkFlow({ clientId: 'my-app' });
+ * await flow.requestOTP('user@example.com');
+ * const tokens = await flow.verifyOTP('user@example.com', '123456');
+ *
+ * // Magic Link Flow (Web)
+ * const flow = new MagicLinkFlow({ clientId: 'my-app' });
+ * await flow.requestMagicLink('user@example.com', 'https://myapp.com/auth/callback');
+ * // User clicks link in email, then:
+ * const tokens = await flow.exchangeMagicLinkToken(supabaseAccessToken, state);
+ * ```
+ */
+
+type OTPType = 'email' | 'magiclink';
+type Platform = 'cli' | 'web' | 'mcp' | 'api';
+interface MagicLinkConfig extends OAuthConfig {
+    projectScope?: string;
+    platform?: Platform;
+}
+interface OTPSendResponse {
+    success: boolean;
+    message: string;
+    type: OTPType;
+    expires_in: number;
+}
+interface OTPVerifyResponse extends TokenResponse {
+    auth_method: 'otp' | 'magic_link';
+    user?: {
+        id: string;
+        email: string;
+        role: string;
+    };
+}
+interface MagicLinkExchangeResponse extends TokenResponse {
+    redirect_to?: string;
+    user?: {
+        id: string;
+        email?: string;
+        role?: string;
+        project_scope?: string;
+    };
+}
+declare class MagicLinkFlow extends BaseOAuthFlow {
+    private readonly projectScope;
+    private readonly platform;
+    constructor(config: MagicLinkConfig);
+    /**
+     * Main authenticate method - uses OTP code flow by default
+     * For interactive CLI usage, prefer using requestOTP() and verifyOTP() separately
+     */
+    authenticate(): Promise<TokenResponse>;
+    /**
+     * Request a 6-digit OTP code to be sent via email
+     * User will enter this code manually in the CLI
+     *
+     * @param email - User's email address
+     * @returns Response with success status and expiration time
+     */
+    requestOTP(email: string): Promise<OTPSendResponse>;
+    /**
+     * Verify the OTP code entered by the user and get tokens
+     *
+     * @param email - User's email address (must match the one used in requestOTP)
+     * @param code - 6-digit OTP code from email
+     * @returns Token response with access_token, refresh_token, etc.
+     */
+    verifyOTP(email: string, code: string): Promise<OTPVerifyResponse>;
+    /**
+     * Resend OTP code (rate limited)
+     *
+     * @param email - User's email address
+     * @returns Response with success status
+     */
+    resendOTP(email: string): Promise<OTPSendResponse>;
+    /**
+     * Request a magic link to be sent via email
+     * User will click the link which redirects to your callback URL
+     *
+     * @param email - User's email address
+     * @param redirectUri - URL to redirect to after clicking the magic link
+     * @returns Response with success status
+     */
+    requestMagicLink(email: string, redirectUri: string): Promise<OTPSendResponse>;
+    /**
+     * Alternative: Use the /v1/auth/magic-link endpoint (web-optimized)
+     * This endpoint provides better redirect handling for web apps
+     *
+     * @param email - User's email address
+     * @param redirectUri - URL to redirect to after authentication
+     * @param createUser - Whether to create a new user if email doesn't exist
+     */
+    requestMagicLinkWeb(email: string, redirectUri: string, createUser?: boolean): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Exchange magic link token for auth-gateway tokens
+     * Called after user clicks the magic link and is redirected to your callback
+     *
+     * @param supabaseAccessToken - Access token from Supabase (from URL hash/query)
+     * @param state - State parameter from the callback URL
+     * @returns Token response with redirect URL
+     */
+    exchangeMagicLinkToken(supabaseAccessToken: string, state: string): Promise<MagicLinkExchangeResponse>;
+    /**
+     * Check if an email is valid format
+     */
+    static isValidEmail(email: string): boolean;
+    /**
+     * Check if an OTP code is valid format (6 digits).
+     *
+     * This method:
+     * - Trims leading and trailing whitespace from the input before validating.
+     * - Requires exactly 6 numeric digits (0–9); any non-numeric characters or
+     *   incorrect length will cause it to return `false`.
+     *
+     * Note: This method expects a string value. Passing `null`, `undefined`, or
+     * other non-string values will result in a runtime error when `.trim()` is
+     * called, rather than returning `false`.
+     *
+     * @param code - The OTP code to validate.
+     * @returns `true` if the trimmed code consists of exactly 6 digits, otherwise `false`.
+     */
+    static isValidOTPCode(code: string): boolean;
+}
+
+/**
+ * API Key Authentication Flow
+ *
+ * This flow uses a direct API key for authentication instead of OAuth.
+ * The API key is sent via x-api-key header to the backend.
+ */
+declare class APIKeyFlow extends BaseOAuthFlow {
+    private apiKey;
+    constructor(apiKey: string, authBaseUrl?: string);
+    /**
+     * "Authenticate" by returning the API key as a virtual token
+     * The API key will be used directly in request headers
+     */
+    authenticate(): Promise<TokenResponse>;
+    /**
+     * API keys don't need refresh
+     */
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+    /**
+     * Optional: Validate API key by making a test request
+     */
+    validateAPIKey(): Promise<boolean>;
+}
+
 interface MCPClientConfig extends Partial<OAuthConfig> {
     mcpEndpoint?: string;
     autoRefresh?: boolean;
@@ -51,4 +210,4 @@ declare class MCPClient {
     deleteMemory(id: string): Promise<void>;
 }
 
-export { BaseOAuthFlow, MCPClient, type MCPClientConfig, OAuthConfig, TerminalOAuthFlow, TokenResponse, TokenStorageAdapter };
+export { APIKeyFlow, BaseOAuthFlow, MCPClient, type MCPClientConfig, type MagicLinkConfig, type MagicLinkExchangeResponse, MagicLinkFlow, OAuthConfig, type OTPSendResponse, type OTPType, type OTPVerifyResponse, type Platform, TerminalOAuthFlow, TokenResponse, TokenStorageAdapter };

package/dist/index.d.ts

@@ -13,6 +13,165 @@ declare class TerminalOAuthFlow extends BaseOAuthFlow {
     private checkDeviceCode;
 }
 
+/**
+ * Magic Link / OTP Flow
+ *
+ * Passwordless authentication supporting two modes:
+ * 1. OTP Code (type: 'email') - User receives 6-digit code to enter manually (CLI, mobile)
+ * 2. Magic Link (type: 'magiclink') - User clicks link in email (web, desktop)
+ *
+ * Usage:
+ * ```typescript
+ * // OTP Code Flow (CLI)
+ * const flow = new MagicLinkFlow({ clientId: 'my-app' });
+ * await flow.requestOTP('user@example.com');
+ * const tokens = await flow.verifyOTP('user@example.com', '123456');
+ *
+ * // Magic Link Flow (Web)
+ * const flow = new MagicLinkFlow({ clientId: 'my-app' });
+ * await flow.requestMagicLink('user@example.com', 'https://myapp.com/auth/callback');
+ * // User clicks link in email, then:
+ * const tokens = await flow.exchangeMagicLinkToken(supabaseAccessToken, state);
+ * ```
+ */
+
+type OTPType = 'email' | 'magiclink';
+type Platform = 'cli' | 'web' | 'mcp' | 'api';
+interface MagicLinkConfig extends OAuthConfig {
+    projectScope?: string;
+    platform?: Platform;
+}
+interface OTPSendResponse {
+    success: boolean;
+    message: string;
+    type: OTPType;
+    expires_in: number;
+}
+interface OTPVerifyResponse extends TokenResponse {
+    auth_method: 'otp' | 'magic_link';
+    user?: {
+        id: string;
+        email: string;
+        role: string;
+    };
+}
+interface MagicLinkExchangeResponse extends TokenResponse {
+    redirect_to?: string;
+    user?: {
+        id: string;
+        email?: string;
+        role?: string;
+        project_scope?: string;
+    };
+}
+declare class MagicLinkFlow extends BaseOAuthFlow {
+    private readonly projectScope;
+    private readonly platform;
+    constructor(config: MagicLinkConfig);
+    /**
+     * Main authenticate method - uses OTP code flow by default
+     * For interactive CLI usage, prefer using requestOTP() and verifyOTP() separately
+     */
+    authenticate(): Promise<TokenResponse>;
+    /**
+     * Request a 6-digit OTP code to be sent via email
+     * User will enter this code manually in the CLI
+     *
+     * @param email - User's email address
+     * @returns Response with success status and expiration time
+     */
+    requestOTP(email: string): Promise<OTPSendResponse>;
+    /**
+     * Verify the OTP code entered by the user and get tokens
+     *
+     * @param email - User's email address (must match the one used in requestOTP)
+     * @param code - 6-digit OTP code from email
+     * @returns Token response with access_token, refresh_token, etc.
+     */
+    verifyOTP(email: string, code: string): Promise<OTPVerifyResponse>;
+    /**
+     * Resend OTP code (rate limited)
+     *
+     * @param email - User's email address
+     * @returns Response with success status
+     */
+    resendOTP(email: string): Promise<OTPSendResponse>;
+    /**
+     * Request a magic link to be sent via email
+     * User will click the link which redirects to your callback URL
+     *
+     * @param email - User's email address
+     * @param redirectUri - URL to redirect to after clicking the magic link
+     * @returns Response with success status
+     */
+    requestMagicLink(email: string, redirectUri: string): Promise<OTPSendResponse>;
+    /**
+     * Alternative: Use the /v1/auth/magic-link endpoint (web-optimized)
+     * This endpoint provides better redirect handling for web apps
+     *
+     * @param email - User's email address
+     * @param redirectUri - URL to redirect to after authentication
+     * @param createUser - Whether to create a new user if email doesn't exist
+     */
+    requestMagicLinkWeb(email: string, redirectUri: string, createUser?: boolean): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Exchange magic link token for auth-gateway tokens
+     * Called after user clicks the magic link and is redirected to your callback
+     *
+     * @param supabaseAccessToken - Access token from Supabase (from URL hash/query)
+     * @param state - State parameter from the callback URL
+     * @returns Token response with redirect URL
+     */
+    exchangeMagicLinkToken(supabaseAccessToken: string, state: string): Promise<MagicLinkExchangeResponse>;
+    /**
+     * Check if an email is valid format
+     */
+    static isValidEmail(email: string): boolean;
+    /**
+     * Check if an OTP code is valid format (6 digits).
+     *
+     * This method:
+     * - Trims leading and trailing whitespace from the input before validating.
+     * - Requires exactly 6 numeric digits (0–9); any non-numeric characters or
+     *   incorrect length will cause it to return `false`.
+     *
+     * Note: This method expects a string value. Passing `null`, `undefined`, or
+     * other non-string values will result in a runtime error when `.trim()` is
+     * called, rather than returning `false`.
+     *
+     * @param code - The OTP code to validate.
+     * @returns `true` if the trimmed code consists of exactly 6 digits, otherwise `false`.
+     */
+    static isValidOTPCode(code: string): boolean;
+}
+
+/**
+ * API Key Authentication Flow
+ *
+ * This flow uses a direct API key for authentication instead of OAuth.
+ * The API key is sent via x-api-key header to the backend.
+ */
+declare class APIKeyFlow extends BaseOAuthFlow {
+    private apiKey;
+    constructor(apiKey: string, authBaseUrl?: string);
+    /**
+     * "Authenticate" by returning the API key as a virtual token
+     * The API key will be used directly in request headers
+     */
+    authenticate(): Promise<TokenResponse>;
+    /**
+     * API keys don't need refresh
+     */
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+    /**
+     * Optional: Validate API key by making a test request
+     */
+    validateAPIKey(): Promise<boolean>;
+}
+
 interface MCPClientConfig extends Partial<OAuthConfig> {
     mcpEndpoint?: string;
     autoRefresh?: boolean;
@@ -51,4 +210,4 @@ declare class MCPClient {
     deleteMemory(id: string): Promise<void>;
 }
 
-export { BaseOAuthFlow, MCPClient, type MCPClientConfig, OAuthConfig, TerminalOAuthFlow, TokenResponse, TokenStorageAdapter };
+export { APIKeyFlow, BaseOAuthFlow, MCPClient, type MCPClientConfig, type MagicLinkConfig, type MagicLinkExchangeResponse, MagicLinkFlow, OAuthConfig, type OTPSendResponse, type OTPType, type OTPVerifyResponse, type Platform, TerminalOAuthFlow, TokenResponse, TokenStorageAdapter };