@plyaz/api 1.0.2 → 1.1.0

package/dist/api/cache/index.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Cache Management Utilities
+ * Direct pass-through to fetchff's cache management system
+ * Maintains vendor abstraction while providing full cache control
+ *
+ * @module cache
+ */
+import { mutate as fetchffMutate, getCache as fetchffGetCache, setCache as fetchffSetCache, deleteCache as fetchffDeleteCache, revalidate as fetchffRevalidate, revalidateAll as fetchffRevalidateAll, subscribe as fetchffSubscribe } from 'fetchff';
+export * from './strategies';
+export * from './patterns';
+/**
+ * Update cached data for a specific key
+ * Supports optimistic updates and background revalidation
+ *
+ * @param cacheKey - The cache key or URL pattern
+ * @param data - New data to set in cache
+ * @param revalidate - Whether to revalidate after mutation
+ *
+ * @example
+ * ```typescript
+ * // Update specific cache entry
+ * await mutate('/api/users/123', updatedUser);
+ *
+ * // Update with revalidation
+ * await mutate('/api/users/123', updatedUser, true);
+ *
+ * // Update multiple entries with pattern
+ * await mutate('/api/users/*', null, true); // Invalidate all users
+ * ```
+ */
+export declare const mutate: typeof fetchffMutate;
+/**
+ * Get cached data for a specific key
+ * Returns null if not in cache or expired
+ *
+ * @param cacheKey - The cache key or URL
+ * @returns Cached data or null
+ *
+ * @example
+ * ```typescript
+ * const cachedUser = getCache('/api/users/123');
+ * if (cachedUser) {
+ *   console.log('Using cached data:', cachedUser);
+ * }
+ * ```
+ */
+export declare const getCache: typeof fetchffGetCache;
+/**
+ * Set cache data directly
+ * Useful for pre-populating cache or manual cache management
+ *
+ * @param cacheKey - The cache key or URL
+ * @param data - Data to cache
+ * @param options - Cache options (ttl, etc.)
+ *
+ * @example
+ * ```typescript
+ * // Pre-populate cache
+ * setCache('/api/users/123', userData, { ttl: 300 });
+ *
+ * // Cache with custom expiry
+ * setCache('/api/config', config, { ttl: 3600 });
+ * ```
+ */
+export declare const setCache: typeof fetchffSetCache;
+/**
+ * Delete cached data for a specific key or pattern
+ * Supports wildcard patterns for bulk deletion
+ *
+ * @param cacheKey - The cache key, URL, or pattern
+ *
+ * @example
+ * ```typescript
+ * // Delete specific entry
+ * deleteCache('/api/users/123');
+ *
+ * // Delete all user cache entries
+ * deleteCache('/api/users/*');
+ *
+ * // Clear all cache
+ * deleteCache('*');
+ * ```
+ */
+export declare const deleteCache: typeof fetchffDeleteCache;
+/**
+ * Revalidate cached data by fetching fresh data
+ * Triggers background fetch to update cache
+ *
+ * @param cacheKey - The cache key or URL to revalidate
+ * @returns Promise that resolves when revalidation completes
+ *
+ * @example
+ * ```typescript
+ * // Revalidate specific endpoint
+ * await revalidate('/api/users/123');
+ *
+ * // Revalidate pattern
+ * await revalidate('/api/users/*');
+ * ```
+ */
+export declare const revalidate: typeof fetchffRevalidate;
+/**
+ * Revalidate all cached data
+ * Useful for global refresh or after authentication changes
+ *
+ * @returns Promise that resolves when all revalidations complete
+ *
+ * @example
+ * ```typescript
+ * // After login, refresh all cached data
+ * await revalidateAll();
+ * ```
+ */
+export declare const revalidateAll: typeof fetchffRevalidateAll;
+/**
+ * Subscribe to cache updates for real-time synchronization
+ * Useful for keeping UI in sync across components/tabs
+ *
+ * @param cacheKey - The cache key or pattern to watch
+ * @param callback - Function called when cache updates
+ * @returns Unsubscribe function
+ *
+ * @example
+ * ```typescript
+ * // Subscribe to user updates
+ * const unsubscribe = subscribe('/api/users/123', (data) => {
+ *   console.log('User data updated:', data);
+ *   updateUI(data);
+ * });
+ *
+ * // Later: cleanup
+ * unsubscribe();
+ * ```
+ */
+export declare const subscribe: typeof fetchffSubscribe;
+/**
+ * Cache utilities grouped for convenient access
+ *
+ * @example
+ * ```typescript
+ * import { cache } from '@plyaz/api';
+ *
+ * // Use utilities
+ * cache.mutate('/api/data', newData);
+ * cache.deleteCache('/api/old/*');
+ * cache.revalidateAll();
+ * ```
+ */
+export declare const cache: {
+    readonly mutate: typeof fetchffMutate;
+    readonly getCache: typeof fetchffGetCache;
+    readonly setCache: typeof fetchffSetCache;
+    readonly deleteCache: typeof fetchffDeleteCache;
+    readonly revalidate: typeof fetchffRevalidate;
+    readonly revalidateAll: typeof fetchffRevalidateAll;
+    readonly subscribe: typeof fetchffSubscribe;
+};
+/**
+ * Helper function to clear cache by pattern
+ * Convenience wrapper around deleteCache
+ *
+ * @example
+ * ```typescript
+ * // Clear all user-related cache
+ * clearCachePattern('/api/users');
+ *
+ * // Clear everything
+ * clearCachePattern('*');
+ * ```
+ */
+export declare function clearCachePattern(pattern: string): void;
+/**
+ * Helper function to invalidate and refetch
+ * Combines deletion and revalidation
+ *
+ * @example
+ * ```typescript
+ * // Force fresh fetch
+ * await invalidateAndRefetch('/api/users/123');
+ * ```
+ */
+export declare function invalidateAndRefetch(cacheKey: string): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/api/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/cache/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,MAAM,IAAI,aAAa,EACvB,QAAQ,IAAI,eAAe,EAC3B,QAAQ,IAAI,eAAe,EAC3B,WAAW,IAAI,kBAAkB,EACjC,UAAU,IAAI,iBAAiB,EAC/B,aAAa,IAAI,oBAAoB,EACrC,SAAS,IAAI,gBAAgB,EAC9B,MAAM,SAAS,CAAC;AAGjB,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAE3B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,MAAM,sBAAgB,CAAC;AAEpC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,QAAQ,wBAAkB,CAAC;AAExC;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,QAAQ,wBAAkB,CAAC;AAExC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,WAAW,2BAAqB,CAAC;AAE9C;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,0BAAoB,CAAC;AAE5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,6BAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,SAAS,yBAAmB,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,KAAK;;;;;;;;CAQR,CAAC;AAEX;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG1E"}

