@sudowealth/schwab-api/dist/auth/adapters/kv-token-store.d.ts

TypeScript client for Charles Schwab API with OAuth support, market data, trading functionality, and complete type safety

import { type TokenData } from '../types.js';
/**
 * Cloudflare KV namespace interface
 * This matches the actual KV API from Cloudflare Workers
 */
export interface KVNamespace {
    get(key: string): Promise<string | null>;
    put(key: string, value: string, options?: {
        expirationTtl?: number;
    }): Promise<void>;
    delete(key: string): Promise<void>;
}
/**
 * Token identifiers for key generation
 */
export interface TokenIdentifiers {
    /**
     * Schwab user ID (preferred identifier)
     */
    schwabUserId?: string;
    /**
     * OAuth client ID (fallback identifier)
     */
    clientId?: string;
    /**
     * Custom identifier
     */
    customId?: string;
}
/**
 * Configuration options for KV token store
 */
export interface KVTokenStoreOptions {
    /**
     * Prefix for all keys in KV
     * @default 'token:'
     */
    keyPrefix?: string;
    /**
     * TTL for tokens in seconds
     * @default 2678400 (31 days)
     */
    ttl?: number;
    /**
     * Whether to automatically migrate tokens between keys
     * @default true
     */
    autoMigrate?: boolean;
}
/**
 * Token store implementation for Cloudflare KV
 *
 * This provides a robust token persistence layer with:
 * - Consistent key generation
 * - Automatic token migration
 * - TTL management
 * - Atomic operations
 *
 * @example
 * ```typescript
 * const store = new KVTokenStore(env.OAUTH_KV);
 *
 * // Use with EnhancedTokenManager
 * const auth = new EnhancedTokenManager({
 *   clientId: 'your-client-id',
 *   clientSecret: 'your-client-secret',
 *   redirectUri: 'your-redirect-uri',
 *   load: () => store.load({ clientId: 'your-client-id' }),
 *   save: (tokens) => store.save({ clientId: 'your-client-id' }, tokens)
 * });
 * ```
 */
export declare class KVTokenStore {
    private readonly kv;
    private readonly keyPrefix;
    private readonly ttl;
    private readonly autoMigrate;
    constructor(kv: KVNamespace, options?: KVTokenStoreOptions);
    /**
     * Generate a consistent KV key from token identifiers
     * Priority: customId > schwabUserId > clientId
     *
     * @param ids Token identifiers
     * @returns The generated key
     * @throws Error if no identifier is provided
     */
    generateKey(ids: TokenIdentifiers): string;
    /**
     * Load tokens from KV storage
     * Automatically handles migration between different key schemes
     *
     * @param ids Token identifiers to load
     * @returns Token data if found, null otherwise
     */
    load(ids: TokenIdentifiers): Promise<TokenData | null>;
    /**
     * Save tokens to KV storage
     *
     * @param ids Token identifiers for key generation
     * @param tokens Token data to save
     */
    save(ids: TokenIdentifiers, tokens: TokenData): Promise<void>;
    /**
     * Delete tokens from KV storage
     *
     * @param ids Token identifiers for key generation
     */
    delete(ids: TokenIdentifiers): Promise<void>;
    /**
     * Migrate tokens from one key to another
     *
     * @param fromIds Source token identifiers
     * @param toIds Destination token identifiers
     * @returns True if migration was successful, false if source not found
     */
    migrate(fromIds: TokenIdentifiers, toIds: TokenIdentifiers): Promise<boolean>;
    /**
     * Create load and save functions bound to specific identifiers
     * This is useful for integration with EnhancedTokenManager
     *
     * @param ids Token identifiers to bind
     * @returns Object with bound load and save functions
     */
    createBoundFunctions(ids: TokenIdentifiers): {
        load: () => Promise<TokenData | null>;
        save: (tokens: TokenData) => Promise<void>;
    };
    /**
     * Sanitize a key for logging (show prefix and suffix only)
     */
    private sanitizeKeyForLog;
}
/**
 * Create a KV token store with default options
 *
 * @param kv KV namespace
 * @param options Optional configuration
 * @returns Configured KV token store instance
 */
export declare function createKVTokenStore(kv: KVNamespace, options?: KVTokenStoreOptions): KVTokenStore;