feat(js-api-client): modernize, harden, and test the API client

[Plopix]

Summary

A comprehensive update to js-api-client covering bug fixes, new features, refactoring, tests, and documentation.

What changed

• Bug fixes: typo in GraphQL query (chidlren), dead code removal, Promise antipattern, empty auth headers, Server-Timing parsing, correct package.json module field
• Features: request timeout via AbortController, Symbol.dispose for automatic cleanup, http2IdleTimeout option, statusCode getter on errors, auth warning when no credentials configured
• Refactoring: proper TypeScript types replacing any, descriptive generic names, extracted shared helpers in cart/subscription managers, cleaner mass-call client
• Tests: comprehensive unit tests for API caller, grabber, mass-call client, and error handling
• Docs: JSDoc on all main exports, updated README with new options
• CI: GitHub Actions workflow for PR and main branch checks
• Deprecation: mass-call client deprecated in favor of p-limit/p-queue

Architecture Overview

graph TD
    A[createClient] --> B[createGrabber]
    A --> C[createApiCaller]
    B --> D{useHttp2?}
    D -->|yes| E[HTTP/2 Session Pool]
    D -->|no| F[Standard fetch]
    E -->|new: http2IdleTimeout| E
    C -->|new: timeout via AbortController| G[Request Execution]
    C --> H[Profiling / Server-Timing]
    
    A --> I[catalogueApi]
    A --> J[searchApi]
    A --> K[pimApi]
    A --> L[shopCartApi]

    I --> M[Catalogue Fetcher]
    I --> N[Navigation Fetcher]
    I --> O[Product Hydrater]

    K --> P[Order Manager]
    K --> Q[Customer Manager]
    K --> R[Subscription Contract Manager]

    L --> S[Cart Manager]

    style A fill:#4a9eff,color:#fff
    style B fill:#6c5ce7,color:#fff
    style C fill:#6c5ce7,color:#fff
    style G fill:#00b894,color:#fff

Loading

Changes Breakdown

pie title Changes by Category
    "Bug Fixes" : 8
    "Features" : 5
    "Refactoring" : 5
    "Tests" : 4
    "Docs & CI" : 4
    "Deprecation" : 1

Loading

Request Lifecycle (updated)

sequenceDiagram
    participant App
    participant Client
    participant ApiCaller
    participant Grabber
    participant API as Crystallize API

    App->>Client: createClient(config, options)
    Client->>Grabber: createGrabber({ useHttp2, http2IdleTimeout })
    Client->>ApiCaller: createApiCaller(uri, grabber, options)
    
    App->>ApiCaller: query(gql, variables)
    
    alt timeout configured
        ApiCaller->>ApiCaller: Create AbortController + setTimeout
    end
    
    alt no credentials configured
        ApiCaller-->>App: ⚠️ console.warn (new)
    end
    
    ApiCaller->>Grabber: grab(uri, body, headers, signal?)
    Grabber->>API: HTTP/1.1 or HTTP/2 request
    API-->>Grabber: Response
    Grabber-->>ApiCaller: parsed JSON
    
    alt error
        ApiCaller-->>App: JSApiClientCallError (now with .statusCode)
    end
    
    ApiCaller-->>App: data
    
    App->>Client: close() or Symbol.dispose (new)
    Client->>Grabber: close HTTP/2 sessions

Loading

Test plan

• Unit tests added for create-api-caller, create-grabber, create-mass-call-client, and error handling
• Verify existing consumers are not broken by type changes (extraHeaders narrowed to Record<string, string>)
• Verify Symbol.dispose works with TypeScript using declarations
• Test http2IdleTimeout with long-lived HTTP/2 connections
• Confirm deprecation warning appears for mass-call client usage