@draftlab/auth 0.15.0 → 0.16.0

package/dist/types/provider/code.d.ts

@@ -0,0 +1,288 @@
+/**
+ * PIN code authentication provider for Draft Auth.
+ * Supports flexible claim-based authentication via email, phone, or custom identifiers.
+ *
+ * ## Quick Setup
+ *
+ * ```ts
+ * import { CodeUI } from "@draftlab/auth/ui/code"
+ * import { CodeProvider } from "@draftlab/auth/provider/code"
+ *
+ * export default issuer({
+ *   providers: {
+ *     code: CodeProvider(
+ *       CodeUI({
+ *         copy: {
+ *           code_info: "We'll send a PIN code to your email"
+ *         },
+ *         sendCode: async (claims, code) => {
+ *           try {
+ *             await sendEmail(claims.email, `Your code: ${code}`)
+ *           } catch {
+ *             return { type: "invalid_claim", key: "delivery", value: "Failed to send code" }
+ *           }
+ *         }
+ *       })
+ *     )
+ *   }
+ * })
+ * ```
+ *
+ * ## Custom Configuration
+ *
+ * ```ts
+ * const customCodeProvider = CodeProvider({
+ *   length: 4, // 4-digit PIN instead of default 6
+ *   request: async (req, state, form, error) => {
+ *     return new Response(renderCodePage(state, form, error))
+ *   },
+ *   sendCode: async (claims, code) => {
+ *     try {
+ *       if (claims.email) {
+ *         await emailService.send(claims.email, code)
+ *       } else if (claims.phone) {
+ *         await smsService.send(claims.phone, code)
+ *       } else {
+ *         return { type: "invalid_claim", key: "email", value: "Email or phone number is required" }
+ *       }
+ *     } catch {
+ *       return { type: "invalid_claim", key: "delivery", value: "Failed to send code" }
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * ## Features
+ *
+ * - **Flexible claims**: Support any claim type (email, phone, username, etc.)
+ * - **Configurable PIN length**: 4-6 digit codes typically
+ * - **Resend functionality**: Built-in code resend capability
+ * - **Custom UI**: Full control over the authentication interface
+ * - **Error handling**: Comprehensive error states for different failure modes
+ *
+ * ## Flow States
+ *
+ * The provider manages a two-step authentication flow:
+ *
+ * 1. **Start**: User enters their claim (email, phone, etc.)
+ * 2. **Code**: User enters the PIN code sent to their claim
+ *
+ * ## User Data
+ *
+ * ```ts
+ * success: async (ctx, value) => {
+ *   if (value.provider === "code") {
+ *     // User's email: value.claims.email
+ *     // User's phone (if provided): value.claims.phone
+ *     // Any other claims collected during the flow
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { Provider } from "./provider";
+/**
+ * Configuration options for the PIN code authentication provider.
+ *
+ * @template Claims - Type of claims collected during authentication (email, phone, etc.)
+ */
+export interface CodeProviderConfig<Claims extends Record<string, string> = Record<string, string>> {
+    /**
+     * The length of the generated PIN code.
+     * Common values are 4, 6, or 8 digits.
+     *
+     * @default 6
+     *
+     * @example
+     * ```ts
+     * {
+     *   length: 4 // 4-digit PIN for easier entry
+     * }
+     * ```
+     */
+    readonly length?: number;
+    /**
+     * Request handler for rendering the authentication UI.
+     * Handles both the initial claim collection and PIN code entry screens.
+     *
+     * @param req - The HTTP request object
+     * @param state - Current authentication state (start or code verification)
+     * @param form - Form data from POST requests (if any)
+     * @param error - Authentication error to display (if any)
+     * @returns Promise resolving to the authentication page response
+     *
+     * @example
+     * ```ts
+     * request: async (req, state, form, error) => {
+     *   if (state.type === 'start') {
+     *     return new Response(renderClaimForm(form, error))
+     *   } else {
+     *     return new Response(renderCodeForm(state.claims.email, error))
+     *   }
+     * }
+     * ```
+     */
+    request: (req: Request, state: CodeProviderState, form?: FormData, error?: CodeProviderError) => Promise<Response>;
+    /**
+     * Callback for sending PIN codes to users via their preferred method.
+     * Should handle delivery via email, SMS, or other communication channels.
+     *
+     * @param claims - User claims containing contact information
+     * @param code - The generated PIN code to send
+     *
+     * @example
+     * ```ts
+     * sendCode: async (claims, code) => {
+     *   await emailService.send({
+     *     to: claims.email,
+     *     subject: 'Your verification code',
+     *     text: `Your PIN code is: ${code}`
+     *   })
+     * }
+     * ```
+     */
+    sendCode: (claims: Claims, code: string) => Promise<void>;
+}
+/**
+ * Authentication flow states for the PIN code provider.
+ * The provider transitions between these states during authentication.
+ */
+export type CodeProviderState = {
+    /** Initial state: user enters their claims (email, phone, etc.) */
+    readonly type: "start";
+} | {
+    /** Code verification state: user enters the PIN code */
+    readonly type: "code";
+    /** Whether this is a code resend request */
+    readonly resend?: boolean;
+    /** The generated PIN code for verification */
+    readonly code: string;
+    /** User claims collected during the start phase */
+    readonly claims: Record<string, string>;
+};
+/**
+ * Possible errors during PIN code authentication.
+ */
+export type CodeProviderError = {
+    /** The entered PIN code is incorrect */
+    readonly type: "invalid_code";
+} | {
+    /** A user claim is invalid or missing */
+    readonly type: "invalid_claim";
+    /** The claim field that failed validation */
+    readonly key: string;
+    /** The invalid value or error description */
+    readonly value: string;
+};
+/**
+ * User data returned by successful PIN code authentication.
+ *
+ * @template Claims - Type of claims collected during authentication
+ */
+export interface CodeUserData<Claims extends Record<string, string> = Record<string, string>> {
+    /** The verified claims collected during authentication */
+    readonly claims: Claims;
+}
+/**
+ * Creates a PIN code authentication provider.
+ * Implements a flexible claim-based authentication flow with PIN verification.
+ *
+ * @template Claims - Type of claims to collect (email, phone, username, etc.)
+ * @param config - PIN code provider configuration
+ * @returns Provider instance implementing PIN code authentication
+ *
+ * @example
+ * ```ts
+ * // Email-based PIN authentication
+ * const emailCodeProvider = CodeProvider<{ email: string }>({
+ *   length: 6,
+ *   request: async (req, state, form, error) => {
+ *     if (state.type === 'start') {
+ *       return new Response(renderEmailForm(form?.get('email'), error))
+ *     } else {
+ *       return new Response(renderPinForm(state.claims.email, error, state.resend))
+ *     }
+ *   },
+ *   sendCode: async (claims, code) => {
+ *     if (!claims.email || !isValidEmail(claims.email)) {
+ *       return {
+ *         type: "invalid_claim",
+ *         key: "email",
+ *         value: "Invalid email address"
+ *       }
+ *     }
+ *
+ *     try {
+ *       await emailService.send(claims.email, `Your verification code: ${code}`)
+ *     } catch {
+ *       return {
+ *         type: "invalid_claim",
+ *         key: "delivery",
+ *         value: "Failed to send code"
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * // Multi-channel PIN authentication (email or phone)
+ * const flexibleCodeProvider = CodeProvider<{ email?: string; phone?: string }>({
+ *   length: 4,
+ *   request: async (req, state, form, error) => {
+ *     if (state.type === 'start') {
+ *       return new Response(renderContactForm(form, error))
+ *     } else {
+ *       const contact = state.claims.email || state.claims.phone
+ *       return new Response(renderPinForm(contact, error))
+ *     }
+ *   },
+ *   sendCode: async (claims, code) => {
+ *     try {
+ *       if (claims.email) {
+ *         await emailService.send(claims.email, `PIN: ${code}`)
+ *       } else if (claims.phone) {
+ *         await smsService.send(claims.phone, `PIN: ${code}`)
+ *       } else {
+ *         return {
+ *           type: "invalid_claim",
+ *           key: "email",
+ *           value: "Provide either email or phone number"
+ *         }
+ *       }
+ *     } catch {
+ *       return {
+ *         type: "invalid_claim",
+ *         key: "delivery",
+ *         value: "Failed to send code"
+ *       }
+ *     }
+ *   }
+ * })
+ *
+ * // Usage in issuer
+ * export default issuer({
+ *   providers: {
+ *     email: emailCodeProvider,
+ *     flexible: flexibleCodeProvider
+ *   },
+ *   success: async (ctx, value) => {
+ *     if (value.provider === "code") {
+ *       const email = value.claims.email
+ *       const phone = value.claims.phone
+ *
+ *       // Look up or create user based on verified claims
+ *       const userId = await findOrCreateUser({ email, phone })
+ *
+ *       return ctx.subject("user", { userId, email, phone })
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare const CodeProvider: <Claims extends Record<string, string> = Record<string, string>>(config: CodeProviderConfig<Claims>) => Provider<CodeUserData<Claims>>;
+/**
+ * Type helper for CodeProvider configuration options.
+ * @internal
+ */
+export type CodeProviderOptions = Parameters<typeof CodeProvider>[0];
+//# sourceMappingURL=code.d.ts.map