package/dist/api/cache/patterns.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Cache Key Patterns
+ * Functions to generate consistent cache keys for selective invalidation
+ *
+ * @module cache/patterns
+ */
+import type { TimeInterval } from '@plyaz/types/api';
+/**
+ * Cache key patterns for organizing cache entries
+ * These generate namespaced keys for better cache organization
+ *
+ * @example
+ * ```typescript
+ * import { cacheKeyPatterns, setCache } from '@plyaz/api';
+ *
+ * // Create user-specific cache key
+ * const cacheKey = cacheKeyPatterns.byUser('123', 'profile');
+ * // Returns: "user:123:profile"
+ *
+ * // Use with cache utilities
+ * setCache(cacheKey, userData, { ttl: 300 });
+ * ```
+ */
+export declare const cacheKeyPatterns: {
+    /**
+     * User-specific cache key
+     * Creates keys like "user:123:endpoint"
+     */
+    readonly byUser: (userId: string, endpoint: string) => string;
+    /**
+     * Organization-specific cache key
+     * Creates keys like "org:456:endpoint"
+     */
+    readonly byOrg: (orgId: string, endpoint: string) => string;
+    /**
+     * Generic namespace-based cache key for any resource type
+     * Creates keys like:
+     * - "campaigns:789:stats"
+     * - "nfts:123:metadata"
+     * - "transactions:abc:details"
+     * - "collections:456:items"
+     *
+     * @example
+     * cacheKeyPatterns.byNamespace('campaigns', '789', 'stats')
+     * cacheKeyPatterns.byNamespace('nfts', '123', 'metadata')
+     */
+    readonly byNamespace: (namespace: string, id: string, endpoint: string) => string;
+    /**
+     * Time-based cache key (for time-series data)
+     * Creates keys like "stats:hour:2024-0-15-14" or "stats:day:2024-0-15"
+     * Uses the time utility for consistent time-based key generation
+     *
+     * @example
+     * cacheKeyPatterns.byTime('analytics', 'hour')
+     * cacheKeyPatterns.byTime('reports', 'week')
+     */
+    readonly byTime: (endpoint: string, interval: TimeInterval) => string;
+    /**
+     * Version-based cache key
+     * Creates keys like "v2:api:users"
+     */
+    readonly byVersion: (version: string, endpoint: string) => string;
+    /**
+     * Role-based cache key
+     * Creates keys like "role:admin:dashboard"
+     */
+    readonly byRole: (role: string, endpoint: string) => string;
+    /**
+     * Session-based cache key
+     * Creates keys like "session:abc123:preferences"
+     */
+    readonly bySession: (sessionId: string, endpoint: string) => string;
+    /**
+     * Locale-based cache key
+     * Creates keys like "locale:en-US:translations"
+     */
+    readonly byLocale: (locale: string, endpoint: string) => string;
+    /**
+     * Feature flag cache key
+     * Creates keys like "feature:dark-mode:config"
+     */
+    readonly byFeature: (feature: string, endpoint: string) => string;
+    /**
+     * Composite cache key with multiple dimensions
+     * Creates keys like "user:123:org:456:project:789"
+     */
+    readonly composite: (dimensions: Record<string, string>) => string;
+    /**
+     * Wildcard pattern for bulk operations
+     * Creates patterns like "user:123:*" for deleteCache
+     */
+    readonly withWildcard: (prefix: string) => string;
+    /**
+     * Global namespace
+     */
+    readonly global: (endpoint: string) => string;
+};
+/**
+ * Common invalidation scenarios using cache keys
+ * These use cache key patterns for targeted invalidation
+ *
+ * @example
+ * ```typescript
+ * import { invalidationScenarios } from '@plyaz/api';
+ *
+ * // After any resource update
+ * await invalidationScenarios.afterResourceUpdate('campaigns', 'campaign-789');
+ * await invalidationScenarios.afterResourceUpdate('user', 'user-123', ['profile', 'settings']);
+ * ```
+ *
+ * Note: For auth-specific scenarios like login/logout, you can:
+ * - Use afterResourceUpdate('session', sessionId) for session updates
+ * - Use afterResourceUpdate('user', userId) for user cache
+ * - Combine with deleteCache(cacheKeyPatterns.withWildcard('role')) for role changes
+ * - Use forceRefreshAll() for complete cache reset on logout
+ */
+export declare const invalidationScenarios: {
+    /**
+     * Generic invalidation after any resource update
+     * Works for campaigns, NFTs, collections, users, sessions, etc.
+     *
+     * @example
+     * afterResourceUpdate('campaigns', 'campaign-123')
+     * afterResourceUpdate('nfts', 'nft-456')
+     * afterResourceUpdate('user', 'user-789', ['profile', 'permissions'])
+     * afterResourceUpdate('session', 'session-abc')
+     */
+    readonly afterResourceUpdate: (namespace: string, resourceId: string, endpoints?: string[]) => Promise<void>;
+    /**
+     * Invalidate time-based caches (e.g., for stats refresh)
+     *
+     * @param endpoint - The endpoint to refresh
+     * @param intervals - Optional specific intervals to clear (defaults to all common intervals)
+     *
+     * @example
+     * refreshTimeBasedCache('analytics') // Clears all intervals
+     * refreshTimeBasedCache('stats', ['hour', 'day']) // Clears only hour and day
+     */
+    readonly refreshTimeBasedCache: (endpoint: string, intervals?: TimeInterval[]) => Promise<void>;
+    /**
+     * Force refresh all data
+     * Use sparingly - this is expensive
+     *
+     * Note: Could be enhanced to:
+     * - Accept namespace filters (e.g., only clear 'user:*')
+     * - Support dry-run mode to see what would be cleared
+     * - Add progress callbacks for large cache clears
+     * - Implement staged clearing (clear in chunks)
+     */
+    readonly forceRefreshAll: () => Promise<void>;
+};
+/**
+ * Create custom cache pattern
+ * Helper for creating type-safe cache patterns
+ *
+ * @example
+ * ```typescript
+ * const customPattern = createCachePattern('/api/custom/:id');
+ * const key = customPattern({ id: '123' }); // '/api/custom/123'
+ * ```
+ */
+export declare function createCachePattern<T extends Record<string, string>>(pattern: string): (params: T) => string;
+/**
+ * Build cache key from parts
+ * Ensures consistent cache key format
+ *
+ * @example
+ * ```typescript
+ * const key = buildCacheKey('users', '123', 'profile');
+ * // Returns: '/users/123/profile'
+ * ```
+ */
+export declare function buildCacheKey(...parts: string[]): string;
+//# sourceMappingURL=patterns.d.ts.map

