@plyaz/api 1.0.2 → 1.1.1

package/README.md

@@ -1,693 +1,783 @@
 # @plyaz/api
 
-Unified API client for seamless backend communication across the Plyaz platform. Provides type-safe endpoints, React Query integration, consistent error handling, and intelligent request management - supporting Web3, authentication, and tokenized experiences.
+> ⚡ Smart, type-safe API client for the Plyaz ecosystem with zero-configuration intelligence
 
-## Overview
+[![Version](https://img.shields.io/badge/version-1.0.2-blue.svg)](https://github.com/Plyaz-Official/api)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/license-ISC-green.svg)](LICENSE)
 
-The @plyaz/api package provides a unified API client for communicating with backend services across the Plyaz platform. It offers type-safe API endpoints, consistent error handling, and integration with React Query for efficient data fetching. This package serves as the core communication layer between frontend applications and backend services.
+**@plyaz/api** is the unified API client for seamless backend communication across the Plyaz platform. Built on [fetchff](https://www.npmjs.com/package/fetchff), it provides intelligent defaults, automatic optimizations, and full TypeScript support for Web3, authentication, and tokenized experiences.
 
-> **Note**: This package is designed as a shared package that works across frontend and backend contexts, with platform-specific implementations where necessary. It integrates seamlessly with the @plyaz/* ecosystem of shared packages.
+---
 
-## Features
+## ✨ Why @plyaz/api?
 
-- **Type-Safe API Client**: Built on `fetchff` with full TypeScript support
-- **React Query Integration**: Ready-to-use hooks for data fetching and mutations
-- **Consistent Error Handling**: Integrated with `@plyaz/errors` for standardized errors
-- **Request Management**: Deduplication, cancellation, and retry mechanisms
-- **Authentication Support**: Built-in auth token handling and interceptors
-- **Pagination Support**: Cursor and offset-based pagination utilities
-- **Performance Optimized**: Request batching, caching, and queue management
-- **Event Integration**: Lifecycle events via `@plyaz/events`
-- **Third-Party APIs**: Support for Alchemy, The Graph, and other integrations
+### Zero-Configuration Smart Features
 
-## Installation
+The API client works intelligently out of the box:
 
-```bash
-pnpm add @plyaz/api
+| Feature | What It Does | Default Behavior | When to Override |
+|---------|--------------|------------------|------------------|
+| **Request Deduplication** | Prevents duplicate requests | 2-second window | Real-time data needs |
+| **Automatic Retry** | Retries failed requests | 3 retries with exponential backoff | Critical operations |
+| **Response Caching** | Caches successful responses | 10min cache, 2min stale | Static vs real-time data |
+| **Network Adaptation** | Adjusts to connection quality | Automatic detection | Custom performance needs |
+| **Smart Headers** | Sets appropriate headers | JSON content-type | File uploads, GraphQL |
+| **Timeout Handling** | Prevents hanging requests | 30 seconds | Long-running operations |
+
+### Pre-Configured Endpoints
+
+All endpoints are pre-defined and fully typed. No configuration needed:
+
+```typescript
+const api = await createApiClient({ baseURL: 'https://api.example.com' });
+
+// Pre-configured, fully typed methods ready to use!
+const { data } = await api.getUsers();
+const { data: campaign } = await api.getCampaign({ id: '123' });
 ```
 
-## Development
+---
+
+## 📦 Installation
 
-### Prerequisites
+```bash
+pnpm add @plyaz/api
+```
 
+**Requirements:**
 - Node.js >= 22.4.0
 - pnpm >= 8.0.0
 
-### Setup
+---
 
-```bash
-# Clone the repository
-git clone https://github.com/Plyaz-Official/api.git
-cd api
+## 🚀 Quick Start
 
-# Install dependencies
-pnpm install
+### Simple REST API (2 lines)
 
-# Start development (watch mode)
-pnpm dev
+```typescript
+const api = await createApiClient({ baseURL: 'https://api.example.com' });
+const { data } = await api.getUsers();
 ```
 
-### Available Scripts
+### Authenticated API
 
-```bash
-# Development
-pnpm dev                # Start development with watch mode (alias: pnpm build:watch)
-pnpm build:watch        # Watch files and rebuild on changes
-
-# Building
-pnpm build              # Full build (clean + JS + TypeScript declarations)
-pnpm build:js           # Build JavaScript bundles with tsup
-pnpm build:types        # Generate TypeScript declaration files
-pnpm clean              # Remove dist directory
-
-# Testing
-pnpm test               # Run all tests once
-pnpm test:watch         # Run tests in watch mode
-pnpm test:coverage      # Run tests with coverage report
-pnpm test:ui            # Open Vitest UI for interactive testing
-pnpm test:ci            # Run tests in CI environment
-
-# Code Quality
-pnpm lint               # Check code with ESLint
-pnpm lint:fix           # Auto-fix ESLint issues
-pnpm format             # Format code with Prettier
-pnpm format:check       # Check if code is formatted correctly
-pnpm type:check         # Type check with TypeScript (no emit)
-
-# Security & Auditing
-pnpm audit              # Basic security audit
-pnpm audit:moderate     # Check for moderate+ vulnerabilities
-pnpm audit:high         # Check for high+ vulnerabilities
-pnpm audit:critical     # Check only critical vulnerabilities
-pnpm audit:fix          # Auto-fix vulnerabilities where possible
-pnpm audit:enhanced     # Enhanced audit with audit-ci
-pnpm security:check     # Full security check (moderate + audit-ci)
-
-# Publishing
-pnpm prepublishOnly     # Runs build, test, and lint before publishing
+```typescript
+const api = await createApiClient({
+  baseURL: 'https://api.example.com',
+  headers: async () => ({
+    Authorization: `Bearer ${await getToken()}`
+  })
+});
 ```
 
-## Package Structure
+### Mobile App (Network-aware)
 
+```typescript
+const api = await createApiClient({
+  baseURL: 'https://api.example.com',
+  performanceStrategy: 'mobile',
+  networkAware: { enabled: true }
+});
 ```
-@plyaz/api/
-├── src/
-│   ├── client/                 # API client implementation
-│   │   ├── createApiClient.ts  # Factory function for API client
-│   │   ├── defaultConfig.ts    # Default configuration
-│   │   └── types.ts            # Client-specific types
-│   ├── endpoints/              # API endpoint definitions
-│   │   ├── auth.ts             # Authentication endpoints
-│   │   ├── user.ts             # User endpoints
-│   │   ├── nft.ts              # NFT endpoints
-│   │   └── transaction.ts      # Transaction endpoints
-│   ├── services/               # API service functions
-│   │   ├── auth.ts             # Auth service functions
-│   │   ├── user.ts             # User service functions
-│   │   └── nft.ts              # NFT service functions
-│   ├── integrations/           # Third-party API integrations
-│   │   └── alchemy/            # Alchemy API integration
-│   ├── hooks/                  # React Query hooks
-│   │   ├── auth/               # Auth-related hooks
-│   │   └── user/               # User-related hooks
-│   ├── utils/                  # Utility functions
-│   │   ├── error-handler.ts    # Error handling utilities
-│   │   └── pagination.ts       # Pagination utilities
-│   └── index.ts                # Main exports
-```
-
-## Quick Start
 
-### Basic Setup
-
-#### Initialize API Client
+### Real-Time Dashboard
 
 ```typescript
-import { createApiClient } from '@plyaz/api';
-
-// Create API client with custom configuration
-const api = createApiClient({
-  baseURL: process.env.NEXT_PUBLIC_API_URL,
-  timeout: 30000,
-  headers: {
-    'Content-Type': 'application/json'
-  }
+const api = await createApiClient({
+  baseURL: 'https://api.example.com',
+  unifiedStrategy: 'realtime',
+  revalidationStrategy: 'aggressive'
 });
-
-// Or use the default pre-configured client
-import { api } from '@plyaz/api';
 ```
 
-#### With Authentication
+---
+
+## 🎯 Complete Feature Set
+
+### Core Request Features
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **🔒 Type Safety** | Auto | Full TypeScript support with intelligent type inference | Enabled | N/A - Always active |
+| **⚡ Smart Defaults** | Auto | Zero-config setup, works perfectly out of the box | Enabled | Override via config |
+| **📋 Pre-Configured Endpoints** | Auto | Typed endpoint methods ready to use | All endpoints | Override with `endpoints` |
+| **🔁 Request Deduplication** | Auto | Prevents duplicate requests within time window | 2-second window | `dedupeTime: number` |
+| **⏱️ Timeout Handling** | Auto | Prevents hanging requests | 30 seconds | `timeout: number` |
+| **🚦 Request Cancellation** | Manual | AbortController support | Available | `cancellable: true` |
+| **🔗 Request Chaining** | Manual | Chain multiple requests efficiently | Available | Standard usage |
+| **🔌 Interceptors** | Manual | Request/response/error interceptors | None | `onRequest`, `onResponse`, `onError` |
+
+### Retry & Resilience
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **🔄 Retry Logic** | Auto | Exponential backoff for failed requests | 3 retries, 1s delay, 1.5x backoff | `retry: { retries, delay, backoff }` |
+| **🎯 Retry Strategies** | Manual | Customizable retry strategies (none, minimal, standard, etc.) | `standard` | `retryStrategy: string` |
+| **🔍 Retry Conditions** | Manual | Conditional retry based on status codes, errors | Standard HTTP errors | `retryOn: number[]` |
+| **⚠️ Status Code Limits** | Manual | Define retry behavior per status code | 408, 429, 500, 502, 503, 504 | Custom limits |
+
+### Caching & Revalidation
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **💾 Response Caching** | Auto | Multi-level caching (memory, session, persistent) | 10min cache, 2min stale | `cacheTime`, `staleTime` |
+| **📦 Cache Strategies** | Manual | 6 strategies (none, minimal, standard, moderate, aggressive, offline) | `standard` | `cacheStrategy: string` |
+| **🔑 Cache Key Patterns** | Manual | Custom cache key generation patterns | Standard pattern | `buildCacheKey()` |
+| **🗑️ Cache Invalidation** | Manual | Invalidation scenarios and utilities | Available | `mutate()`, `deleteCache()` |
+| **♻️ Revalidation** | Auto | 9 strategies (focus, reconnect, interval, etc.) | On focus/reconnect | `revalidationStrategy: string` |
+| **🔄 Manual Revalidation** | Manual | Programmatic cache revalidation | Available | `revalidate()`, `revalidateAll()` |
+
+### Network & Performance
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **🌐 Network Detection** | Auto | Detects connection quality and adapts | Enabled | `networkAware: { enabled }` |
+| **📊 Network Quality** | Auto | Monitors network quality (excellent, good, slow, offline) | Automatic | Auto-detection |
+| **🎯 Performance Strategies** | Manual | Optimized presets (mobile, realtime, static, etc.) | `standard` | `performanceStrategy: string` |
+| **⚙️ Network Config Manager** | Auto | Manages network-optimized configurations | Enabled | Automatic management |
+| **💻 Platform Detection** | Auto | Detects platform (browser, Node.js, Electron, etc.) | Automatic | Auto-detection |
+| **📱 Device Detection** | Auto | Detects device type and capabilities | Automatic | Auto-detection |
+| **🔍 Client Hints** | Auto | Enhanced client hints for network optimization | Enabled | Automatic detection |
+| **⚡ Adaptive Performance** | Auto | Adapts behavior based on device/network | Enabled | Automatic adaptation |
+| **📈 Performance Monitoring** | Auto | Tracks request timing and performance metrics | Enabled | Automatic tracking |
+| **💤 Data Saver Mode** | Auto | Detects and respects data saver preferences | Enabled | Automatic detection |
+
+### Headers & Regional
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **📝 Header Management** | Auto | Smart header enrichment and presets | JSON content-type | `headers: {}` or `headers: () => {}` |
+| **✨ Enriched Headers** | Auto | Automatic header enrichment with platform/network data | Enabled | `enrichedHeaders: boolean` |
+| **🎨 Header Presets** | Manual | Pre-configured header sets (json, multipart, etc.) | Available | `headerPresets` |
+| **🔐 Authentication** | Manual | Token management and auth interceptors | None | `onRequest` interceptor |
+| **🌍 Regional Compliance** | Auto | GDPR, CCPA, APAC support | Enabled | `regionalConfig` |
+| **🗺️ Regional Detection** | Auto | Auto-detect user region for compliance | Enabled | Automatic detection |
+| **🎯 Regional Presets** | Manual | Region-specific configuration presets | Available | Regional presets |
+
+### Configuration Management
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **📊 Config Levels** | Auto | 4-level hierarchy (global → client → request → temporary) | All levels active | Config hierarchy |
+| **🔄 Config Merging** | Auto | Smart deep merging of configuration objects | Enabled | Automatic merging |
+| **⚙️ Merge Strategies** | Manual | Custom merge strategies for config properties | Deep merge | Custom strategies |
+| **🔀 Temporary Overrides** | Manual | Temporary config overrides with auto-reset | Available | `applyTemporaryOverride()` |
+| **📋 Override Tracking** | Auto | Tracks all configuration overrides | Enabled | Automatic tracking |
+| **🎯 Config Update Strategy** | Manual | 3 strategies (merge, replace, temporary) | Merge | `configOverride.strategy` |
+| **🎨 Handler Strategy** | Manual | 4 strategies (merge, replace, prepend, append) | Merge | `configOverride.handlerStrategy` |
+| **📍 Event Scopes Control** | Manual | Control which scopes receive events | All scopes | `configOverride.eventScopes` |
+| **🧹 Auto-Clear Overrides** | Manual | Auto-clear temporary overrides after request | Disabled | `configOverride.clearOnComplete` |
+| **⚡ Priority Mode** | Manual | Only highest priority handler runs | Disabled | `configOverride.priority` |
+| **💾 Preserved Config** | Auto | Preserves original config for restoration | Enabled | Automatic preservation |
+| **🔍 Config Debugger** | Manual | Detect configuration conflicts | Available | `useApiConfigConflicts()` |
+| **⚠️ Conflict Detection** | Manual | Detects conflicting configurations | Available | `checkConflicts()` |
+| **🌐 Global Config API** | Manual | Set/get/update global configuration | Available | Global config methods |
+| **📝 Config Validation** | Auto | Validates configuration at runtime | Enabled | Automatic validation |
+
+### Tracking & Telemetry
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **🎛️ Master Tracking Switch** | Manual | Enable/disable all tracking features | Enabled | `tracking.enabled` |
+| **📊 Operation Tracking** | Manual | Track operations for debugging (debugger queue) | Enabled | `tracking.operations` |
+| **📡 Event Emission Control** | Manual | Control whether events are emitted/processed | Enabled | `tracking.events` |
+| **⚙️ Queue Strategy** | Manual | 4 strategies (immediate, batch, throttle, debounce) | Batch | `tracking.queueStrategy` |
+| **📤 Event Strategy** | Manual | Event processing (immediate, queued) | Immediate | `tracking.eventStrategy` |
+| **⚡ Performance Mode** | Manual | 3 modes (full, minimal, off) | Full | `tracking.performanceMode` |
+| **📜 History Size Limit** | Manual | Max operations to keep in history | 1000 | `tracking.historySize` |
+| **⚠️ Max Conflicts Tracking** | Manual | Max conflicts to track | 100 | `tracking.maxConflicts` |
+| **🚫 Skip History** | Manual | Skip adding entries to history for this request | Disabled | `tracking.skipHistory` |
+| **📈 Telemetry Collection** | Manual | Analytics/monitoring data collection | Disabled | `tracking.telemetry` |
+| **🎯 Context-Aware Tracking** | Auto | Different defaults for test vs production | Auto-detected | Environment-based |
+
+### Events & Monitoring
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **📊 Event System** | Auto | 80+ events across 8 namespaces | Enabled | `on()`, `off()`, `emit()` |
+| **🎯 Event Namespaces** | Auto | 8 namespaces (headers, network, errors, debug, config, perf, client, cache) | All active | Namespace filtering |
+| **📍 Event Scopes** | Auto | 4 scopes (GLOBAL → CONFIG → CLIENT → REQUEST) | All scopes | Scope-based handlers |
+| **🔄 Handler Strategies** | Manual | 4 strategies (merge, replace, prepend, append) | Merge | `handlerStrategy` config |
+| **⚡ Event Priorities** | Auto | Priority-based event execution | By scope priority | Automatic prioritization |
+| **⚙️ Queue System** | Auto | Priority-based async operation processing | Enabled | Automatic batching |
+| **📦 Batch Processing** | Auto | Batches events for efficient processing | 10ms window | Batch config |
+| **🔔 Network Events** | Auto | Network state change events | Enabled | Event subscriptions |
+| **📦 PubSub System** | Manual | Real-time subscriptions and updates | Available | Event subscriptions |
+| **🎣 React Hooks** | Manual | 4 monitoring hooks (monitor, debug, config, network) | Available | `useApiMonitor()`, etc. |
+| **📈 Event Statistics** | Manual | Get stats on event emissions and handlers | Available | `getEventStats()` |
+| **🎯 Scoped Handlers** | Manual | Register handlers at specific scopes | Available | Scope parameter |
+| **⏱️ Once Handlers** | Manual | Handlers that execute only once | Available | `once()` method |
+| **🚫 Handler Removal** | Manual | Unregister event handlers | Available | `off()` method |
+
+### Debugging & Diagnostics
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **🐛 Debug Tools** | Manual | Built-in debugging and analysis tools | Available | `getDebugInfo()` |
+| **📋 Debug Reporting** | Manual | Generate comprehensive debug reports | Available | `generateReport()` |
+| **📊 Operation Tracking** | Auto | Tracks all API operations for debugging | Enabled | Automatic tracking |
+| **📜 History Tracking** | Auto | Maintains request/response history (LRU) | Enabled | Automatic tracking |
+| **🔍 Issue Analysis** | Manual | Analyzes issues and provides recommendations | Available | Debug factories |
+| **📊 Performance Analysis** | Manual | Analyzes performance bottlenecks | Available | Performance factory |
+
+### Strategies & Patterns
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **🎯 Unified Strategies** | Manual | Combined strategy presets (realtime, mobile, etc.) | Available | `unifiedStrategy: string` |
+| **🔄 Polling Strategies** | Manual | Progressive, conditional, visibility-aware polling | Available | Polling config |
+| **♻️ Revalidation Strategies** | Manual | 9 revalidation patterns | On focus/reconnect | Strategy config |
+| **⏰ Visibility-Aware** | Auto | Pauses operations when tab inactive | Enabled | Automatic behavior |
+| **📈 Progressive Polling** | Manual | Gradually increasing poll intervals | Available | Progressive config |
+| **🎯 Conditional Polling** | Manual | Poll based on conditions | Available | Conditional config |
+
+### Error Handling
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **❌ Error Handling** | Auto | Standardized error handling with @plyaz/errors | 18 error types | `strategy: 'softFail' \| 'reject'` |
+| **🎯 Error Strategies** | Manual | softFail, reject, silent, defaultResponse | `softFail` | `strategy` config |
+| **🔔 Error Events** | Auto | Error event handlers (global, instance, once) | Enabled | Error event handlers |
+| **📊 Error Categories** | Auto | Categorized errors (network, validation, auth, etc.) | Automatic | Built-in categories |
+
+### Framework Integration
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **🚀 Next.js Middleware** | Manual | Next.js-specific integrations | Available | Framework middleware |
+| **⚡ Express Middleware** | Manual | Express server-side integration | Available | Framework middleware |
+| **🎯 NestJS Integration** | Manual | NestJS decorators and providers | Available | Framework middleware |
+| **💻 SSR Support** | Auto | Server-side rendering safe operations | Enabled | SSR-safe configs |
+
+### Utilities
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **🆔 ID Generation** | Auto | Request ID, Correlation ID generation | Enabled | Automatic generation |
+| **⏱️ Time Utilities** | Manual | Time formatting, duration, delays | Available | Utility functions |
+| **🔢 Math Utilities** | Manual | Percentage, clamping, averaging | Available | Utility functions |
+| **📝 String Utilities** | Manual | String manipulation helpers | Available | Utility functions |
+| **📦 Object Utilities** | Manual | Deep merge, clone, access | Available | Utility functions |
+| **🔍 Type Guards** | Manual | Runtime type checking | Available | Utility functions |
+| **✅ Validation** | Manual | Data validation utilities | Available | Utility functions |
+| **⏰ Interval Manager** | Manual | Manage polling intervals | Available | Utility functions |
+| **🎨 JSON Utilities** | Manual | Safe JSON parsing/stringifying | Available | Utility functions |
+
+### Endpoints & Services
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **📋 Endpoint Builders** | Manual | Fluent API for building endpoint configurations | Available | Endpoint builder pattern |
+| **🏗️ Endpoint Utilities** | Manual | Helper utilities for endpoint management | Available | Utility functions |
+| **🎯 Services Layer** | Manual | Service functions with smart defaults per HTTP method | Available | `ServiceOptions` |
+| **🔧 Campaign Services** | Manual | Complete CRUD operations for campaigns | Available | Service layer |
+| **🎣 React Query Hooks** | Manual | Pre-built hooks (useCampaigns, useCreateCampaign, etc.) | Available | Hook factories |
+| **📦 Endpoint Registry** | Auto | Maintains registry of all configured endpoints | Enabled | Automatic registration |
+| **🔍 Endpoint Validation** | Auto | Validates endpoint configurations | Enabled | Automatic validation |
+
+### Request Management
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **📝 Request Preparation** | Auto | Prepares requests with proper formatting | Enabled | Automatic preparation |
+| **🚫 Abort Management** | Manual | Manage request cancellation via AbortController | Available | Abort utilities |
+| **🔍 Request Routing** | Auto | Routes requests through proper pipeline | Enabled | Automatic routing |
+| **📊 Request Utils** | Manual | Request preparation and management utilities | Available | Utility functions |
+| **🆔 Request ID Tracking** | Auto | Automatic request ID generation and tracking | Enabled | Automatic generation |
+| **🔗 Correlation ID** | Auto | Correlation ID for distributed tracing | Enabled | Automatic generation |
+
+### Advanced Features
+
+| Feature | Type | Description | Default | Configuration |
+|---------|------|-------------|---------|---------------|
+| **🔍 Request Fingerprinting** | Auto | Generates unique fingerprints for requests | Enabled | Automatic generation |
+| **🔐 Header Sanitization** | Auto | Removes sensitive headers from logs | Enabled | Automatic sanitization |
+| **🔍 Authentication Detection** | Auto | Detects auth type from headers | Enabled | Automatic detection |
+| **📦 Multiple Clients** | Manual | Create and manage multiple client instances | Available | Standard usage |
+| **🎯 Extended API Client** | Manual | ApiClientWithEvents with enhanced features | Available | Create extended client |
+| **🔄 Client Factory Pattern** | Manual | Factory pattern for creating specialized clients | Available | Factory functions |
+| **🎨 Color Utilities** | Manual | Console color utilities for logging | Available | Color helpers |
+| **🌐 Environment Detection** | Auto | Detects runtime environment (browser/Node/Deno/Bun) | Enabled | Automatic detection |
+| **📱 Push Notification Support** | Auto | Detects push notification capabilities | Enabled | Automatic detection |
+
+### Legend
+- **Auto**: Enabled by default, works automatically
+- **Manual**: Available when needed, requires explicit usage
+- **Total Features**: **110+** comprehensive features
+
+---
+
+## ⚙️ Service Configuration Reference
+
+### ServiceOptions Interface
 
 ```typescript
-import { createApiClient } from '@plyaz/api';
+interface ServiceOptions {
+  /**
+   * Optional API client instance override
+   * Use this when you need a different client configuration
+   * The client should have all endpoints from EndpointsList
+   */
+  apiClient?: ApiClientWithEvents<ClientEventManager, TEndpoints>;
+
+  /**
+   * Optional API configuration updates
+   * By default applied with { strategy: 'temporary' } mode (affects only this request)
+   * Can be overridden via updateConfigOptions
+   */
+  apiConfig?: Partial<ApiConfig>;
+
+  /**
+   * Optional update config options
+   * Controls how apiConfig is applied to the client
+   *
+   * Defaults to: { strategy: 'temporary' }
+   * - 'temporary': Only affects this request (highest priority)
+   * - 'merge': Merges with client config (persists)
+   * - 'replace': Replaces client config (persists)
+   */
+  updateConfigOptions?: UpdateConfigOptions;
+}
 
-const api = createApiClient({
-  onRequest: (config) => {
-    const token = localStorage.getItem('auth_token');
-    if (token) {
-      config.headers = {
-        ...config.headers,
-        Authorization: `Bearer ${token}`
-      };
-    }
-    return config;
-  }
-});
+/**
+ * Config update options
+ */
+interface UpdateConfigOptions {
+    strategy?: ConfigUpdateStrategy;
+    priority?: number;
+    namespace?: string;
+    scope?: string;
+    preserveFields?: (keyof ApiConfig)[];
+}
 ```
 
-### React/Next.js Integration
+### Available Unified Strategies
+
+| Strategy | Cache | Retry | Use Case | Default For |
+|----------|-------|-------|----------|-------------|
+| **realtime** | None | Low | Live data, mutations | POST/PUT/DELETE |
+| **interactive** | 2min stale, 10min cache | Medium | User-facing lists | GET (lists) |
+| **background** | 10min stale, 30min cache | Medium | Background refreshes | GET (single items) |
+| **mobile** | 5min stale, 15min cache | High | Mobile networks | - |
+| **static** | 1hr stale, 24hr cache | Low | Rarely-changing data | - |
 
-#### Query Hook Usage
+### Common Configuration Patterns
 
 ```typescript
-import { useGetUserProfile } from '@plyaz/api/hooks';
+// Pattern 1: Mobile-optimized
+const serviceOptions: ServiceOptions = {
+  apiConfig: {
+    unifiedStrategy: 'mobile',
+    networkAware: { enabled: true, adaptConfig: true },
+    retry: { retries: 5, backoff: 2 }
+  }
+};
 
-export function UserProfile({ walletAddress }: { walletAddress: string }) {
-  const { data, error, isLoading } = useGetUserProfile(
-    { walletAddress },
-    { includeDetails: true }
-  );
+// Pattern 2: Real-time dashboard
+const serviceOptions: ServiceOptions = {
+  apiConfig: {
+    unifiedStrategy: 'realtime',
+    revalidationStrategy: 'aggressive',
+    cacheStrategy: 'none'
+  }
+};
 
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
+// Pattern 3: Static content
+const serviceOptions: ServiceOptions = {
+  apiConfig: {
+    unifiedStrategy: 'static',
+    cacheStrategy: 'aggressive',
+    timeout: 10000
+  }
+};
 
-  return (
-    <div>
-      <h1>{data.username}</h1>
-      <p>{data.email}</p>
-    </div>
-  );
-}
+// Pattern 4: Custom fine-tuned
+const serviceOptions: ServiceOptions = {
+  apiConfig: {
+    timeout: 15000,
+    retry: { retries: 3, delay: 2000, backoff: 2 },
+    cacheStrategy: 'moderate',
+    headers: {
+      'X-Client-Version': '1.0.0',
+      'X-Request-Priority': 'high'
+    }
+  }
+};
 ```
 
-#### Mutation Hook Usage
+---
 
-```typescript
-import { useUpdateUserProfile } from '@plyaz/api/hooks';
+## 📖 Usage Examples
 
-export function ProfileEditForm({ userId }: { userId: string }) {
-  const { mutate, isLoading } = useUpdateUserProfile();
+### React Hooks
 
-  const handleSubmit = (formData: UpdateUserRequest) => {
-    mutate(
-      { 
-        pathParams: { userId }, 
-        body: formData 
-      },
-      {
-        onSuccess: (data) => {
-          console.log('Profile updated:', data);
-        },
-        onError: (error) => {
-          console.error('Update failed:', error);
-        }
-      }
-    );
-  };
+#### Data Fetching with Services
 
-  return (
-    <form onSubmit={handleSubmit}>
-      {/* Form fields */}
-      <button type="submit" disabled={isLoading}>
-        {isLoading ? 'Updating...' : 'Update Profile'}
-      </button>
-    </form>
+```typescript
+import {
+  useCampaigns,
+  useCampaign,
+  useCreateCampaign,
+  useJoinCampaign,
+} from '@plyaz/api/services/campaigns';
+import { useQueryClient } from '@tanstack/react-query';
+import type { ServiceOptions } from '@plyaz/api/services';
+
+function CampaignList() {
+  const queryClient = useQueryClient();
+
+  // Basic query with smart defaults
+  const { data, isLoading, error } = useCampaigns(
+    ['campaigns', 'active'],
+    { status: 'active' }
   );
-}
-```
 
-#### Infinite Query for Pagination
+  // Query with custom configuration
+  const { data: searchResults } = useCampaigns(
+    ['campaigns', 'search', searchTerm],
+    { search: searchTerm },
+    // ServiceOptions - API client config
+    {
+      apiConfig: {
+        timeout: 5000,
+        retry: { retries: 2 },
+      }
+    },
+    // UseQueryOptions - React Query config
+    {
+      enabled: searchTerm.length > 2,
+      staleTime: 30000,
+      refetchOnWindowFocus: false,
+    }
+  );
 
-```typescript
-import { useInfiniteTransactions } from '@plyaz/api/hooks';
-
-export function TransactionList({ walletAddress, chainId }: Props) {
-  const {
-    data,
-    fetchNextPage,
-    hasNextPage,
-    isFetchingNextPage
-  } = useInfiniteTransactions(
-    { walletAddress, chainId },
-    { limit: 10 }
+  // Single item query with background caching
+  const { data: campaign } = useCampaign(
+    ['campaign', campaignId],
+    { id: campaignId }
+  );
+
+  // Mutation with comprehensive handlers
+  const { mutate: createCampaign, isPending } = useCreateCampaign(
+    // ServiceOptions for API config
+    {
+      apiConfig: {
+        timeout: 15000,
+        headers: { 'X-Campaign-Source': 'web-app' },
+      }
+    },
+    // Mutation options
+    {
+      onSuccess: (data) => {
+        queryClient.invalidateQueries({ queryKey: ['campaigns'] });
+        toast.success(`Campaign "${data.name}" created!`);
+      },
+      onError: (error) => {
+        toast.error(`Failed to create: ${error.message}`);
+      },
+      onMutate: (variables) => {
+        // Optimistic update
+        const previousCampaigns = queryClient.getQueryData(['campaigns']);
+        queryClient.setQueryData(['campaigns'], (old) => [...old, variables]);
+        return { previousCampaigns };
+      },
+    }
   );
 
+  // Multiple mutations with shared options
+  const { mutate: joinCampaign } = useJoinCampaign(undefined, {
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['campaigns', campaignId] });
+    }
+  });
+
+  if (isLoading) return <Spinner />;
+  if (error) return <ErrorMessage error={error} />;
+
   return (
     <div>
-      {data?.pages.flatMap(page => 
-        page.transactions.map(tx => (
-          <div key={tx.id}>{tx.hash}</div>
-        ))
-      )}
-      
-      {hasNextPage && (
-        <button onClick={() => fetchNextPage()}>
-          {isFetchingNextPage ? 'Loading...' : 'Load More'}
-        </button>
-      )}
+      <CampaignGrid
+        campaigns={data}
+        onCreate={createCampaign}
+        onJoin={joinCampaign}
+        isPending={isPending}
+      />
     </div>
   );
 }
 ```
 
-### Service Functions
+#### Hook Configuration Priority
 
 ```typescript
-import { getUserProfile, updateUserProfile } from '@plyaz/api/services';
-
-// Fetch user profile
-const profile = await getUserProfile(
-  { walletAddress: '0x123...' },
-  { includeDetails: true }
-);
-
-// Update user profile
-const updated = await updateUserProfile(
-  { userId: 'usr-123' },
-  { username: 'newusername', email: 'new@email.com' }
+// The priority chain (lowest to highest):
+// 1. Factory defaults (from createApiQuery/createApiMutation)
+// 2. Hook-level defaults (when hook was created)
+// 3. ServiceOptions parameter (API config)
+// 4. UseQueryOptions parameter (React Query config)
+
+// Example showing all levels:
+const { data } = useCampaigns(
+  ['campaigns'],
+  { status: 'active' },           // Query parameters
+  { apiConfig: { timeout: 10000 } }, // Level 3: Service options
+  { staleTime: 60000 }            // Level 4: React Query options (highest)
 );
 ```
 
-## API Methods
-
-### GET Requests
+#### Monitoring Hooks
 
 ```typescript
-// Path parameters
-const { data } = await api.getUserProfile({
-  urlPathParams: { walletAddress: '0x123...' }
-});
+import { useApiMonitor, useApiNetworkQuality } from '@plyaz/api';
 
-// Query parameters
-const { data } = await api.getUsers({
-  params: { page: 1, limit: 10 }
-});
+function Dashboard() {
+  const { stats, isHealthy } = useApiMonitor(api);
+  const { quality, isOnline } = useApiNetworkQuality();
 
-// Both path and query parameters
-const { data } = await api.getNFTs({
-  urlPathParams: { walletAddress: '0x123...', chainId: 'ethereum' },
-  params: { tokenType: 'ERC721' }
-});
+  return <DashboardUI stats={stats} quality={quality} />;
+}
 ```
 
-### POST Requests
+### Service Functions
 
-```typescript
-// Simple POST
-const { data } = await api.createUser({
-  body: { username: 'johndoe', email: 'john@example.com' }
-});
+Service functions provide smart defaults based on HTTP method (GET/POST/PUT/DELETE) and allow granular configuration overrides.
 
-// POST with path parameters
-const { data } = await api.transferNFT({
-  urlPathParams: { walletAddress: '0x456...' },
-  body: { nftId: '123', toAddress: '0x789...' }
-});
-```
-
-### PUT/PATCH Requests
+#### Basic Usage
 
 ```typescript
-// PUT request
-const { data } = await api.updateUserProfile({
-  urlPathParams: { userId: '123' },
-  body: { username: 'newusername' }
-});
-
-// PATCH request
-const { data } = await api.patchUserSettings({
-  urlPathParams: { userId: '123' },
-  body: { theme: 'dark' }
-});
-```
+import { fetchCampaigns, createCampaign } from '@plyaz/api/services/campaigns';
 
-### DELETE Requests
+// Simple fetch with smart defaults (interactive caching for lists)
+const response = await fetchCampaigns({ status: 'active' });
 
-```typescript
-// DELETE with path parameters
-const { data } = await api.deleteUser({
-  urlPathParams: { userId: '123' }
+// Create with realtime strategy (no cache for mutations)
+const created = await createCampaign({
+  name: 'Summer Campaign',
+  description: 'Q3 promotional campaign'
 });
 ```
 
-## Configuration
-
-### Full Configuration Options
+#### With ServiceOptions Configuration
 
 ```typescript
-{
-  // Base configuration
-  baseURL: process.env.NEXT_PUBLIC_API_URL,
-  timeout: 30000,
-  headers: {
-    'Content-Type': 'application/json'
-  },
-  
-  // Request management
-  withCredentials: true,
-  cancellable: true,
-  dedupeTime: 1000,
-  
-  // Retry configuration
-  retry: {
-    retries: 3,
-    delay: 1000,
-    backoff: 1.5,
-    maxDelay: 10000,
-    retryOn: [408, 429, 500, 502, 503, 504]
-  },
-  
-  // Error handling strategy
-  strategy: 'softFail', // 'reject' | 'softFail' | 'defaultResponse' | 'silent'
-  
-  // Caching
-  cache: {
-    cacheTime: 60,
-    skipCache: (response, config) => config.method !== 'GET'
-  },
-  
-  // Interceptors
-  onRequest: (config) => config,
-  onResponse: (response) => response,
-  onError: (error) => error
-}
-```
+import type { ServiceOptions } from '@plyaz/api/services';
+
+// Override API client configuration
+const serviceOptions: ServiceOptions = {
+  apiConfig: {
+    timeout: 15000,                    // Custom timeout
+    retry: { retries: 5, delay: 2000 }, // Aggressive retry
+    headers: { 'X-Custom': 'value' },   // Additional headers
+  }
+};
 
-## Advanced Features
+const campaigns = await fetchCampaigns(
+  { status: 'active', limit: 50 },
+  serviceOptions
+);
 
-### Request Cancellation
+// Use different strategies
+const realtimeData = await fetchCampaigns(
+  { status: 'active' },
+  {
+    apiConfig: {
+      unifiedStrategy: 'realtime',  // No cache, always fresh
+      revalidationStrategy: 'none',
+    }
+  }
+);
 
-```typescript
-// Enable automatic cancellation
-const { data } = await api.searchUsers({
-  params: { query: searchTerm },
-  cancellable: true,
-  rejectCancelled: true
-});
+// Mobile-optimized configuration
+const mobileData = await fetchCampaigns(
+  { status: 'active' },
+  {
+    apiConfig: {
+      unifiedStrategy: 'mobile',     // Mobile-friendly caching
+      networkAware: { enabled: true }, // Adapt to connection
+    }
+  }
+);
 ```
 
-### Request Deduplication
+#### Error Handling Patterns
 
 ```typescript
-// Deduplicate identical requests within time window
-const { data } = await api.getUserProfile({
-  urlPathParams: { walletAddress: '0x123...' },
-  dedupeTime: 5000 // 5 seconds
-});
-```
+import { isNotFoundError, isValidationError } from '@plyaz/errors';
 
-### Error Handling Strategies
+// Pattern 1: Check response.error
+const response = await fetchCampaigns({ status: 'active' });
+if (response.error) {
+  if (isNotFoundError(response.error)) {
+    console.log('No campaigns found');
+  }
+  return;
+}
+console.log('Campaigns:', response.data);
 
-```typescript
-// Reject strategy (throws errors)
+// Pattern 2: Try-catch with throw
 try {
-  const { data } = await api.getUserProfile({
-    urlPathParams: { walletAddress: '0x123...' },
-    strategy: 'reject'
-  });
-} catch (error) {
-  console.error(error);
+  const { data, error } = await createCampaign(newCampaign);
+  if (error) throw error;
+  console.log('Created:', data);
+} catch (err) {
+  if (isValidationError(err)) {
+    console.error('Invalid data:', err.message);
+  }
 }
+```
 
-// SoftFail strategy (returns error property)
-const { data, error } = await api.getUserProfile({
-  urlPathParams: { walletAddress: '0x123...' },
-  strategy: 'softFail'
-});
+#### Using Multiple Services
 
-if (error) {
-  console.error(error);
-} else {
-  console.log(data);
-}
+```typescript
+import {
+  fetchCampaign,
+  fetchCampaignStats,
+  fetchCampaignParticipants,
+} from '@plyaz/api/services/campaigns';
+
+// Fetch related data with consistent configuration
+const serviceOpts: ServiceOptions = {
+  apiConfig: { timeout: 10000 }
+};
 
-// Silent strategy (fire-and-forget)
-api.trackUserActivity({
-  body: { action: 'page_view' },
-  strategy: 'silent'
-});
+const [campaign, stats, participants] = await Promise.all([
+  fetchCampaign({ id: '123' }, serviceOpts),
+  fetchCampaignStats({ id: '123' }, serviceOpts),
+  fetchCampaignParticipants({ id: '123' }, serviceOpts),
+]);
 ```
 
 ### Custom Interceptors
 
 ```typescript
-const apiWithAuth = createApiClient({
-  onRequest: [
-    // Add authentication
-    (config) => {
-      const token = getAuthToken();
-      if (token) {
-        config.headers.Authorization = `Bearer ${token}`;
-      }
-      return config;
-    },
-    // Add tenant ID
-    (config) => {
-      config.headers['X-Tenant-ID'] = getTenantId();
-      return config;
-    }
-  ],
-  
+const api = await createApiClient({
+  onRequest: (config) => {
+    config.headers['X-Request-ID'] = generateRequestId();
+    return config;
+  },
+
+  onResponse: (response) => {
+    console.log(`Request completed in ${response.duration}ms`);
+    return response;
+  },
+
   onError: (error) => {
     if (error.status === 401) {
-      router.push('/login');
+      redirectToLogin();
     }
     return error;
   }
 });
 ```
 
-## Error Handling
-
-### With @plyaz/errors Integration
+### Error Handling
 
 ```typescript
 import { isNotFoundError, isValidationError } from '@plyaz/errors';
-import { handleApiError } from '@plyaz/api/utils';
 
-const fetchUser = async (walletAddress: string) => {
-  const { data, error } = await api.getUserProfile({
-    urlPathParams: { walletAddress },
-    strategy: 'softFail'
-  });
-  
-  if (error) {
-    if (isNotFoundError(error)) {
-      console.log('User not found');
-    } else if (isValidationError(error)) {
-      console.log('Invalid parameters');
-    } else {
-      const handled = handleApiError(error);
-      console.error(handled.message);
-    }
-    return null;
-  }
-  
-  return data;
-};
-```
-
-## Pagination Utilities
+const { data, error } = await api.getUser({ id: '123' });
 
-```typescript
-import { 
-  getCursorPaginationParams,
-  getOffsetPaginationParams,
-  getPaginationInfo 
-} from '@plyaz/api/utils';
-
-// Cursor-based pagination
-const cursorParams = getCursorPaginationParams('next_cursor_123', 10);
-
-// Offset-based pagination
-const offsetParams = getOffsetPaginationParams(2, 10); // Page 2, 10 items
-
-// Extract pagination info
-const { data } = await api.getUsers({ params: offsetParams });
-const info = getPaginationInfo(data);
-console.log(`Page ${info.currentPage} of ${info.totalPages}`);
+if (error) {
+  if (isNotFoundError(error)) {
+    console.log('User not found');
+  } else if (isValidationError(error)) {
+    console.log('Invalid parameters');
+  }
+}
 ```
 
-## Third-Party Integrations
+---
 
-### Alchemy API Integration
+## 🏗️ Architecture
 
-```typescript
-import { AlchemyService } from '@plyaz/api/integrations/alchemy';
-
-const alchemy = new AlchemyService({
-  apiKey: process.env.ALCHEMY_API_KEY,
-  network: 'eth-mainnet'
-});
+The @plyaz/api package orchestrates 21 internal modules to provide a seamless API experience:
 
-// Get NFTs for wallet
-const nfts = await alchemy.getNFTs({
-  owner: '0x123...',
-  withMetadata: true
-});
-
-// Get token balances
-const balances = await alchemy.getTokenBalances({
-  address: '0x123...'
-});
+```
+Your App → createApiClient() → Smart Features → fetchff → Your API
+              ↓
+         [Automatic]
+         • Retry Logic
+         • Caching
+         • Deduplication
+         • Network Adaptation
+         • Event System
+         • Performance Tracking
 ```
 
-## Platform Architecture Context
-
-The API client is a critical component of the Plyaz platform's shared package ecosystem:
-
-### Frontend Architecture
-- **Multiple Apps**: Supports web app, admin panel, and micro apps
-- **React Query**: Deep integration for efficient data fetching
-- **State Management**: Works with Zustand stores for state synchronization
-- **Next.js**: Optimized for server-side rendering and API routes
+**Want to understand how it works?** See the [Architecture Overview](./docs/USAGE.md#architecture-overview) and [Internal Architecture](./docs/INTERNAL.md).
 
-### Backend Architecture
-- **Microservices**: Communicates with distributed NestJS services
-- **API Gateway**: Routes through centralized gateway with auth
-- **Event-Driven**: Supports async communication patterns
-- **GraphQL/REST**: Flexible endpoint configuration
+---
 
-## Integration with Other Plyaz Packages
+## 📚 Documentation
 
-| Package | Integration | Purpose |
-|---------|------------|---------|
-| **@plyaz/types** | Type definitions | Provides API interfaces and types |
-| **@plyaz/errors** | Error handling | Standardized error types and handlers |
-| **@plyaz/config** | Configuration | API URLs and environment settings |
-| **@plyaz/auth** | Authentication | Token management and auth headers |
-| **@plyaz/events** | Event bus | API lifecycle events |
-| **@plyaz/logger** | Logging | Request/response logging |
-| **@plyaz/web3** | Blockchain | Web3 transaction APIs |
-| **@plyaz/monitoring** | Metrics | API performance tracking |
+- **[Usage Guide](./docs/USAGE.md)** - Complete usage documentation with examples
+- **[API Reference](./docs/API-REFERENCE.md)** - Detailed API reference
+- **[Internal Architecture](./docs/INTERNAL.md)** - Deep dive into internal systems
+- **[Confluence Docs](https://plyaz.atlassian.net/wiki/spaces/SD/pages/950316/API+Package)** - Official documentation
 
-## Type Safety
+---
 
-### Endpoint Type Definitions
+## 🛠️ Development
 
-```typescript
-// Types are imported from @plyaz/types
-import type { 
-  UserMethods, 
-  TransactionMethods,
-  NFTMethods 
-} from '@plyaz/types/api';
-
-// Combined interface for all endpoints
-export interface EndpointsMethods extends 
-  UserMethods,
-  TransactionMethods,
-  NFTMethods {}
-```
+### Setup
 
-### Request/Response Types
+```bash
+# Install dependencies
+pnpm install
 
-```typescript
-import type { 
-  ApiResponse,
-  PaginatedResponse,
-  ApiError 
-} from '@plyaz/types/api';
-
-// Type-safe responses
-type UserResponse = ApiResponse<User>;
-type UsersListResponse = PaginatedResponse<User>;
+# Start development mode
+pnpm dev
 ```
 
-## Best Practices
+### Common Commands
 
-### Service Layer Pattern
-
-```typescript
-// services/user.ts
-export async function getUserProfile(
-  urlPathParams: GetUserProfilePathParams,
-  queryParams?: GetUserProfileQueryParams
-): Promise<UserProfile> {
-  return api.getUserProfile({
-    urlPathParams,
-    params: queryParams
-  });
-}
+```bash
+pnpm dev              # Watch mode development
+pnpm build            # Build the package
+pnpm test             # Run tests
+pnpm test:watch       # Watch mode testing
+pnpm test:coverage    # Coverage report
+pnpm lint             # Lint code
+pnpm type:check       # Type checking
 ```
 
-### Query Key Management
+---
 
-```typescript
-// hooks/user/keys.ts
-export const userKeys = {
-  all: ['user'] as const,
-  lists: () => [...userKeys.all, 'list'] as const,
-  list: (params: any) => [...userKeys.lists(), params] as const,
-  profile: (id: string) => [...userKeys.all, 'profile', id] as const
-};
-```
+## 🔗 Integration with Plyaz Packages
 
-### Error Boundary Integration
+| Package | Purpose | Usage |
+|---------|---------|-------|
+| **@plyaz/types** | Type definitions | API interfaces and types |
+| **@plyaz/errors** | Error handling | Standardized error types |
+| **@plyaz/config** | Configuration | API URLs and constants |
 
-```typescript
-import { ErrorBoundary } from '@plyaz/ui';
-import { handleApiError } from '@plyaz/api/utils';
+---
 
-function MyApp() {
-  return (
-    <ErrorBoundary
-      fallback={<ErrorFallback />}
-      onError={(error) => {
-        const handled = handleApiError(error);
-        logError(handled);
-      }}
-    >
-      <App />
-    </ErrorBoundary>
-  );
-}
-```
+## 🎓 Learning Path
 
-## Migration Guide
+1. **Beginner**: Start with [Quick Start](#-quick-start) → Try the examples
+2. **Intermediate**: Read [Usage Guide](./docs/USAGE.md) → Learn patterns
+3. **Advanced**: Explore [API Reference](./docs/API-REFERENCE.md) → Master configuration
+4. **Expert**: Study [Internal Architecture](./docs/INTERNAL.md) → Understand internals
 
-### From Axios
+---
 
-```typescript
-// Before (Axios)
-const response = await axios.get('/api/users/123');
-const user = response.data;
+## 🤝 Contributing
 
-// After (@plyaz/api)
-const { data: user } = await api.getUserProfile({
-  urlPathParams: { userId: '123' }
-});
-```
+This package is part of the Plyaz platform. Please follow the [contribution guidelines](https://plyaz.atlassian.net/wiki/spaces/SD/pages/22544393) in the main repository.
 
-### From Fetch
+---
 
-```typescript
-// Before (Fetch)
-const response = await fetch('/api/users', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify(userData)
-});
-const user = await response.json();
+## 📄 License
 
-// After (@plyaz/api)
-const { data: user } = await api.createUser({
-  body: userData
-});
-```
-
-## Contributing
+ISC © Plyaz
 
-This package is part of the Plyaz platform. Please follow the contribution guidelines in the main repository.
+---
 
-## Resources
+## 🔗 Links
 
-- [Plyaz Confluence Documentation](https://plyaz.atlassian.net/wiki/spaces/SD/pages/950316/API+Package)
+- [Plyaz Platform Documentation](https://plyaz.atlassian.net/wiki/spaces/SD)
 - [fetchff Documentation](https://www.npmjs.com/package/fetchff)
 - [React Query Documentation](https://tanstack.com/query)
-
-## License
-
-ISC © Plyaz
+- [TypeScript Documentation](https://www.typescriptlang.org/)