/**
 * Yahoo Fantasy Sports API Client
 *
 * Main entry point for the Yahoo Fantasy Sports API wrapper.
 * Provides access to all fantasy sports resources with full TypeScript support.
 *
 * @module
 *
 * @example
 * ```typescript
 * import { YahooFantasySportsClient } from 'yfs-api';
 *
 * const yfs = new YahooFantasySportsClient({
 *   clientId: process.env.YAHOO_CLIENT_ID!,
 *   clientSecret: process.env.YAHOO_CLIENT_SECRET!,
 *   redirectUri: 'https://example.com/callback', // or 'oob'
 * });
 *
 * // Step 1: Get authorization URL
 * const authUrl = yfs.getAuthUrl();
 * console.log('Visit this URL and authorize:', authUrl);
 *
 * // Step 2: User authorizes and gets redirected with code
 * // (Alternatively, ask the user to input the code manually)
 * const code = '...'; // User authorization code from yahoo
 *
 * // Step 3: Exchange code for tokens
 * await yfs.authenticate(code);
 *
 * // Make API calls
 * const league = await yfs.api().league('423.l.12345').get();
 * const roster = await yfs.api().team('423.l.12345.t.1').roster().get();
 * ```
 */
import { type OAuth2AuthorizationRequest, type OAuth2Tokens } from '../auth/oauth2.js';
import { type ApiRoot } from '../resources/api.js';
import { type RequestOptions } from './http.js';
/**
 * Configuration options for Yahoo Fantasy Sports API client
 *
 * Supports two authentication modes:
 * 1. User Authentication (OAuth 2.0) - Full access to all endpoints
 * 2. Public Mode (OAuth 1.0) - Access to public endpoints only
 */
export interface Config {
    /**
     * OAuth client ID (Consumer Key) from Yahoo Developer
     */
    clientId: string;
    /**
     * OAuth client secret (Consumer Secret) from Yahoo Developer
     */
    clientSecret: string;
    /**
     * Enable public mode (OAuth 1.0 2-legged authentication)
     *
     * When true:
     * - Uses OAuth 1.0 with HMAC-SHA1 signing
     * - No user authorization required
     * - Access limited to public endpoints only
     * - redirectUri is not required
     *
     * When false (default):
     * - Uses OAuth 2.0 Authorization Code Grant
     * - Requires user authorization
     * - Full access to all endpoints
     * - redirectUri is required
     *
     * @default false
     */
    publicMode?: boolean;
    /**
     * Redirect URI for OAuth 2.0 flow
     * Must match the URI configured in Yahoo Developer app
     *
     * Required when publicMode is false (default)
     * Not used when publicMode is true
     */
    redirectUri?: string;
    /**
     * Optional: Access token if already authenticated
     * Only used in user authentication mode (publicMode: false)
     */
    accessToken?: string;
    /**
     * Optional: Refresh token for getting new access tokens
     * Only used in user authentication mode (publicMode: false)
     */
    refreshToken?: string;
    /**
     * Optional: Token expiration timestamp (milliseconds since epoch)
     * Only used in user authentication mode (publicMode: false)
     */
    expiresAt?: number;
    /**
     * Optional: Enable debug logging
     * @default false
     */
    debug?: boolean;
    /**
     * Optional: Request timeout in milliseconds
     * @default 30000
     */
    timeout?: number;
    /**
     * Optional: Maximum retry attempts
     * @default 3
     */
    maxRetries?: number;
}
/**
 * Callback interface for storing and retrieving OAuth 2.0 tokens
 * Implement this to persist tokens between sessions
 */
export interface TokenStorage {
    /**
     * Save tokens
     */
    save(tokens: OAuth2Tokens): Promise<void> | void;
    /**
     * Load saved tokens
     */
    load(): Promise<OAuth2Tokens | null> | OAuth2Tokens | null;
    /**
     * Clear saved tokens
     */
    clear(): Promise<void> | void;
}
/**
 * Main Yahoo Fantasy Sports API client
 *
 * Provides access to Yahoo Fantasy Sports through a fluent resource API.
 *
 * @example
 * ```typescript
 * const yfs = new YahooFantasySportsClient({
 *   clientId: 'your-client-id',
 *   clientSecret: 'your-client-secret',
 *   redirectUri: 'https://example.com/callback',
 * });
 *
 * // Step 1: Get authorization URL
 * const authUrl = yfs.getAuthUrl();
 * console.log('Visit this URL and authorize:', authUrl);
 *
 * // Step 2: User authorizes and gets redirected with code
 * // Extract code from redirect: ?code=AUTHORIZATION_CODE
 *
 * // Step 3: Complete authentication
 * await yfs.authenticate(code);
 *
 * // Use the resource builders
 * const league = await yfs.api().league('423.l.12345').get();
 * const teams = await yfs.api().league('423.l.12345').teams().get();
 * ```
 */
