@xivdyetools/core 1.3.7

package/dist/services/APIService.d.ts

@@ -0,0 +1,246 @@
+/**
+ * @xivdyetools/core - API Service
+ *
+ * Universalis API integration with caching and debouncing
+ * Environment-agnostic with pluggable cache backends
+ *
+ * @module services/APIService
+ */
+import type { PriceData, CachedData, Logger } from '../types/index.js';
+/**
+ * Fetch client interface for HTTP requests
+ * Implement this for different fetch implementations (global fetch, node-fetch, mocked fetch, etc.)
+ *
+ * Refactored for testability: Allows injecting mock fetch clients
+ */
+export interface FetchClient {
+    /**
+     * Perform HTTP fetch request
+     */
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+/**
+ * Default fetch client using global fetch API
+ */
+export declare class DefaultFetchClient implements FetchClient {
+    fetch(url: string, options?: RequestInit): Promise<Response>;
+}
+/**
+ * Rate limiter interface for controlling request frequency
+ * Implement this for different rate limiting strategies
+ *
+ * Refactored for testability: Allows injecting custom rate limiters or disabling rate limiting for tests
+ */
+export interface RateLimiter {
+    /**
+     * Wait if needed to respect rate limits
+     */
+    waitIfNeeded(): Promise<void>;
+    /**
+     * Record that a request was made (updates internal state)
+     */
+    recordRequest(): void;
+}
+/**
+ * Default rate limiter with configurable minimum delay between requests
+ */
+export declare class DefaultRateLimiter implements RateLimiter {
+    private minDelay;
+    private lastRequestTime;
+    /**
+     * Constructor with optional minimum delay
+     * @param minDelay Minimum milliseconds between requests (default: API_RATE_LIMIT_DELAY)
+     */
+    constructor(minDelay?: number);
+    waitIfNeeded(): Promise<void>;
+    recordRequest(): void;
+}
+/**
+ * Cache backend interface
+ * Implement this for different storage backends (localStorage, Redis, Memory, etc.)
+ */
+export interface ICacheBackend {
+    /**
+     * Get item from cache
+     */
+    get(key: string): Promise<CachedData<PriceData> | null> | CachedData<PriceData> | null;
+    /**
+     * Set item in cache
+     */
+    set(key: string, value: CachedData<PriceData>): Promise<void> | void;
+    /**
+     * Delete item from cache
+     */
+    delete(key: string): Promise<void> | void;
+    /**
+     * Clear all cache entries
+     */
+    clear(): Promise<void> | void;
+    /**
+     * Get all cache keys
+     */
+    keys(): Promise<string[]> | string[];
+}
+/**
+ * In-memory cache backend (default, no persistence)
+ */
+export declare class MemoryCacheBackend implements ICacheBackend {
+    private cache;
+    get(key: string): CachedData<PriceData> | null;
+    set(key: string, value: CachedData<PriceData>): void;
+    delete(key: string): void;
+    clear(): void;
+    keys(): string[];
+}
+/**
+ * Configuration options for APIService
+ */
+export interface APIServiceOptions {
+    /**
+     * Cache backend implementation (defaults to memory cache)
+     */
+    cacheBackend?: ICacheBackend;
+    /**
+     * Fetch client implementation (defaults to global fetch)
+     */
+    fetchClient?: FetchClient;
+    /**
+     * Rate limiter implementation (defaults to standard rate limiting)
+     */
+    rateLimiter?: RateLimiter;
+    /**
+     * Logger for API operations (defaults to NoOpLogger)
+     */
+    logger?: Logger;
+}
+/**
+ * Service for Universalis API integration
+ * Handles price data fetching with caching and debouncing
+ *
+ * Refactored for testability: Supports dependency injection of cache, fetch client, and rate limiter
+ *
+ * @example
+ * // With default implementations (memory cache, global fetch, standard rate limiting)
+ * const apiService = new APIService();
+ *
+ * // With custom cache backend (e.g., Redis)
+ * const redisCache = new RedisCacheBackend(redisClient);
+ * const apiService = new APIService(redisCache);
+ *
+ * // With custom fetch client for testing
+ * const mockFetch = new MockFetchClient();
+ * const apiService = new APIService(undefined, mockFetch);
+ *
+ * // With custom rate limiter (e.g., no rate limiting for tests)
+ * const noRateLimit = new NoOpRateLimiter();
+ * const apiService = new APIService(undefined, undefined, noRateLimit);
+ *
+ * // Fetch price data
+ * const priceData = await apiService.getPriceData(itemID, worldID, dataCenterID);
+ *
+ * // With custom logger for debugging
+ * import { ConsoleLogger } from 'xivdyetools-core';
+ * const apiService = new APIService({ logger: ConsoleLogger });
+ */
+export declare class APIService {
+    private cache;
+    private fetchClient;
+    private rateLimiter;
+    private pendingRequests;
+    private readonly logger;
+    /**
+     * Constructor with optional dependency injection
+     * @param options Configuration options or legacy cache backend
+     */
+    constructor(options?: ICacheBackend | APIServiceOptions, fetchClient?: FetchClient, rateLimiter?: RateLimiter);
+    /**
+     * Get price from cache if available and not expired
+     * Validates cache version and checksum
+     */
+    private getCachedPrice;
+    /**
+     * Set price in cache with version and checksum
+     */
+    private setCachedPrice;
+    /**
+     * Clear cache
+     */
+    clearCache(): Promise<void>;
+    /**
+     * Get cache stats
+     */
+    getCacheStats(): Promise<{
+        size: number;
+        keys: string[];
+    }>;
+    /**
+     * Fetch price data for a dye from Universalis API
+     * Implements caching, debouncing, and retry logic
+     */
+    getPriceData(itemID: number, worldID?: number, dataCenterID?: string): Promise<PriceData | null>;
+    /**
+     * Internal method to fetch price data from API
+     */
+    private fetchPriceData;
+    /**
+     * Fetch with timeout and size limits
+     * Uses injected fetch client for better testability
+     */
+    private fetchWithTimeout;
+    /**
+     * Parse and validate API response
+     */
+    private parseApiResponse;
+    /**
+     * Build API URL for item price query
+     */
+    private buildApiUrl;
+    /**
+     * Sanitize datacenter ID to prevent cache key injection.
+     * Only allows alphanumeric characters (a-z, A-Z, 0-9).
+     */
+    private sanitizeDataCenterId;
+    /**
+     * Build cache key from parameters
+     * SECURITY: Uses type prefixes to prevent cache key collisions
+     * Format: itemID:type:value where type is 'dc', 'world', or 'global'
+     * This prevents crafted dataCenterID values from colliding with other key patterns
+     */
+    private buildCacheKey;
+    /**
+     * Fetch prices for multiple items
+     * PERFORMANCE: Uses Promise.allSettled for parallel requests
+     * Failed requests are logged but don't block other results
+     */
+    getPricesForItems(itemIDs: number[]): Promise<Map<number, PriceData>>;
+    /**
+     * Fetch prices for dyes in a specific data center
+     * PERFORMANCE: Uses Promise.allSettled for parallel requests
+     */
+    getPricesForDataCenter(itemIDs: number[], dataCenterID: string): Promise<Map<number, PriceData>>;
+    /**
+     * Check if Universalis API is available
+     * Uses injected fetch client
+     */
+    isAPIAvailable(): Promise<boolean>;
+    /**
+     * Get API status information
+     */
+    getAPIStatus(): Promise<{
+        available: boolean;
+        latency: number;
+    }>;
+    /**
+     * Format price for display (FFXIV Gil format: 69,420G)
+     */
+    static formatPrice(price: number): string;
+    /**
+     * Calculate price trend (simplified)
+     */
+    static getPriceTrend(currentPrice: number, previousPrice: number): {
+        trend: 'up' | 'down' | 'stable';
+        change: number;
+        changePercent: number;
+    };
+}
+//# sourceMappingURL=APIService.d.ts.map

package/dist/services/APIService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"APIService.d.ts","sourceRoot":"","sources":["../../src/services/APIService.ts"],"names":[],"mappings":"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"}