package/dist/api/cache/patterns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.d.ts","sourceRoot":"","sources":["../../../src/api/cache/patterns.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;OAGG;8BACc,MAAM,YAAY,MAAM;IAEzC;;;OAGG;4BACY,MAAM,YAAY,MAAM;IAEvC;;;;;;;;;;;OAWG;sCACsB,MAAM,MAAM,MAAM,YAAY,MAAM;IAG7D;;;;;;;;OAQG;gCACgB,MAAM,YAAY,YAAY;IAKjD;;;OAGG;kCACkB,MAAM,YAAY,MAAM;IAE7C;;;OAGG;4BACY,MAAM,YAAY,MAAM;IAEvC;;;OAGG;oCACoB,MAAM,YAAY,MAAM;IAE/C;;;OAGG;gCACgB,MAAM,YAAY,MAAM;IAE3C;;;OAGG;kCACkB,MAAM,YAAY,MAAM;IAE7C;;;OAGG;qCACqB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IAM9C;;;OAGG;oCACoB,MAAM;IAE7B;;OAEG;gCACgB,MAAM;CACjB,CAAC;AAEX;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qBAAqB;IAChC;;;;;;;;;OASG;8CAEU,MAAM,cACL,MAAM,cACN,MAAM,EAAE,KACnB,OAAO,CAAC,IAAI,CAAC;IAehB;;;;;;;;;OASG;+CAES,MAAM,cACL,YAAY,EAAE,KACxB,OAAO,CAAC,IAAI,CAAC;IAOhB;;;;;;;;;OASG;oCACsB,OAAO,CAAC,IAAI,CAAC;CAO9B,CAAC;AAEX;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjE,OAAO,EAAE,MAAM,GACd,CAAC,MAAM,EAAE,CAAC,KAAK,MAAM,CAQvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAExD"}