package/dist/types/provider/code.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code.d.ts","sourceRoot":"","sources":["../../../src/provider/code.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAE1C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAClC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAE9D;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IAExB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,EAAE,CACR,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,iBAAiB,EACxB,IAAI,CAAC,EAAE,QAAQ,EACf,KAAK,CAAC,EAAE,iBAAiB,KACrB,OAAO,CAAC,QAAQ,CAAC,CAAA;IAEtB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CACzD;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAC1B;IACA,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACrB,GACD;IACA,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACtC,CAAA;AAEJ;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAC1B;IACA,wCAAwC;IACxC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAC5B,GACD;IACA,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACrB,CAAA;AAEJ;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAC3F,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC1F,QAAQ,kBAAkB,CAAC,MAAM,CAAC,KAChC,QAAQ,CAAC,YAAY,CAAC,MAAM,CAAC,CA6G/B,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC,CAAA"}

package/dist/types/provider/discord.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Discord OAuth 2.0 authentication provider for Draft Auth.
+ * Provides access tokens for calling Discord APIs on behalf of users.
+ *
+ * ## Quick Setup
+ *
+ * ```ts
+ * import { DiscordProvider } from "@draftlab/auth/provider/discord"
+ *
+ * export default issuer({
+ *   basePath: "/auth", // Important for callback URL
+ *   providers: {
+ *     discord: DiscordProvider({
+ *       clientID: process.env.DISCORD_CLIENT_ID,
+ *       clientSecret: process.env.DISCORD_CLIENT_SECRET,
+ *       scopes: ["identify", "email", "guilds"]
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/discord/callback`
+ * - Production: `https://yourapp.com/auth/discord/callback`
+ *
+ * Register this URL in your Discord Developer Portal.
+ *
+ * ## Common Scopes
+ *
+ * - `identify` - Access to user's basic account information
+ * - `email` - Access to user's email address
+ * - `guilds` - Access to user's guilds (servers)
+ * - `guilds.join` - Ability to join user to guilds
+ * - `gdm.join` - Ability to join user to group DMs
+ * - `connections` - Access to user's connections (Steam, YouTube, etc.)
+ * - `guilds.members.read` - Read guild member information
+ * - `bot` - For bot applications (requires additional setup)
+ *
+ * ## User Data Access
+ *
+ * ```ts
+ * success: async (ctx, value) => {
+ *   if (value.provider === "discord") {
+ *     const accessToken = value.tokenset.access
+ *
+ *     // Fetch user information
+ *     const userResponse = await fetch('https://discord.com/api/users/@me', {
+ *       headers: { Authorization: `Bearer ${accessToken}` }
+ *     })
+ *     const user = await userResponse.json()
+ *
+ *     // Fetch user guilds (requires guilds scope)
+ *     const guildsResponse = await fetch('https://discord.com/api/users/@me/guilds', {
+ *       headers: { Authorization: `Bearer ${accessToken}` }
+ *     })
+ *     const guilds = await guildsResponse.json()
+ *
+ *     // User info: user.username + user.discriminator
+ *     // Avatar: `https://cdn.discordapp.com/avatars/${user.id}/${user.avatar}.png`
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { type Oauth2WrappedConfig } from "./oauth2";
+/**
+ * Configuration options for Discord OAuth 2.0 provider.
+ * Extends the base OAuth 2.0 configuration with Discord-specific documentation.
+ */
+export interface DiscordConfig extends Oauth2WrappedConfig {
+    /**
+     * Discord OAuth 2.0 client ID from Discord Developer Portal.
+     * Found in your Discord application settings.
+     *
+     * @example
+     * ```ts
+     * {
+     *   clientID: "1234567890123456789"
+     * }
+     * ```
+     */
+    readonly clientID: string;
+    /**
+     * Discord OAuth 2.0 client secret from Discord Developer Portal.
+     * Keep this secure and never expose it to client-side code.
+     *
+     * @example
+     * ```ts
+     * {
+     *   clientSecret: process.env.DISCORD_CLIENT_SECRET
+     * }
+     * ```
+     */
+    readonly clientSecret: string;
+    /**
+     * Discord OAuth scopes to request access for.
+     * Determines what data and actions your app can access.
+     *
+     * @example
+     * ```ts
+     * {
+     *   scopes: [
+     *     "identify",    // Basic user information
+     *     "email",       // Email address
+     *     "guilds",      // User's Discord servers
+     *     "connections"  // Connected accounts (Steam, etc.)
+     *   ]
+     * }
+     * ```
+     */
+    readonly scopes: string[];
+    /**
+     * Additional query parameters for Discord OAuth authorization.
+     * Useful for Discord-specific options like permissions.
+     *
+     * @example
+     * ```ts
+     * {
+     *   query: {
+     *     permissions: "8",        // Administrator permission
+     *     guild_id: "123456789",   // Pre-select specific guild
+     *     disable_guild_select: "true" // Disable guild selection
+     *   }
+     * }
+     * ```
+     */
+    readonly query?: Record<string, string>;
+}
+/**
+ * Creates a Discord OAuth 2.0 authentication provider.
+ * Use this when you need access tokens to call Discord APIs on behalf of the user.
+ *
+ * @param config - Discord OAuth 2.0 configuration
+ * @returns OAuth 2.0 provider configured for Discord
+ *
+ * @example
+ * ```ts
+ * // Basic Discord authentication
+ * const basicDiscord = DiscordProvider({
+ *   clientID: process.env.DISCORD_CLIENT_ID,
+ *   clientSecret: process.env.DISCORD_CLIENT_SECRET
+ * })
+ *
+ * // Discord with specific scopes
+ * const discordWithScopes = DiscordProvider({
+ *   clientID: process.env.DISCORD_CLIENT_ID,
+ *   clientSecret: process.env.DISCORD_CLIENT_SECRET,
+ *   scopes: [
+ *     "identify",
+ *     "email",
+ *     "guilds",
+ *     "connections"
+ *   ]
+ * })
+ *
+ * // Discord bot integration
+ * const discordBot = DiscordProvider({
+ *   clientID: process.env.DISCORD_CLIENT_ID,
+ *   clientSecret: process.env.DISCORD_CLIENT_SECRET,
+ *   scopes: ["bot", "guilds"],
+ *   query: {
+ *     permissions: "2048" // Send Messages permission
+ *   }
+ * })
+ *
+ * // Using the access token to fetch data
+ * export default issuer({
+ *   providers: { discord: discordWithScopes },
+ *   success: async (ctx, value) => {
+ *     if (value.provider === "discord") {
+ *       const token = value.tokenset.access
+ *
+ *       // Get user profile
+ *       const userRes = await fetch('https://discord.com/api/users/@me', {
+ *         headers: { Authorization: `Bearer ${token}` }
+ *       })
+ *       const user = await userRes.json()
+ *
+ *       // Get user guilds (if guilds scope granted)
+ *       const guildsRes = await fetch('https://discord.com/api/users/@me/guilds', {
+ *         headers: { Authorization: `Bearer ${token}` }
+ *       })
+ *       const guilds = await guildsRes.json()
+ *
+ *       return ctx.subject("user", {
+ *         discordId: user.id,
+ *         username: user.username,
+ *         discriminator: user.discriminator,
+ *         email: user.email,
+ *         avatar: user.avatar ? `https://cdn.discordapp.com/avatars/${user.id}/${user.avatar}.png` : null,
+ *         guildCount: guilds.length
+ *       })
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/discord/callback`
+ * - Production: `https://yourapp.com/auth/discord/callback`
+ *
+ * Register this URL in your Discord Developer Portal.
+ */
+export declare const DiscordProvider: (config: DiscordConfig) => import("./provider").Provider<import("./oauth2").Oauth2UserData>;
+//# sourceMappingURL=discord.d.ts.map

