@plyaz/api 1.0.2 → 1.1.0

package/dist/api/events/queue/ConfigUpdateQueueManager.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Config Update Queue Manager
+ *
+ * Manages queued configuration updates with priority handling
+ * to ensure config changes are applied in the correct order.
+ */
+import type { QueuedConfigUpdate, ConfigState, QueueStats } from '@plyaz/types/api';
+/**
+ * Config update queue manager
+ */
+export declare class ConfigUpdateQueueManager {
+    private static instance;
+    private queue;
+    private configState;
+    private constructor();
+    /**
+     * Get or create the queue
+     */
+    private getQueue;
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): ConfigUpdateQueueManager;
+    /**
+     * Initialize with config state
+     */
+    initialize(configState: ConfigState): void;
+    /**
+     * Queue a config update
+     */
+    queueUpdate(config: Partial<Record<string, unknown>>, strategy?: QueuedConfigUpdate['strategy'], scope?: QueuedConfigUpdate['scope'], metadata?: QueuedConfigUpdate['metadata']): void;
+    /**
+     * Process a config update
+     */
+    private processConfigUpdate;
+    /**
+     * Determine priority for config update
+     */
+    private getPriority;
+    /**
+     * Apply config immediately (bypass queue)
+     */
+    applyImmediate(config: Partial<Record<string, unknown>>, strategy?: QueuedConfigUpdate['strategy']): void;
+    /**
+     * Get queue statistics
+     */
+    getStats(): QueueStats;
+    /**
+     * Reset the queue
+     */
+    reset(): void;
+}
+//# sourceMappingURL=ConfigUpdateQueueManager.d.ts.map

package/dist/api/events/queue/ConfigUpdateQueueManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConfigUpdateQueueManager.d.ts","sourceRoot":"","sources":["../../../../src/api/events/queue/ConfigUpdateQueueManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EAEX,UAAU,EACX,MAAM,kBAAkB,CAAC;AAsB1B;;GAEG;AACH,qBAAa,wBAAwB;IACnC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAA2B;IAClD,OAAO,CAAC,KAAK,CAAgD;IAC7D,OAAO,CAAC,WAAW,CAA4B;IAE/C,OAAO;IAIP;;OAEG;IACH,OAAO,CAAC,QAAQ;IAQhB;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,wBAAwB;IAO9C;;OAEG;IACI,UAAU,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAIjD;;OAEG;IACI,WAAW,CAChB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,QAAQ,GAAE,kBAAkB,CAAC,UAAU,CAAW,EAClD,KAAK,GAAE,kBAAkB,CAAC,OAAO,CAAY,EAC7C,QAAQ,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,GACxC,IAAI;IAeP;;OAEG;YACW,mBAAmB;IA0CjC;;OAEG;IACH,OAAO,CAAC,WAAW;IAoCnB;;OAEG;IACI,cAAc,CACnB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACxC,QAAQ,GAAE,kBAAkB,CAAC,UAAU,CAAW,GACjD,IAAI;IAaP;;OAEG;IACI,QAAQ,IAAI,UAAU;IAiB7B;;OAEG;IACI,KAAK,IAAI,IAAI;CAKrB"}

package/dist/api/events/queue/EventQueueManager.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Event Queue Manager
+ *
+ * Manages queued event processing with priority support
+ * for high-volume event handling.
+ */
+import type { EventScopeWithTemporary, QueueStats, QueuedEvent } from '@plyaz/types/api';
+import { EventManager } from '../EventManager';
+/**
+ * Event queue manager for handling events with priority
+ */
+export declare class EventQueueManager {
+    private static instance;
+    private queue;
+    private eventManager;
+    private enabled;
+    private constructor();
+    /**
+     * Get or create the queue
+     */
+    private getQueue;
+    /**
+     * Get singleton instance
+     */
+    static getInstance(): EventQueueManager;
+    /**
+     * Initialize with event manager
+     */
+    initialize(eventManager?: EventManager): void;
+    /**
+     * Enable or disable event queueing
+     */
+    setEnabled(enabled?: boolean): void;
+    /**
+     * Check if queueing is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Queue an event for processing
+     */
+    queueEvent(options: {
+        eventType: string;
+        eventName: string;
+        data: unknown;
+        scopes?: EventScopeWithTemporary[];
+        metadata?: QueuedEvent['metadata'];
+    }): void;
+    /**
+     * Process a queued event
+     */
+    private processEvent;
+    /**
+     * Determine priority for event
+     */
+    private getPriority;
+    /**
+     * Get queue statistics
+     */
+    getStats(): QueueStats;
+    /**
+     * Reset the queue
+     */
+    reset(): void;
+    /**
+     * Process events immediately (bypass queue)
+     */
+    processImmediate(eventType: string, eventName: string, data: unknown, scopes?: EventScopeWithTemporary[]): void;
+}
+//# sourceMappingURL=EventQueueManager.d.ts.map