package/dist/api/cache/strategies.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Cache Management Strategies
+ * Pre-configured cache strategies for common use cases
+ *
+ * @module cache/strategies
+ */
+import type { CacheStrategyConfig, CacheStrategyName } from '@plyaz/types/api';
+/**
+ * Pre-configured cache strategies for common use cases
+ *
+ * @example
+ * ```typescript
+ * import { cacheStrategies } from '@plyaz/api';
+ *
+ * // Use in service function
+ * const config = {
+ *   cache: cacheStrategies.standard
+ * };
+ *
+ * // Use in hook
+ * const { data } = useFetcher('/api/data', {
+ *   ...cacheStrategies.shortLived
+ * });
+ * ```
+ */
+export declare const cacheStrategies: Readonly<Record<CacheStrategyName, CacheStrategyConfig>>;
+/**
+ * Helper to create custom cache strategy
+ *
+ * @example
+ * ```typescript
+ * const customCache = createCacheStrategy({
+ *   ttl: 120,
+ *   stale: 240
+ * });
+ * ```
+ */
+export declare function createCacheStrategy(config: CacheStrategyConfig): CacheStrategyConfig;
+/**
+ * Get cache strategy by name with runtime validation
+ */
+export declare function getCacheStrategy(name: CacheStrategyName): CacheStrategyConfig;
+/**
+ * Merge multiple cache strategies (last wins)
+ */
+export declare function mergeCacheStrategies(...configs: (CacheStrategyConfig | undefined)[]): CacheStrategyConfig;
+//# sourceMappingURL=strategies.d.ts.map

package/dist/api/cache/strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../../src/api/cache/strategies.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAoB,MAAM,kBAAkB,CAAC;AAGjG;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,CAoE3E,CAAC;AAEX;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,mBAAmB,CAMpF;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG,mBAAmB,CAiC7E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,OAAO,EAAE,CAAC,mBAAmB,GAAG,SAAS,CAAC,EAAE,GAC9C,mBAAmB,CAiBrB"}