package/dist/types/provider/discord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discord.d.ts","sourceRoot":"","sources":["../../../src/provider/discord.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,EAAkB,KAAK,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAEnE;;;GAGG;AACH,MAAM,WAAW,aAAc,SAAQ,mBAAmB;IACzD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IAEzB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAE7B;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAA;IAEzB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,aAAa,qEASpD,CAAA"}

package/dist/types/provider/facebook.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Facebook OAuth 2.0 authentication provider for Draft Auth.
+ * Provides access tokens for calling Facebook Graph API on behalf of users.
+ *
+ * ## Quick Setup
+ *
+ * ```ts
+ * import { FacebookProvider } from "@draftlab/auth/provider/facebook"
+ *
+ * export default issuer({
+ *   basePath: "/auth", // Important for callback URL
+ *   providers: {
+ *     facebook: FacebookProvider({
+ *       clientID: process.env.FACEBOOK_APP_ID,
+ *       clientSecret: process.env.FACEBOOK_APP_SECRET,
+ *       scopes: ["email", "public_profile", "user_friends"]
+ *     })
+ *   }
+ * })
+ * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/facebook/callback`
+ * - Production: `https://yourapp.com/auth/facebook/callback`
+ *
+ * Register this URL in your Facebook App Dashboard.
+ *
+ * ## Configuration Options
+ *
+ * - Access tokens for Facebook Graph API calls
+ * - Support for various Facebook permissions
+ * - Access to user data, posts, friends, etc.
+ *
+ * ## Common Facebook Permissions
+ *
+ * - `public_profile` - Basic profile information (name, picture, etc.)
+ * - `email` - User's email address
+ * - `user_friends` - List of user's friends who also use your app
+ * - `user_posts` - User's posts on their timeline
+ * - `user_photos` - User's photos and albums
+ * - `pages_read_engagement` - Read engagement data for Pages
+ *
+ * ## User Data Access
+ *
+ * ```ts
+ * success: async (ctx, value) => {
+ *   if (value.provider === "facebook") {
+ *     const accessToken = value.tokenset.access
+ *
+ *     // Fetch user profile from Graph API
+ *     const profileResponse = await fetch(
+ *       `https://graph.facebook.com/me?fields=id,name,email,picture&access_token=${accessToken}`
+ *     )
+ *     const profile = await profileResponse.json()
+ *
+ *     // User info: `${profile.name} (${profile.email})`
+ *     // Facebook ID: profile.id
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import { type Oauth2WrappedConfig } from "./oauth2";
+/**
+ * Configuration options for Facebook OAuth 2.0 provider.
+ * Extends the base OAuth 2.0 configuration with Facebook-specific documentation.
+ */
+export interface FacebookConfig extends Oauth2WrappedConfig {
+    /**
+     * Facebook App ID from your Facebook App Dashboard.
+     * This is the public identifier for your Facebook application.
+     *
+     * @example
+     * ```ts
+     * {
+     *   clientID: "1234567890123456"
+     * }
+     * ```
+     */
+    readonly clientID: string;
+    /**
+     * Facebook App Secret from your Facebook App Dashboard.
+     * Keep this secure and never expose it to client-side code.
+     *
+     * @example
+     * ```ts
+     * {
+     *   clientSecret: process.env.FACEBOOK_APP_SECRET
+     * }
+     * ```
+     */
+    readonly clientSecret: string;
+    /**
+     * Facebook permissions to request during login.
+     * Determines what data your app can access from the user's Facebook account.
+     *
+     * @example
+     * ```ts
+     * {
+     *   scopes: [
+     *     "email",           // User's email address
+     *     "public_profile",  // Basic profile info
+     *     "user_friends",    // User's friends list
+     *     "user_posts"       // User's timeline posts
+     *   ]
+     * }
+     * ```
+     */
+    readonly scopes: string[];
+    /**
+     * Additional query parameters for Facebook OAuth authorization.
+     * Useful for Facebook-specific options like response type or display mode.
+     *
+     * @example
+     * ```ts
+     * {
+     *   query: {
+     *     display: "popup",           // Show login in popup
+     *     auth_type: "rerequest",     // Force permission re-request
+     *     state: "custom-state"       // Custom state parameter
+     *   }
+     * }
+     * ```
+     */
+    readonly query?: Record<string, string>;
+}
+/**
+ * Creates a Facebook OAuth 2.0 authentication provider.
+ * Use this when you need access tokens to call Facebook Graph API on behalf of the user.
+ *
+ * @param config - Facebook OAuth 2.0 configuration
+ * @returns OAuth 2.0 provider configured for Facebook
+ *
+ * @example
+ * ```ts
+ * // Basic Facebook authentication
+ * const basicFacebook = FacebookProvider({
+ *   clientID: process.env.FACEBOOK_APP_ID,
+ *   clientSecret: process.env.FACEBOOK_APP_SECRET,
+ *   scopes: ["email", "public_profile"]
+ * })
+ *
+ * // Facebook with extended permissions
+ * const extendedFacebook = FacebookProvider({
+ *   clientID: process.env.FACEBOOK_APP_ID,
+ *   clientSecret: process.env.FACEBOOK_APP_SECRET,
+ *   scopes: [
+ *     "email",
+ *     "public_profile",
+ *     "user_friends",
+ *     "user_posts",
+ *     "user_photos"
+ *   ],
+ *   query: {
+ *     display: "popup",
+ *     auth_type: "rerequest" // Force permission approval
+ *   }
+ * })
+ *
+ * // Using the access token for Graph API calls
+ * export default issuer({
+ *   providers: { facebook: extendedFacebook },
+ *   success: async (ctx, value) => {
+ *     if (value.provider === "facebook") {
+ *       const token = value.tokenset.access
+ *
+ *       // Get user profile with custom fields
+ *       const profileRes = await fetch(
+ *         `https://graph.facebook.com/me?fields=id,name,email,picture.width(200),friends&access_token=${token}`
+ *       )
+ *       const profile = await profileRes.json()
+ *
+ *       // Get user's posts (if permission granted)
+ *       const postsRes = await fetch(
+ *         `https://graph.facebook.com/me/posts?access_token=${token}`
+ *       )
+ *       const posts = await postsRes.json()
+ *
+ *       return ctx.subject("user", {
+ *         facebookId: profile.id,
+ *         name: profile.name,
+ *         email: profile.email,
+ *         picture: profile.picture?.data?.url,
+ *         friendsCount: profile.friends?.summary?.total_count || 0,
+ *         postsCount: posts.data?.length || 0
+ *       })
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/facebook/callback`
+ * - Production: `https://yourapp.com/auth/facebook/callback`
+ *
+ * Register this URL in your Facebook App Dashboard.
+ */
+export declare const FacebookProvider: (config: FacebookConfig) => import("./provider").Provider<import("./oauth2").Oauth2UserData>;
+//# sourceMappingURL=facebook.d.ts.map