package/dist/api/events/queue/EventQueueManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventQueueManager.d.ts","sourceRoot":"","sources":["../../../../src/api/events/queue/EventQueueManager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,uBAAuB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAQzF,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAK/C;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAoB;IAC3C,OAAO,CAAC,KAAK,CAA8E;IAC3F,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,OAAO,CAAQ;IAEvB,OAAO;IAIP;;OAEG;IACH,OAAO,CAAC,QAAQ;IAQhB;;OAEG;IACH,MAAM,CAAC,WAAW,IAAI,iBAAiB;IAOvC;;OAEG;IACI,UAAU,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;IAIpD;;OAEG;IACI,UAAU,CAAC,OAAO,GAAE,OAAc,GAAG,IAAI;IAIhD;;OAEG;IACI,SAAS,IAAI,OAAO;IAI3B;;OAEG;IACI,UAAU,CAAC,OAAO,EAAE;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,SAAS,EAAE,MAAM,CAAC;QAClB,IAAI,EAAE,OAAO,CAAC;QACd,MAAM,CAAC,EAAE,uBAAuB,EAAE,CAAC;QACnC,QAAQ,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;KACpC,GAAG,IAAI;IAuBR;;OAEG;YACW,YAAY;IAyC1B;;OAEG;IACH,OAAO,CAAC,WAAW;IAyCnB;;OAEG;IACI,QAAQ,IAAI,UAAU;IAiB7B;;OAEG;IACI,KAAK,IAAI,IAAI;IAMpB;;OAEG;IACI,gBAAgB,CACrB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,uBAAuB,EAAE,GACjC,IAAI;CAOR"}

package/dist/api/events/queue/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Event Queue Module
+ *
+ * Handles queued event processing with priority support
+ * for high-volume event handling.
+ *
+ * NOTE: All types are available from @plyaz/types/api, not re-exported here
+ * Import types like: import type { QueuedEvent, QueuedConfigUpdate } from '@plyaz/types/api';
+ */
+export { EventQueueManager } from './EventQueueManager';
+export { ConfigUpdateQueueManager } from './ConfigUpdateQueueManager';
+//# sourceMappingURL=index.d.ts.map

package/dist/api/events/queue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/api/events/queue/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/api/events/shared-emitter.d.ts

@@ -0,0 +1,14 @@
+import type { EventEmitter } from '../pubsub';
+/**
+ * Get the shared event emitter instance
+ * Creates one if it doesn't exist
+ * Returns enhanced EventEmitter with all handler management utilities
+ */
+export declare function getSharedEventEmitter(): EventEmitter;
+/**
+ * Reset the shared event emitter
+ * Removes all listeners and creates a fresh instance
+ * Uses enhanced removeAllListeners method
+ */
+export declare function resetSharedEventEmitter(): void;
+//# sourceMappingURL=shared-emitter.d.ts.map

package/dist/api/events/shared-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-emitter.d.ts","sourceRoot":"","sources":["../../../src/api/events/shared-emitter.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAK9C;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,YAAY,CAGpD;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAM9C"}

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