package/dist/api/client/clientEventManager.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Unified Client Event Management System
+ *
+ * Centralizes all event handling for API clients using the shared event emitter.
+ * Handles internal events, external events, and configuration-based events.
+ */
+import type { RequestConfig, FetchResponse, ResponseError } from 'fetchff';
+import { getEventManager } from '../events';
+import type { ApiPackageError } from '../errors/ApiPackageError';
+import type { ConfigConflict, DebugInfo, ApiClientInstance, ApiClientOptions, ApiConfig, UpdateConfigOptions, HandlerOptions, ApiClientWithEvents, ClientEventManagerLike, EventScopeWithTemporary } from '@plyaz/types/api';
+import type { EndpointsList } from '../endpoints';
+/**
+ * Client Event Manager
+ * Manages all event handling for a client instance using the shared emitter
+ */
+export declare class ClientEventManager implements ClientEventManagerLike<ReturnType<typeof getEventManager>> {
+    private readonly client;
+    private config;
+    private readonly eventManager;
+    readonly emitter: import("@plyaz/types").EventEmitter<unknown>;
+    private readonly monitoringState;
+    private readonly handlerRegistry;
+    private readonly eventStats;
+    private static readonly MAX_RECENT_EVENTS;
+    private static readonly DEFAULT_MAX_RETRY_ATTEMPTS;
+    private static readonly DEFAULT_RETRY_DELAY;
+    /**
+     * Track an event for statistics
+     * @private
+     */
+    private trackEvent;
+    /**
+     * Setup universal event tracking for all events
+     * @private
+     */
+    private setupEventTracking;
+    constructor(client: ApiClientInstance<EndpointsList>, config: Partial<ApiConfig>);
+    /**
+     * Register all namespace handlers from config
+     */
+    private setupNamespaceHandlers;
+    /**
+     * Setup monitoring if enabled
+     */
+    private setupMonitoringIfNeeded;
+    /**
+     * Setup temporary override handlers for network
+     */
+    private setupTemporaryOverrideHandlers;
+    /**
+     * Setup all event handlers based on configuration
+     */
+    private setupEventHandlers;
+    /**
+     * Register handlers for a specific namespace with proper scope
+     * Maps handler names to the actual event names emitted by factories
+     */
+    private registerHandlers;
+    /**
+     * Clear all handlers for a specific scope
+     */
+    private clearHandlersForScope;
+    /**
+     * Get the proper handler namespace for an event type and scope
+     * Delegates to the centralized function in namespaces.ts
+     */
+    private getHandlerNamespace;
+    /**
+     * Add event handler with strategy
+     */
+    addHandler(event: string, handler: Function | Function[], options?: HandlerOptions): () => void;
+    /**
+     * Get handlers for an event
+     */
+    private getHandlers;
+    /**
+     * Clear handlers for an event
+     */
+    private clearHandlers;
+    /**
+     * Try to find exact event name match from namespace events
+     */
+    private findExactEventMatch;
+    /**
+     * Remove namespace-specific suffixes from handler name
+     */
+    private removeNamespaceSuffixes;
+    /**
+     * Convert handler name to kebab-case event name
+     */
+    private toKebabCaseEventName;
+    /**
+     * Map handler name to the actual event name emitted by factories
+     * e.g., 'onNetworkError' -> 'errors:network'
+     */
+    private mapHandlerNameToEventName;
+    /**
+     * Get the events object for a namespace using EVENT_NAMESPACES
+     */
+    private getNamespaceEvents;
+    /**
+     * Type guard for NetworkQualityEvent
+     */
+    private isNetworkQualityEvent;
+    /**
+     * Setup network event forwarding and listeners
+     */
+    private setupNetworkEventForwarding;
+    /**
+     * Track ClientEventManager operations using the operation queue to avoid circular dependency
+     */
+    private trackClientEventManagerOperation;
+    /**
+     * Setup event scopes based on strategy
+     */
+    private setupEventScopes;
+    /**
+     * Apply config update based on strategy
+     */
+    private applyConfigStrategy;
+    /**
+     * Register standard namespace handlers from updates
+     */
+    private registerStandardHandlers;
+    /**
+     * Register network override handler if present
+     */
+    private registerNetworkOverrideHandler;
+    /**
+     * Handle debug events and monitoring updates
+     */
+    private handleDebugEventsUpdate;
+    /**
+     * Register all event handlers from updates
+     */
+    private registerEventHandlers;
+    /**
+     * Update configuration and re-setup handlers
+     */
+    updateConfig(updates: Partial<ApiConfig>, options?: UpdateConfigOptions): void;
+    /**
+     * Clear all temporary configuration overrides
+     * Clears handlers at REQUEST/TEMPORARY scope
+     */
+    clearTemporaryOverrides(): void;
+    /**
+     * Check for conflicts
+     */
+    checkConflicts(): ConfigConflict[];
+    /**
+     * Generate debug info
+     */
+    getDebugInfo(): DebugInfo;
+    /**
+     * Calculate impact level
+     */
+    private calculateImpactLevel;
+    /**
+     * Start monitoring
+     */
+    startMonitoring(): void;
+    /**
+     * Stop monitoring
+     */
+    stopMonitoring(): void;
+    /**
+     * Check if monitoring
+     */
+    isMonitoring(): boolean;
+    /**
+     * Get event statistics for monitoring and debugging
+     */
+    getEventStats(): {
+        totalEvents: number;
+        totalListeners: number;
+        listenerCount: number;
+        recentEvents: Array<{
+            type: string;
+            timestamp: number;
+            data?: unknown;
+        }>;
+        overrideCount: number;
+        eventCountsByType: Record<string, number>;
+    };
+    /**
+     * Get the active event scopes from the EventManager
+     */
+    getActiveScopes(): EventScopeWithTemporary[];
+    /**
+     * Emit error event (delegates to emitErrorEvent for consistency)
+     */
+    emitError(error: ApiPackageError): void;
+    /**
+     * Emit request start event
+     * Called by fetchff onRequest interceptor
+     */
+    emitRequestStart(config: RequestConfig): void;
+    /**
+     * Emit response received event
+     * Called by fetchff onResponse interceptor
+     */
+    emitResponseReceived<TData = unknown>(response: FetchResponse<TData>): void;
+    /**
+     * Emit retry attempt event
+     * Called by fetchff onRetry interceptor
+     */
+    emitRetryAttempt<TResponse = unknown>(error: ResponseError<TResponse>, attemptNumber: number, config?: RequestConfig): void;
+    /**
+     * Dispose of all resources
+     */
+    dispose(): void;
+}
+/**
+ * Setup client events for an API client instance
+ * Centralizes all event configuration and management
+ */
+export declare function setupClientEvents(client: ApiClientInstance<EndpointsList>, globalConfig: ApiConfig, clientConfig: ApiClientOptions): ApiClientWithEvents<ClientEventManager, EndpointsList>;
+/**
+ * Check if there's meaningful configuration to apply
+ * Returns false if config is empty and updateOptions only has default values
+ *
+ * @param config - The merged API configuration
+ * @param updateOptions - The update configuration options
+ * @returns True if updateConfig should be called, false otherwise
+ *
+ * @example
+ * ```typescript
+ * const mergedConfig = mergeConfigs(serviceDefaults, options?.apiConfig ?? {});
+ * const updateOptions = { strategy: 'temporary', ...options?.updateConfigOptions };
+ *
+ * if (shouldApplyConfig(mergedConfig, updateOptions)) {
+ *   client.updateConfig(mergedConfig, updateOptions);
+ * }
+ * ```
+ */
+export declare function shouldApplyConfig(config: Partial<ApiConfig>, updateOptions: UpdateConfigOptions): boolean;
+export declare function mergeEventConfigs(global?: Partial<ApiConfig>, client?: Partial<ApiConfig>, request?: Partial<ApiConfig>): Partial<ApiConfig>;
+//# sourceMappingURL=clientEventManager.d.ts.map

