@plyaz/api

⚡ Smart, type-safe API client for the Plyaz ecosystem with zero-configuration intelligence

@plyaz/api is the unified API client for seamless backend communication across the Plyaz platform. Built on fetchff, it provides intelligent defaults, automatic optimizations, and full TypeScript support for Web3, authentication, and tokenized experiences.

✨ Why @plyaz/api?

Zero-Configuration Smart Features

The API client works intelligently out of the box:

| 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:

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' });

📦 Installation

pnpm add @plyaz/api

Requirements:

• Node.js >= 22.4.0
• pnpm >= 8.0.0

🚀 Quick Start

Simple REST API (2 lines)

const api = await createApiClient({ baseURL: 'https://api.example.com' });
const { data } = await api.getUsers();

Authenticated API

const api = await createApiClient({
  baseURL: 'https://api.example.com',
  headers: async () => ({
    Authorization: `Bearer ${await getToken()}`
  })
});

Mobile App (Network-aware)

const api = await createApiClient({
  baseURL: 'https://api.example.com',
  performanceStrategy: 'mobile',
  networkAware: { enabled: true }
});

Real-Time Dashboard

const api = await createApiClient({
  baseURL: 'https://api.example.com',
  unifiedStrategy: 'realtime',
  revalidationStrategy: 'aggressive'
});

🎯 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

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;
}

/**
 * Config update options
 */
interface UpdateConfigOptions {
    strategy?: ConfigUpdateStrategy;
    priority?: number;
    namespace?: string;
    scope?: string;
    preserveFields?: (keyof ApiConfig)[];
}

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 | - |

Common Configuration Patterns

// Pattern 1: Mobile-optimized
const serviceOptions: ServiceOptions = {
  apiConfig: {
    unifiedStrategy: 'mobile',
    networkAware: { enabled: true, adaptConfig: true },
    retry: { retries: 5, backoff: 2 }
  }
};

// Pattern 2: Real-time dashboard
const serviceOptions: ServiceOptions = {
  apiConfig: {
    unifiedStrategy: 'realtime',
    revalidationStrategy: 'aggressive',
    cacheStrategy: 'none'
  }
};

// Pattern 3: Static content
const serviceOptions: ServiceOptions = {
  apiConfig: {
    unifiedStrategy: 'static',
    cacheStrategy: 'aggressive',
    timeout: 10000
  }
};

// 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'
    }
  }
};

📖 Usage Examples

React Hooks

Data Fetching with Services

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' }
  );

  // 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,
    }
  );

  // 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>
      <CampaignGrid
        campaigns={data}
        onCreate={createCampaign}
        onJoin={joinCampaign}
        isPending={isPending}
      />
    </div>
  );
}

Hook Configuration Priority

// 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)
);

Monitoring Hooks

import { useApiMonitor, useApiNetworkQuality } from '@plyaz/api';

function Dashboard() {
  const { stats, isHealthy } = useApiMonitor(api);
  const { quality, isOnline } = useApiNetworkQuality();

  return <DashboardUI stats={stats} quality={quality} />;
}

Service Functions

Service functions provide smart defaults based on HTTP method (GET/POST/PUT/DELETE) and allow granular configuration overrides.

Basic Usage

import { fetchCampaigns, createCampaign } from '@plyaz/api/services/campaigns';

// Simple fetch with smart defaults (interactive caching for lists)
const response = await fetchCampaigns({ status: 'active' });

// Create with realtime strategy (no cache for mutations)
const created = await createCampaign({
  name: 'Summer Campaign',
  description: 'Q3 promotional campaign'
});

With ServiceOptions Configuration

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
  }
};

const campaigns = await fetchCampaigns(
  { status: 'active', limit: 50 },
  serviceOptions
);

// Use different strategies
const realtimeData = await fetchCampaigns(
  { status: 'active' },
  {
    apiConfig: {
      unifiedStrategy: 'realtime',  // No cache, always fresh
      revalidationStrategy: 'none',
    }
  }
);

// Mobile-optimized configuration
const mobileData = await fetchCampaigns(
  { status: 'active' },
  {
    apiConfig: {
      unifiedStrategy: 'mobile',     // Mobile-friendly caching
      networkAware: { enabled: true }, // Adapt to connection
    }
  }
);

Error Handling Patterns

import { isNotFoundError, isValidationError } from '@plyaz/errors';

// 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);

// Pattern 2: Try-catch with throw
try {
  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);
  }
}

Using Multiple Services

import {
  fetchCampaign,
  fetchCampaignStats,
  fetchCampaignParticipants,
} from '@plyaz/api/services/campaigns';

// Fetch related data with consistent configuration
const serviceOpts: ServiceOptions = {
  apiConfig: { timeout: 10000 }
};

const [campaign, stats, participants] = await Promise.all([
  fetchCampaign({ id: '123' }, serviceOpts),
  fetchCampaignStats({ id: '123' }, serviceOpts),
  fetchCampaignParticipants({ id: '123' }, serviceOpts),
]);

Custom Interceptors

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) {
      redirectToLogin();
    }
    return error;
  }
});

Error Handling

import { isNotFoundError, isValidationError } from '@plyaz/errors';

const { data, error } = await api.getUser({ id: '123' });

if (error) {
  if (isNotFoundError(error)) {
    console.log('User not found');
  } else if (isValidationError(error)) {
    console.log('Invalid parameters');
  }
}

🏗️ Architecture

The @plyaz/api package orchestrates 21 internal modules to provide a seamless API experience:

Your App → createApiClient() → Smart Features → fetchff → Your API
              ↓
         [Automatic]
         • Retry Logic
         • Caching
         • Deduplication
         • Network Adaptation
         • Event System
         • Performance Tracking

Want to understand how it works? See the Architecture Overview and Internal Architecture.

📚 Documentation

• Usage Guide - Complete usage documentation with examples
• API Reference - Detailed API reference
• Internal Architecture - Deep dive into internal systems
• Confluence Docs - Official documentation

🛠️ Development

Setup

# Install dependencies
pnpm install

# Start development mode
pnpm dev

Common Commands

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

🔗 Integration with Plyaz Packages

| 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 |

🎓 Learning Path

1. Beginner: Start with Quick Start → Try the examples
2. Intermediate: Read Usage Guide → Learn patterns
3. Advanced: Explore API Reference → Master configuration
4. Expert: Study Internal Architecture → Understand internals

🤝 Contributing

This package is part of the Plyaz platform. Please follow the contribution guidelines in the main repository.

📄 License

ISC © Plyaz

🔗 Links

• Plyaz Platform Documentation
• fetchff Documentation
• React Query Documentation
• TypeScript Documentation