@@ -0,0 +1,17 @@
+import type { EnrichedHeadersOptions } from '@plyaz/types/api';
+/**
+ * Get cached value from configured storage
+ */
+export declare function getCachedValue<T>(key: string, options?: EnrichedHeadersOptions['cache']): T | null;
+/**
+ * Set cached value in configured storage
+ */
+export declare function setCachedValue<T>(key: string, value: T, options?: EnrichedHeadersOptions['cache']): void;
+/**
+ * Clear cached values
+ */
+export declare function clearCache(options?: EnrichedHeadersOptions['cache']): void;
+export declare const invalidateHeaderCache: typeof clearCache;
+export declare const clearHeaderCache: typeof clearCache;
+export declare function getOrCompute<T>(key: string, compute: () => T | Promise<T>, options?: EnrichedHeadersOptions['cache']): Promise<T>;
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/api/headers/cache.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,sBAAsB,EAAiC,MAAM,kBAAkB,CAAC;AAuP9F;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,sBAAsB,CAAC,OAAO,CAAC,GACxC,CAAC,GAAG,IAAI,CA0CV;AA0CD;;GAEG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,sBAAsB,CAAC,OAAO,CAAC,GACxC,IAAI,CAmBN;AA4CD;;GAEG;AACH,wBAAgB,UAAU,CAAC,OAAO,CAAC,EAAE,sBAAsB,CAAC,OAAO,CAAC,GAAG,IAAI,CAmB1E;AAGD,eAAO,MAAM,qBAAqB,mBAAa,CAAC;AAChD,eAAO,MAAM,gBAAgB,mBAAa,CAAC;AAE3C,wBAAsB,YAAY,CAAC,CAAC,EAClC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC7B,OAAO,CAAC,EAAE,sBAAsB,CAAC,OAAO,CAAC,GACxC,OAAO,CAAC,CAAC,CAAC,CAoCZ"}

package/dist/api/headers/enriched.d.ts

@@ -0,0 +1,18 @@
+import type { EndpointsList } from '../endpoints';
+import type { EnrichedHeadersOptions, HeaderValidationResult, ApiHeaders, RequestContext } from '@plyaz/types/api';
+/**
+ * Preset options for enriched header collection
+ */
+export declare const enrichedHeaderPresets: Record<string, Partial<EnrichedHeadersOptions>>;
+export declare function buildEnrichedHeaders(context?: RequestContext<EndpointsList>, options?: EnrichedHeadersOptions): Promise<ApiHeaders>;
+/**
+ * Validate enriched headers format and values for security
+ * Internal function used during header building
+ */
+export declare function validateHeaders(headers: ApiHeaders): HeaderValidationResult;
+/**
+ * Sanitize header values for safe transmission
+ * Removes dangerous characters while preserving valid header content
+ */
+export declare function sanitizeHeaderValue(value: string): string;
+//# sourceMappingURL=enriched.d.ts.map

package/dist/api/headers/enriched.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enriched.d.ts","sourceRoot":"","sources":["../../../src/api/headers/enriched.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EAItB,UAAU,EAEV,cAAc,EACf,MAAM,kBAAkB,CAAC;AAO1B;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,sBAAsB,CAAC,CA2DxE,CAAC;AAwgBX,wBAAsB,oBAAoB,CACxC,OAAO,GAAE,cAAc,CAAC,aAAa,CAAM,EAC3C,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,UAAU,CAAC,CAOrB;AAsBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,sBAAsB,CAkC3E;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAyBzD"}

package/dist/api/headers/events.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Header Events System
+ * Event system for tracking header changes, overrides, and transformations
+ */
+import type { ApiHeaders } from '@plyaz/types/api';
+/**
+ * Detect changes between two header sets
+ */
+export declare function detectHeaderChanges(previous: ApiHeaders, current: ApiHeaders): {
+    added: Record<string, string>;
+    modified: Record<string, {
+        old: string;
+        new: string;
+    }>;
+    removed: string[];
+};
+//# sourceMappingURL=events.d.ts.map

package/dist/api/headers/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/api/headers/events.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,UAAU,EACpB,OAAO,EAAE,UAAU,GAClB;IACD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAsBA"}