package/dist/api/client/clientEventManager.d.ts.map

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

package/dist/api/client/createApiClient.d.ts

@@ -0,0 +1,5 @@
+import type { EndpointsList } from '../endpoints';
+import type { ApiClientOptions, ApiClientWithEvents } from '@plyaz/types/api';
+import type { ClientEventManager } from './clientEventManager';
+export declare function createApiClient(options?: ApiClientOptions): Promise<ApiClientWithEvents<ClientEventManager, EndpointsList>>;
+//# sourceMappingURL=createApiClient.d.ts.map

package/dist/api/client/createApiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createApiClient.d.ts","sourceRoot":"","sources":["../../../src/api/client/createApiClient.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAEV,gBAAgB,EAOhB,mBAAmB,EAMpB,MAAM,kBAAkB,CAAC;AA+B1B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAqkB/D,wBAAsB,eAAe,CACnC,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,aAAa,CAAC,CAAC,CAkHjE"}

package/dist/api/client/helpers/headers.d.ts

@@ -0,0 +1,11 @@
+import type { ApiHeaders, ApiClientOptions } from '@plyaz/types/api';
+/**
+ * Apply header presets to existing headers
+ */
+export declare function applyHeaderPresets(headers: ApiHeaders, presets: string[]): ApiHeaders;
+/**
+ * Process header configuration from options
+ * Handles both simple and advanced header configurations
+ */
+export declare function processHeaders(options: ApiClientOptions, baseHeaders?: ApiHeaders): Promise<ApiHeaders>;
+//# sourceMappingURL=headers.d.ts.map