export declare class YahooFantasySportsClient {
    private config;
    private oauth2Client?;
    private oauth1Client?;
    private httpClient;
    private tokenStorage?;
    private tokens?;
    private refreshInFlight?;
    /**
     * Creates a new Yahoo Fantasy Sports API client
     *
     * @param config - Configuration options
     * @param tokenStorage - Optional token storage implementation
     * @throws ConfigError - If required configuration is missing or invalid
     *
     * @example
     * ```typescript
     * const yfs = new YahooFantasySportsClient({
     *   clientId: process.env.YAHOO_CLIENT_ID!,
     *   clientSecret: process.env.YAHOO_CLIENT_SECRET!,
     *   redirectUri: 'https://example.com/callback',
     *   debug: true, // Optional: enable debug logging
     * });
     * ```
     *
     * @example With token storage
     * ```typescript
     * const storage: TokenStorage = {
     *   async save(tokens) {
     *     await fs.writeFile('tokens.json', JSON.stringify(tokens));
     *   },
     *   async load() {
     *     try {
     *       const data = await fs.readFile('tokens.json', 'utf-8');
     *       return JSON.parse(data);
     *     } catch {
     *       return null;
     *     }
     *   },
     *   async clear() {
     *     await fs.unlink('tokens.json');
     *   },
     * };
     *
     * const yfs = new YahooFantasySportsClient(config, storage);
     *
     * // Try to load existing tokens
     * await yfs.loadTokens();
     * ```
     */
    constructor(config: Config, tokenStorage?: TokenStorage);
    /**
     * Create a new resource API root
     *
     * A type-safe, chainable API for Yahoo Fantasy resource queries.
     * Provides resource-specific builders with path-safe chaining.
     *
     * @returns A new ApiRoot instance
     *
     * @example Query league settings
     * ```typescript
     * const league = await yfs.api()
     *   .league('423.l.12345')
     *   .include('settings')
     *   .get();
     * ```
     *
     * @example Query players with filters
     * ```typescript
     * const players = await yfs.api()
     *   .league('423.l.12345')
     *   .players()
     *   .position('C')
     *   .status('FA')
     *   .count(25)
     *   .get();
     * ```
     *
     * @example Query team roster
     * ```typescript
     * const roster = await yfs.api()
     *   .team('423.l.12345.t.1')
     *   .roster()
     *   .week(10)
     *   .get();
     * ```
     *
     * @example Query specific games
     * ```typescript
     * const games = await yfs.api()
     *   .games(['nhl', 'nfl'])
     *   .get();
     * ```
     *
     * @example Query user's games
     * ```typescript
     * const userGames = await yfs.api()
     *   .users()
     *   .games()
     *   .get();
     * ```
     */
    api(): ApiRoot;
    /** Returns an unparsed Yahoo XML response without changing typed API calls. */
    requestRawXml(path: string, options?: RequestOptions): Promise<string>;
    /**
     * Gets the authorization URL for the OAuth 2.0 flow
     *
     * Only available in user authentication mode (not in public mode).
     *
     * Step 1 of the OAuth flow. The user must visit this URL and authorize the application.
     * After authorization, Yahoo will redirect to your redirectUri with a code parameter.
     *
     * @param state - Optional state parameter for CSRF protection
     * @param language - Optional language code (default: 'en-us')
     * @returns Authorization URL that the user must visit
     * @throws ConfigError - If called in public mode
     *
     * @example
     * ```typescript
     * const authUrl = yfs.getAuthUrl('random-state-string');
     * console.log('Please visit:', authUrl);
     * console.log('After authorizing, you will be redirected with a code parameter.');
     * ```
     */
    getAuthUrl(state?: string, language?: string): string;
    createAuthorizationRequest(language?: string): OAuth2AuthorizationRequest;
    validateAuthorizationState(expected: string, received: string | null | undefined): void;
    /**
     * Completes authentication with the authorization code
     *
     * Step 2 of the OAuth flow. After the user authorizes and is redirected with a code,
     * call this method to exchange it for access and refresh tokens.
     *
     * @param code - Authorization code from Yahoo OAuth redirect
     * @throws AuthenticationError - If authentication fails
     *
     * @example
     * ```typescript
     * const authUrl = yfs.getAuthUrl();
     * console.log('Visit:', authUrl);
     *
     * // After user authorizes and is redirected to:
     * // https://your-redirect-uri?code=AUTHORIZATION_CODE
     *
     * const code = '...'; // Extract from redirect URL
     * await yfs.authenticate(code);
     *
     * console.log('Authenticated successfully!');
     * ```
     */
    /**
     * Completes authentication with the authorization code
     *
     * Only available in user authentication mode (not in public mode).
     *
     * Step 2 of the OAuth flow. After the user authorizes and is redirected with a code,
     * call this method to exchange it for access and refresh tokens.
     *
     * @param code - Authorization code from Yahoo OAuth redirect
     * @throws AuthenticationError - If authentication fails
     * @throws ConfigError - If called in public mode
     *
     * @example
     * ```typescript
     * const authUrl = yfs.getAuthUrl();
     * console.log('Visit:', authUrl);
     *
     * // After user authorizes and is redirected to:
     * // https://your-redirect-uri?code=AUTHORIZATION_CODE
     *
     * const code = '...'; // Extract from redirect URL
     * await yfs.authenticate(code);
     *
     * console.log('Authenticated successfully!');
     * ```
     */
    authenticate(code: string): Promise<void>;
    /**
     * Loads tokens from storage
     *
     * If a TokenStorage implementation was provided, this loads previously saved tokens.
     *
     * @returns True if tokens were loaded, false otherwise
     *
     * @example
     * ```typescript
     * const yfs = new YahooFantasySportsClient(config, storage);
     *
     * if (await yfs.loadTokens()) {
     *   console.log('Using saved tokens');
     * } else {
     *   console.log('No saved tokens, need to authenticate');
     *   const authUrl = yfs.getAuthUrl();
     *   // ... authenticate
     * }
     * ```
     */
    loadTokens(): Promise<boolean>;
    /**
     * Refreshes the access token using the refresh token
     *
     * Only available in user authentication mode (not in public mode).
     *
     * OAuth 2.0 access tokens expire after 1 hour. Use this method to get a new access token
     * without requiring the user to re-authenticate.
     *
     * Note: The HttpClient automatically refreshes tokens before making requests,
     * so you typically don't need to call this manually.
     *
     * @throws AuthenticationError - If refresh fails
     * @throws ConfigError - If no refresh token is available or if called in public mode
     *
     * @example
     * ```typescript
     * try {
     *   await yfs.refreshToken();
     *   console.log('Token refreshed successfully');
     * } catch (error) {
     *   console.log('Refresh failed, need to re-authenticate');
     *   await yfs.authenticate(code);
     * }
     * ```
     */
    refreshToken(): Promise<void>;
    /**
     * Checks if the client is currently authenticated
     *
     * In public mode (OAuth 1.0), always returns true since no user auth is needed.
     * In user auth mode (OAuth 2.0), returns true if valid access tokens exist.
     *
     * @returns True if the client can make authenticated requests
     *
     * @example
     * ```typescript
     * if (!yfs.isAuthenticated()) {
     *   await yfs.authenticate(code);
     * }
     * ```
     */
    isAuthenticated(): boolean;
    /**
     * Checks if the access token is expired or will expire soon
     *
     * Only applicable in user authentication mode (OAuth 2.0).
     * In public mode (OAuth 1.0), always returns false (tokens don't expire).
     *
     * @param bufferSeconds - Time buffer in seconds before actual expiration (default: 60)
     * @returns True if the token is expired or will expire within the buffer time
     *
     * @example
     * ```typescript
     * if (yfs.isTokenExpired()) {
     *   await yfs.refreshToken();
     * }
     * ```
     */
    isTokenExpired(bufferSeconds?: number): boolean;
    /**
     * Gets the current OAuth 2.0 tokens
     *
     * @returns Current tokens or null if not authenticated
     *
     * @example
     * ```typescript
     * const tokens = yfs.getTokens();
     * if (tokens) {
     *   // Save tokens for later use
     *   await saveToDatabase(tokens);
     * }
     * ```
     */
    getTokens(): OAuth2Tokens | null;
    /**
     * Clears stored authentication tokens
     *
     * @example
     * ```typescript
     * await yfs.logout();
     * console.log('Logged out successfully');
     * ```
     */
    logout(): Promise<void>;
    /**
     * Sets OAuth tokens (internal method)
     */
    private setTokens;
    private refreshTokens;
}
//# sourceMappingURL=yahoo.d.ts.map