package/dist/api/headers/extract.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Extract Enriched Headers from Response
+ *
+ * Utilities for extracting enriched headers from HTTP responses
+ * to transfer context between different API clients
+ */
+import type { ApiHeaders, RequestHeaderExtraction } from '@plyaz/types/api';
+/**
+ * Extract enriched headers from a response object
+ * These headers are prefixed with 'X-Enriched-' by the middleware
+ *
+ * @param headers - Response headers (can be Headers object or plain object)
+ * @returns Extracted enriched headers without the prefix
+ *
+ * @example
+ * ```typescript
+ * // Extract from fetch response
+ * const response = await fetch(url);
+ * const enrichedHeaders = extractEnrichedHeaders(response.headers);
+ *
+ * // Use in another API call
+ * const anotherClient = createApiClient({
+ *   headers: enrichedHeaders
+ * });
+ * ```
+ */
+export declare function extractEnrichedHeaders(headers: Headers | Record<string, string | string[] | undefined>): ApiHeaders;
+/**
+ * Transfer enriched headers from one response to another request
+ * Useful for microservice-to-microservice communication
+ *
+ * @param sourceHeaders - Headers from the source response
+ * @param targetConfig - Target API configuration to enhance
+ * @returns Enhanced configuration with transferred headers
+ *
+ * @example
+ * ```typescript
+ * // Service A calls Service B
+ * const responseB = await apiServiceB.getData();
+ *
+ * // Extract and transfer headers to Service C
+ * const configC = transferEnrichedHeaders(
+ *   responseB.headers,
+ *   { timeout: 10000 }
+ * );
+ *
+ * const responseC = await apiServiceC.process(data, configC);
+ * ```
+ */
+export declare function transferEnrichedHeaders<T extends {
+    headers?: ApiHeaders;
+}>(sourceHeaders: Headers | Record<string, string | string[] | undefined>, targetConfig?: T): T;
+/**
+ * Check if headers contain enriched context headers
+ *
+ * @param headers - Headers to check
+ * @returns True if enriched headers are present
+ */
+export declare function hasEnrichedHeaders(headers: Headers | Record<string, string | string[] | undefined>): boolean;
+export declare function extractHeadersFromRequest<T extends {
+    headers?: Record<string, string>;
+}>(request: T): RequestHeaderExtraction;
+export declare function extractClientHints<T extends {
+    headers?: Record<string, string>;
+}>(request: T): ApiHeaders;
+export declare function extractDeviceInfo<T extends {
+    headers?: Record<string, string>;
+}>(request: T): ApiHeaders;
+export declare function extractNetworkInfo<T extends {
+    headers?: Record<string, string>;
+}>(request: T): ApiHeaders;
+export declare function prepareEnrichedHeadersForTransfer(headers: ApiHeaders): ApiHeaders;
+//# sourceMappingURL=extract.d.ts.map

package/dist/api/headers/extract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../../src/api/headers/extract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAC/D,UAAU,CA4BZ;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,SAAS;IAAE,OAAO,CAAC,EAAE,UAAU,CAAA;CAAE,EACxE,aAAa,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,EACtE,YAAY,GAAE,CAAW,GACxB,CAAC,CAUH;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAC/D,OAAO,CAkBT;AAGD,wBAAgB,yBAAyB,CAAC,CAAC,SAAS;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EACtF,OAAO,EAAE,CAAC,GACT,uBAAuB,CAMzB;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EAC/E,OAAO,EAAE,CAAC,GACT,UAAU,CAaZ;AAED,wBAAgB,iBAAiB,CAAC,CAAC,SAAS;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EAC9E,OAAO,EAAE,CAAC,GACT,UAAU,CAWZ;AAED,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EAC/E,OAAO,EAAE,CAAC,GACT,UAAU,CAaZ;AAED,wBAAgB,iCAAiC,CAAC,OAAO,EAAE,UAAU,GAAG,UAAU,CAWjF"}

