@http-client-toolkit/core 0.0.1

package/lib/index.d.ts

@@ -0,0 +1,382 @@
+import { z } from 'zod';
+
+/**
+ * Interface for caching API responses with TTL support
+ */
+interface CacheStore<T = unknown> {
+    /**
+     * Retrieve a cached value by hash key
+     * @param hash The hash key of the cached item
+     * @returns The cached value or undefined if not found or expired
+     */
+    get(hash: string): Promise<T | undefined>;
+    /**
+     * Store a value in the cache with a TTL
+     * @param hash The hash key for the cached item
+     * @param value The value to cache
+     * @param ttlSeconds TTL in seconds after which the item expires
+     */
+    set(hash: string, value: T, ttlSeconds: number): Promise<void>;
+    /**
+     * Remove a cached item by hash key
+     * @param hash The hash key of the cached item
+     */
+    delete(hash: string): Promise<void>;
+    /**
+     * Clear all cached items
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * Interface for deduplicating concurrent API requests
+ */
+interface DedupeStore<T = unknown> {
+    /**
+     * Wait for the result of an existing request if one is in progress
+     * @param hash The hash key of the request
+     * @returns The result if found, otherwise undefined
+     */
+    waitFor(hash: string): Promise<T | undefined>;
+    /**
+     * Register a new request and get a job ID
+     * @param hash The hash key of the request
+     * @returns A unique job ID for this request
+     */
+    register(hash: string): Promise<string>;
+    /**
+     * Atomically register or join an in-flight request.
+     *
+     * When provided, this allows callers to determine ownership and guarantees
+     * that only one caller executes the upstream request while others wait.
+     * Implementations that do not provide this method remain compatible, but
+     * may allow duplicate upstream requests under extreme races.
+     *
+     * @param hash The hash key of the request
+     * @returns The job id and whether the caller owns execution
+     */
+    registerOrJoin?(hash: string): Promise<{
+        jobId: string;
+        isOwner: boolean;
+    }>;
+    /**
+     * Mark a request as complete with its result
+     * @param hash The hash key of the request
+     * @param value The result of the request
+     */
+    complete(hash: string, value: T): Promise<void>;
+    /**
+     * Mark a request as failed with an error
+     * @param hash The hash key of the request
+     * @param error The error that occurred
+     */
+    fail(hash: string, error: Error): Promise<void>;
+    /**
+     * Check if a request is currently in progress
+     * @param hash The hash key of the request
+     * @returns True if the request is in progress
+     */
+    isInProgress(hash: string): Promise<boolean>;
+}
+
+/**
+ * Priority level for API requests
+ */
+type RequestPriority = 'user' | 'background';
+/**
+ * Adaptive configuration schema with validation and defaults
+ */
+declare const AdaptiveConfigSchema: z.ZodEffects<z.ZodObject<{
+    monitoringWindowMs: z.ZodDefault<z.ZodNumber>;
+    highActivityThreshold: z.ZodDefault<z.ZodNumber>;
+    moderateActivityThreshold: z.ZodDefault<z.ZodNumber>;
+    recalculationIntervalMs: z.ZodDefault<z.ZodNumber>;
+    sustainedInactivityThresholdMs: z.ZodDefault<z.ZodNumber>;
+    backgroundPauseOnIncreasingTrend: z.ZodDefault<z.ZodBoolean>;
+    maxUserScaling: z.ZodDefault<z.ZodNumber>;
+    minUserReserved: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    monitoringWindowMs: number;
+    highActivityThreshold: number;
+    moderateActivityThreshold: number;
+    recalculationIntervalMs: number;
+    sustainedInactivityThresholdMs: number;
+    backgroundPauseOnIncreasingTrend: boolean;
+    maxUserScaling: number;
+    minUserReserved: number;
+}, {
+    monitoringWindowMs?: number | undefined;
+    highActivityThreshold?: number | undefined;
+    moderateActivityThreshold?: number | undefined;
+    recalculationIntervalMs?: number | undefined;
+    sustainedInactivityThresholdMs?: number | undefined;
+    backgroundPauseOnIncreasingTrend?: boolean | undefined;
+    maxUserScaling?: number | undefined;
+    minUserReserved?: number | undefined;
+}>, {
+    monitoringWindowMs: number;
+    highActivityThreshold: number;
+    moderateActivityThreshold: number;
+    recalculationIntervalMs: number;
+    sustainedInactivityThresholdMs: number;
+    backgroundPauseOnIncreasingTrend: boolean;
+    maxUserScaling: number;
+    minUserReserved: number;
+}, {
+    monitoringWindowMs?: number | undefined;
+    highActivityThreshold?: number | undefined;
+    moderateActivityThreshold?: number | undefined;
+    recalculationIntervalMs?: number | undefined;
+    sustainedInactivityThresholdMs?: number | undefined;
+    backgroundPauseOnIncreasingTrend?: boolean | undefined;
+    maxUserScaling?: number | undefined;
+    minUserReserved?: number | undefined;
+}>;
+/**
+ * Configuration for adaptive rate limiting
+ */
+type AdaptiveConfig = z.infer<typeof AdaptiveConfigSchema>;
+/**
+ * Interface for rate limiting API requests per resource
+ */
+interface RateLimitStore {
+    /**
+     * Check if a request to a resource can proceed based on rate limits
+     * @param resource The resource name (e.g., 'issues', 'characters')
+     * @returns True if the request can proceed, false if rate limited
+     */
+    canProceed(resource: string): Promise<boolean>;
+    /**
+     * Record a request to a resource for rate limiting tracking
+     * @param resource The resource name (e.g., 'issues', 'characters')
+     */
+    record(resource: string): Promise<void>;
+    /**
+     * Get the current rate limit status for a resource
+     * @param resource The resource name
+     * @returns Rate limit information including remaining requests and reset time
+     */
+    getStatus(resource: string): Promise<{
+        remaining: number;
+        resetTime: Date;
+        limit: number;
+    }>;
+    /**
+     * Reset rate limits for a resource (useful for testing)
+     * @param resource The resource name
+     */
+    reset(resource: string): Promise<void>;
+    /**
+     * Get the time in milliseconds until the next request can be made
+     * @param resource The resource name
+     * @returns Milliseconds to wait, or 0 if no waiting is needed
+     */
+    getWaitTime(resource: string): Promise<number>;
+}
+/**
+ * Enhanced interface for adaptive rate limiting stores with priority support
+ */
+interface AdaptiveRateLimitStore extends RateLimitStore {
+    /**
+     * Check if a request to a resource can proceed based on rate limits
+     * @param resource The resource name (e.g., 'issues', 'characters')
+     * @param priority The priority level of the request (defaults to 'background')
+     * @returns True if the request can proceed, false if rate limited
+     */
+    canProceed(resource: string, priority?: RequestPriority): Promise<boolean>;
+    /**
+     * Record a request to a resource for rate limiting tracking
+     * @param resource The resource name (e.g., 'issues', 'characters')
+     * @param priority The priority level of the request (defaults to 'background')
+     */
+    record(resource: string, priority?: RequestPriority): Promise<void>;
+    /**
+     * Get the current rate limit status for a resource
+     * @param resource The resource name
+     * @returns Rate limit information including remaining requests and reset time
+     */
+    getStatus(resource: string): Promise<{
+        remaining: number;
+        resetTime: Date;
+        limit: number;
+        adaptive?: {
+            userReserved: number;
+            backgroundMax: number;
+            backgroundPaused: boolean;
+            recentUserActivity: number;
+            reason: string;
+        };
+    }>;
+    /**
+     * Get the time in milliseconds until the next request can be made
+     * @param resource The resource name
+     * @param priority The priority level of the request (defaults to 'background')
+     * @returns Milliseconds to wait, or 0 if no waiting is needed
+     */
+    getWaitTime(resource: string, priority?: RequestPriority): Promise<number>;
+}
+
+/**
+ * Creates a consistent hash for API requests to use as cache/dedupe keys
+ * @param endpoint The API endpoint
+ * @param params The request parameters
+ * @returns A SHA-256 hash of the request
+ */
+declare function hashRequest(endpoint: string, params?: Record<string, unknown>): string;
+
+/**
+ * Configuration for per-resource rate limiting.
+ *
+ * This interface is shared by all store implementations (e.g. in-memory,
+ * SQLite) so that callers can use a single canonical type.
+ */
+interface RateLimitConfig {
+    /** Number of requests allowed per time window */
+    limit: number;
+    /** Duration of the window in milliseconds */
+    windowMs: number;
+}
+/**
+ * Default rate-limit window: 60 requests per minute.
+ *
+ * Store implementations can reference this to avoid duplicating magic numbers.
+ */
+declare const DEFAULT_RATE_LIMIT: RateLimitConfig;
+
+interface ActivityMetrics {
+    recentUserRequests: Array<number>;
+    recentBackgroundRequests: Array<number>;
+    userActivityTrend: 'increasing' | 'stable' | 'decreasing' | 'none';
+}
+interface DynamicCapacityResult {
+    userReserved: number;
+    backgroundMax: number;
+    backgroundPaused: boolean;
+    reason: string;
+}
+/**
+ * Calculates dynamic capacity allocation based on real-time user activity patterns
+ */
+declare class AdaptiveCapacityCalculator {
+    readonly config: z.infer<typeof AdaptiveConfigSchema>;
+    constructor(config?: Partial<z.input<typeof AdaptiveConfigSchema>>);
+    calculateDynamicCapacity(resource: string, totalLimit: number, activityMetrics: ActivityMetrics): DynamicCapacityResult;
+    getRecentActivity(requests: Array<number>): number;
+    calculateActivityTrend(requests: Array<number>): 'increasing' | 'stable' | 'decreasing' | 'none';
+    private getUserMultiplier;
+    private getSustainedInactivityPeriod;
+}
+
+interface HttpClientContract {
+    /**
+     * Perform a GET request.
+     *
+     * @param url     Full request URL
+     * @param options Optional configuration – primarily an AbortSignal so
+     *                callers can cancel long-running or rate-limited waits.
+     */
+    get<Result>(url: string, options?: {
+        /**
+         * AbortSignal that allows the caller to cancel the request, including any
+         * internal rate-limit wait. If the signal is aborted while waiting the
+         * promise rejects with an `AbortError`-like `Error` instance.
+         */
+        signal?: AbortSignal;
+        /**
+         * Priority level for the request (affects rate limiting behavior)
+         */
+        priority?: RequestPriority;
+    }): Promise<Result>;
+}
+
+interface HttpClientStores {
+    cache?: CacheStore;
+    dedupe?: DedupeStore;
+    rateLimit?: RateLimitStore | AdaptiveRateLimitStore;
+}
+interface HttpClientOptions {
+    /**
+     * Default cache TTL in seconds
+     */
+    defaultCacheTTL?: number;
+    /**
+     * Whether to throw errors on rate limit violations
+     */
+    throwOnRateLimit?: boolean;
+    /**
+     * Maximum time to wait for rate limit in milliseconds
+     */
+    maxWaitTime?: number;
+    /**
+     * Optional response transformer applied to the raw response data.
+     * Use this for converting snake_case to camelCase, etc.
+     */
+    responseTransformer?: (data: unknown) => unknown;
+    /**
+     * Optional error handler to convert errors into domain-specific error types.
+     * If not provided, a generic HttpClientError is thrown.
+     */
+    errorHandler?: (error: unknown) => Error;
+    /**
+     * Optional response validator/handler called after transformation.
+     * Use this to inspect the response and throw domain-specific errors
+     * based on response content (e.g., API-level error codes).
+     */
+    responseHandler?: (data: unknown) => unknown;
+    /**
+     * Configure rate-limit response header names for standards and custom APIs.
+     */
+    rateLimitHeaders?: {
+        retryAfter?: Array<string>;
+        limit?: Array<string>;
+        remaining?: Array<string>;
+        reset?: Array<string>;
+        combined?: Array<string>;
+    };
+}
+declare class HttpClient implements HttpClientContract {
+    private _http;
+    private stores;
+    private serverCooldowns;
+    private options;
+    constructor(stores?: HttpClientStores, options?: HttpClientOptions);
+    private normalizeRateLimitHeaders;
+    private normalizeHeaderNames;
+    /**
+     * Infer the resource name from the endpoint URL
+     * @param url The full URL or endpoint path
+     * @returns The resource name for rate limiting
+     */
+    private inferResource;
+    /**
+     * Extract endpoint and params from URL for request hashing
+     * @param url The full URL
+     * @returns Object with endpoint and params for hashing
+     */
+    private parseUrlForHashing;
+    private getOriginScope;
+    private getHeaderValue;
+    private parseIntegerHeader;
+    private parseRetryAfterMs;
+    private parseResetMs;
+    private parseCombinedRateLimitHeader;
+    private applyServerRateLimitHints;
+    private enforceServerCooldown;
+    private enforceStoreRateLimit;
+    private generateClientError;
+    get<Result>(url: string, options?: {
+        signal?: AbortSignal;
+        priority?: RequestPriority;
+    }): Promise<Result>;
+}
+
+/**
+ * Base error class for HTTP client errors.
+ * Consumers can extend this for domain-specific error handling.
+ */
+declare class HttpClientError extends Error {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+
+export { type ActivityMetrics, AdaptiveCapacityCalculator, type AdaptiveConfig, AdaptiveConfigSchema, type AdaptiveRateLimitStore, type CacheStore, DEFAULT_RATE_LIMIT, type DedupeStore, type DynamicCapacityResult, HttpClient, type HttpClientContract, HttpClientError, type HttpClientOptions, type HttpClientStores, type RateLimitConfig, type RateLimitStore, type RequestPriority, hashRequest };