import type { KeyValueStorage } from '@agentuity/keyvalue';
import type { OAuthFlowConfig, OAuthTokenResponse, StoredToken } from './types.ts';
/**
 * Check whether a stored token's access token has expired.
 *
 * @param token - The stored token to check
 * @returns true if the token has an expires_at timestamp that is in the past
 *
 * @example
 * ```typescript
 * const token = await storage.get('user:123');
 * if (token && isTokenExpired(token)) {
 *   // Token is expired and auto-refresh wasn't available
 * }
 * ```
 */
export declare function isTokenExpired(token: StoredToken): boolean;
/**
 * Options for configuring a TokenStorage instance.
 */
export interface TokenStorageOptions {
    /**
     * OAuth configuration for auto-refresh and token revocation.
     * If not provided, auto-refresh on get() and server-side revocation on invalidate() are disabled.
     */
    config?: OAuthFlowConfig;
    /**
     * KV namespace for storing tokens. Defaults to 'oauth-tokens'.
     */
    namespace?: string;
    /**
     * Key prefix prepended to all storage keys.
     * Useful for scoping tokens by application or tenant.
     */
    prefix?: string;
}
/**
 * Interface for storing, retrieving, and invalidating OAuth tokens.
 *
 * Implementations handle persistence and may support automatic token refresh
 * on retrieval and server-side revocation on invalidation.
 */
export interface TokenStorage {
    /**
     * Retrieve a stored token by key.
     *
     * If the token is expired and a refresh_token is available (and config is provided),
     * the token is automatically refreshed, stored, and the new token is returned.
     * If auto-refresh fails, the expired token is returned so the caller can decide
     * how to handle it (check with {@link isTokenExpired}).
     *
     * @param key - The storage key (e.g. a user ID or session ID)
     * @returns The stored token, or null if no token exists for the key
     */
    get(key: string): Promise<StoredToken | null>;
    /**
     * Store a token response from a token exchange or refresh.
     *
     * Automatically computes `expires_at` from `expires_in` if present.
     *
     * @param key - The storage key (e.g. a user ID or session ID)
     * @param token - The OAuth token response to store
     */
    set(key: string, token: OAuthTokenResponse): Promise<void>;
    /**
     * Invalidate a stored token: revoke it server-side and remove from storage.
     *
     * If config is provided, the refresh token (or access token as fallback)
     * is revoked via the token revocation endpoint. Revocation is best-effort —
     * the token is removed from storage regardless of whether revocation succeeds.
     *
     * @param key - The storage key to invalidate
     * @returns The token that was removed, or null if no token existed
     */
    invalidate(key: string): Promise<StoredToken | null>;
}
/**
 * Token storage backed by Agentuity's Key-Value storage service.
 *
 * Stores tokens as JSON in a KV namespace. Supports automatic token refresh
 * on retrieval when tokens expire (if OAuth config is provided).
 *
 * @example
 * ```typescript
 * import { KeyValueTokenStorage } from '@agentuity/server';
 * import { KeyValueClient } from '@agentuity/keyvalue';
 *
 * const kv = new KeyValueClient();
 *
 * // Create storage with auto-refresh enabled
 * const storage = new KeyValueTokenStorage(kv, {
 *   config: { issuer: 'https://auth.example.com' },
 * });
 *
 * // Store a token after initial exchange
 * await storage.set('user:123', tokenResponse);
 *
 * // Retrieve — auto-refreshes if expired
 * const token = await storage.get('user:123');
 *
 * // Logout — revokes server-side and removes from storage
 * await storage.invalidate('user:123');
 * ```
 */
export declare class KeyValueTokenStorage implements TokenStorage {
    #private;
    constructor(kv: KeyValueStorage, options?: TokenStorageOptions);
    get(key: string): Promise<StoredToken | null>;
    set(key: string, token: OAuthTokenResponse): Promise<void>;
    invalidate(key: string): Promise<StoredToken | null>;
}
//# sourceMappingURL=token-storage.d.ts.map