package/dist/api/headers/headerBuilder.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Header Builder Utilities
+ * Fluent API for building HTTP headers, following TASK-016 specification
+ */
+import type { ApiHeaders, ContentType, AcceptType, AuthType, PlatformType, HeaderBuilderLike } from '@plyaz/types/api';
+/**
+ * Header builder with fluent API for constructing HTTP headers
+ *
+ * @example
+ * ```typescript
+ * const headers = new HeaderBuilder()
+ *   .auth('Bearer token123')
+ *   .contentType('json')
+ *   .locale('en-US')
+ *   .tenant('acme-corp')
+ *   .build();
+ * ```
+ */
+export declare class HeaderBuilder implements HeaderBuilderLike {
+    private _headers;
+    /**
+     * Get read-only access to headers (for HeaderBuilderLike compatibility)
+     */
+    get headers(): ApiHeaders;
+    /**
+     * Set authentication header
+     *
+     * @param token - Authentication token or credentials
+     * @param type - Authentication type (Bearer, Basic, ApiKey)
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.auth('token123') // Bearer token123
+     * builder.auth('token123', 'Basic') // Basic token123
+     * builder.auth('key123', 'ApiKey') // x-api-key: key123
+     * ```
+     */
+    auth(token: string, type?: AuthType): this;
+    /**
+     * Set content type header
+     *
+     * @param type - Content type (json, form, multipart, or custom)
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.contentType('json') // application/json
+     * builder.contentType('form') // application/x-www-form-urlencoded
+     * builder.contentType('multipart') // multipart/form-data
+     * builder.contentType('application/vnd.api+json') // custom type
+     * ```
+     */
+    contentType(type: ContentType): this;
+    /**
+     * Set accept header
+     *
+     * @param type - Accept type (json, xml, html, or custom)
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.accept('json') // application/json
+     * builder.accept('xml') // application/xml
+     * builder.accept('stream') // text/event-stream
+     * ```
+     */
+    accept(type: AcceptType): this;
+    /**
+     * Set locale/language headers
+     *
+     * @param locale - Locale string (e.g., 'en-US', 'fr-FR')
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.locale('en-US') // Sets both accept-language and x-locale
+     * ```
+     */
+    locale(locale: string): this;
+    /**
+     * Set platform header
+     *
+     * @param platform - Platform identifier
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.platform('ios') // x-platform: ios
+     * builder.platform('web') // x-platform: web
+     * ```
+     */
+    platform(platform: PlatformType): this;
+    /**
+     * Set tenant for multi-tenant applications
+     *
+     * @param tenantId - Tenant identifier
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.tenant('acme-corp') // x-tenant-id: acme-corp
+     * ```
+     */
+    tenant(tenantId: string): this;
+    /**
+     * Set user context
+     *
+     * @param userId - User identifier
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.user('user123') // x-user-id: user123
+     * ```
+     */
+    user(userId: string): this;
+    /**
+     * Set application version
+     *
+     * @param version - Application version
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.version('1.2.3') // x-app-version: 1.2.3
+     * ```
+     */
+    version(version: string): this;
+    /**
+     * Set feature flags
+     *
+     * @param flags - Feature flags as array or comma-separated string
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.features(['featureA', 'featureB']) // x-feature-flag: featureA,featureB
+     * builder.features('featureA,featureB') // x-feature-flag: featureA,featureB
+     * ```
+     */
+    features(flags: string[] | string): this;
+    /**
+     * Set device identifier
+     *
+     * @param deviceId - Device identifier
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.device('device123') // x-device-id: device123
+     * ```
+     */
+    device(deviceId: string): this;
+    /**
+     * Set session identifier
+     *
+     * @param sessionId - Session identifier
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.session('sess_abc123') // x-session-id: sess_abc123
+     * ```
+     */
+    session(sessionId: string): this;
+    /**
+     * Set client identifier
+     *
+     * @param clientId - Client identifier
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.client('mobile-app') // x-client-id: mobile-app
+     * ```
+     */
+    client(clientId: string): this;
+    /**
+     * Add correlation ID for distributed tracing
+     *
+     * @param id - Correlation ID (auto-generated if not provided)
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.correlationId() // x-correlation-id: auto-generated
+     * builder.correlationId('corr_123') // x-correlation-id: corr_123
+     * ```
+     */
+    correlationId(id?: string): this;
+    /**
+     * Add request ID for tracking
+     *
+     * @param id - Request ID (auto-generated if not provided)
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.requestId() // x-request-id: auto-generated
+     * builder.requestId('req_123') // x-request-id: req_123
+     * ```
+     */
+    requestId(id?: string): this;
+    /**
+     * Add trace ID for distributed tracing
+     *
+     * @param traceId - Trace ID (auto-generated if not provided)
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.traceId() // x-trace-id: auto-generated
+     * builder.traceId('trace_123') // x-trace-id: trace_123
+     * ```
+     */
+    traceId(traceId?: string): this;
+    /**
+     * Add span ID for distributed tracing
+     *
+     * @param spanId - Span ID
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.spanId('span_123') // x-span-id: span_123
+     * ```
+     */
+    spanId(spanId: string): this;
+    /**
+     * Add AJAX request marker
+     *
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.ajax() // x-requested-with: XMLHttpRequest
+     * ```
+     */
+    ajax(): this;
+    /**
+     * Add custom header
+     *
+     * @param key - Header name
+     * @param value - Header value
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.custom('x-custom-header', 'custom-value')
+     * ```
+     */
+    custom(key: string, value: string): this;
+    /**
+     * Add multiple headers at once
+     *
+     * @param headers - Headers object to merge
+     * @returns Builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * builder.merge({ 'x-custom-1': 'value1', 'x-custom-2': 'value2' })
+     * ```
+     */
+    merge(headers: Record<string, string>): this;
+    /**
+     * Get built headers object
+     *
+     * @returns Headers object ready for use with API requests
+     *
+     * @example
+     * ```typescript
+     * const headers = builder.build();
+     * await fetch('/api/data', { headers });
+     * ```
+     */
+    build(): ApiHeaders;
+    /**
+     * Clear all headers and reset builder
+     *
+     * @returns Builder instance for chaining
+     */
+    clear(): this;
+    /**
+     * Remove specific header
+     *
+     * @param key - Header name to remove
+     * @returns Builder instance for chaining
+     */
+    remove(key: string): this;
+}
+/**
+ * Create a new header builder instance
+ *
+ * @returns New HeaderBuilder instance
+ *
+ * @example
+ * ```typescript
+ * import { headers } from '@plyaz/api/headers';
+ *
+ * const myHeaders = headers()
+ *   .auth('Bearer token')
+ *   .contentType('json')
+ *   .build();
+ * ```
+ */
+export declare function headers(): HeaderBuilder;
+//# sourceMappingURL=headerBuilder.d.ts.map

package/dist/api/headers/headerBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headerBuilder.d.ts","sourceRoot":"","sources":["../../../src/api/headers/headerBuilder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,iBAAiB,EAClB,MAAM,kBAAkB,CAAC;AAM1B;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,YAAW,iBAAiB;IACrD,OAAO,CAAC,QAAQ,CAAkB;IAElC;;OAEG;IACH,IAAI,OAAO,IAAI,UAAU,CAExB;IAED;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,QAAmB,GAAG,IAAI;IASpD;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI;IAapC;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAY9B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAM5B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAKtC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;;;;;;;OAUG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK1B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI;IAKxC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAKhC;;;;;;;;;;OAUG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAKhC;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAK5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAK/B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5B;;;;;;;;;OASG;IACH,IAAI,IAAI,IAAI;IAKZ;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKxC;;;;;;;;;;OAUG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAS5C;;;;;;;;;;OAUG;IACH,KAAK,IAAI,UAAU;IAInB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAKb;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAI1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,IAAI,aAAa,CAEvC"}

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

@@ -0,0 +1,37 @@
+/**
+ * Header Management Utilities
+ * Comprehensive header management for API requests
+ *
+ * This module provides:
+ * - Fluent API for building headers
+ * - Common header presets for different scenarios
+ * - Header merging and management utilities
+ * - Integration with network detection
+ *
+ * @example
+ * ```typescript
+ * import { headers, headerPresets, mergeHeaders } from '@plyaz/api/headers';
+ *
+ * // Using header builder
+ * const authHeaders = headers()
+ *   .auth('Bearer token123')
+ *   .contentType('json')
+ *   .tenant('acme-corp')
+ *   .build();
+ *
+ * // Using presets
+ * const jsonHeaders = headerPresets.json();
+ *
+ * // Merging headers
+ * const finalHeaders = mergeHeaders(jsonHeaders, authHeaders);
+ * ```
+ */
+export { HeaderBuilder, headers } from './headerBuilder';
+export { headerPresets, getPresetNames, hasPreset } from './presets';
+export { mergeHeaders, mergeHeadersWithImmutable, combineHeaderValues, parseHeaderValues, } from './merge';
+export { getCacheAffectingHeaders, getNonCacheAffectingHeaders, sanitizeHeaders, removeSensitiveHeaders, normalizeHeaders, hasAuthentication, getAuthenticationType, validateHeaders, getHeaderFingerprint, } from './utils';
+export { getNetworkInfoFromHeaders, getNetworkQualityFromHeaders, isDataSaverEnabledFromHeaders, getNetworkConfigFromHeaders, getClientHintHeaders, withNetworkDetection, } from '../network/headers';
+export { buildEnrichedHeaders, sanitizeHeaderValue, enrichedHeaderPresets } from './enriched';
+export { getOrCompute, invalidateHeaderCache, clearHeaderCache } from './cache';
+export { extractHeadersFromRequest, extractClientHints, extractDeviceInfo, extractNetworkInfo, } from './extract';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/api/headers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAGzD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAGrE,OAAO,EACL,YAAY,EACZ,yBAAyB,EACzB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,wBAAwB,EACxB,2BAA2B,EAC3B,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,yBAAyB,EACzB,4BAA4B,EAC5B,6BAA6B,EAC7B,2BAA2B,EAC3B,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAG9F,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGhF,OAAO,EACL,yBAAyB,EACzB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,WAAW,CAAC"}