@igniter-js/caller 0.1.4 → 0.1.51

package/AGENTS.md

@@ -44,7 +44,7 @@ The package follows these core principles:
 
 `@igniter-js/caller` is a standalone library that can be used independently or alongside other Igniter.js packages. It integrates with:
 
-- **`@igniter-js/core`:** Uses `IgniterError` base class, `IgniterLogger` interface, and `StandardSchemaV1` type.
+- **`@igniter-js/common`:** Uses `IgniterError` base class, `IgniterLogger` interface, and `StandardSchemaV1` type.
 
 - **`@igniter-js/telemetry`:** Emits structured telemetry events for request lifecycle monitoring.
 
@@ -54,6 +54,11 @@ The package follows these core principles:
 
 Unlike most Igniter.js packages, `@igniter-js/caller` is **explicitly designed to work in both server and client environments**. It does NOT have a server-only shim because HTTP clients are a valid use case for browser applications.
 
+Additional constraints for client usage:
+
+- The React layer is exported from `@igniter-js/caller/client` to avoid bundling React into non-React consumers.
+- If a caller instance is configured with server-only store adapters or telemetry managers, do not bundle that instance in browser code. Create a browser-safe instance instead.
+
 ---
 
 ## I. MAINTAINER GUIDE (Internal Architecture)
@@ -73,6 +78,15 @@ packages/caller/src/
 │   ├── schema.builder.ts       # IgniterCallerSchema (schema registry builder)
 │   ├── schema.builder.spec.ts  # Schema builder tests
 │   └── schema-path.builder.ts # IgniterCallerSchemaPathBuilder (path+methods)
+├── client/                    # React client layer (Provider + hooks)
+│   ├── index.ts               # React client entrypoint barrel
+│   ├── builders/              # Provider + hook factories
+│   ├── interfaces/            # Client-specific types
+│   └── utils/                 # Client-only helpers (cache, keys, cookies)
+├── mock/                      # Typed mock registry for schemas
+│   ├── index.ts               # Mock exports barrel
+│   ├── main.builder.ts        # IgniterCallerMockBuilder
+│   └── manager.ts             # IgniterCallerMockManager
 ├── core/                      # Runtime execution layer
 │   ├── index.ts               # Core exports barrel
 │   ├── manager.ts             # IgniterCallerManager (HTTP client runtime)
@@ -122,7 +136,18 @@ packages/caller/src/
 | `schema.builder.ts`      | `IgniterCallerSchema` class - schema registry builder with `$Infer` type helpers and `get` runtime helpers. Prevents duplicate keys and paths.                                             |
 | `schema-path.builder.ts` | `IgniterCallerSchemaPathBuilder` class - path-first fluent API for defining HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD) on a path. Provides `ref()` helper for registry references. |
 
-#### 2.2 Core Directory (`src/core/`)
+#### 2.2 Client Directory (`src/client/`)
+
+**Purpose:** React-specific layer that provides Provider + hooks for multiple callers.
+
+| Folder/File          | Responsibility                                                                                          |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| `builders/`          | `IgniterCallerProvider`, `useIgniterCaller`, and hook factories for `useQuery`/`useMutate`.            |
+| `interfaces/`        | Client-only types for config, hooks, context, and the wrapper client API.                              |
+| `utils/`             | Client-only helpers (query keys, in-memory cache, cookie header merge).                                |
+| `index.ts`           | Client entrypoint barrel used by `@igniter-js/caller/client`.                                          |
+
+#### 2.3 Core Directory (`src/core/`)
 
 **Purpose:** Runtime execution and event handling.
 
@@ -131,7 +156,7 @@ packages/caller/src/
 | `manager.ts` | `IgniterCallerManager` class - the main HTTP client runtime. Creates request builders, executes direct requests, manages global event emission, and provides static methods for cache invalidation and batch requests. |
 | `events.ts`  | `IgniterCallerEvents` class - global event emitter supporting exact URL matches and RegExp patterns. Handles listener registration, cleanup, and error-safe emission.                                                  |
 
-#### 2.3 Types Directory (`src/types/`)
+#### 2.4 Types Directory (`src/types/`)
 
 **Purpose:** Pure TypeScript contracts—no implementation code.
 
@@ -150,7 +175,7 @@ packages/caller/src/
 | `schemas.ts`        | Core schema types: `IgniterCallerSchemaMethod`, `IgniterCallerEndpointSchema`, `IgniterCallerSchemaMap`, path extraction types (`ExtractPathParams`), inference types (`InferRequestType`, `InferResponseType`, `InferSuccessResponseType`, `InferAllResponseTypes`), path filtering types (`GetPaths`, `PostPaths`, etc.), endpoint info types, validation options. |
 | `store.ts`          | `IgniterCallerStoreAdapter<TClient>`, `IgniterCallerStoreOptions`.                                                                                                                                                                                                                                                                                                   |
 
-#### 2.4 Utils Directory (`src/utils/`)
+#### 2.5 Utils Directory (`src/utils/`)
 
 **Purpose:** Pure functions for specific operations.
 
@@ -672,7 +697,7 @@ This section provides step-by-step flow documentation for every public method.
 
 | Package                 | Purpose                                             | Peer Dependency                          |
 | ----------------------- | --------------------------------------------------- | ---------------------------------------- |
-| `@igniter-js/core`      | `IgniterError`, `IgniterLogger`, `StandardSchemaV1` | ✅ Required                              |
+| `@igniter-js/common`    | `IgniterError`, `IgniterLogger`, `StandardSchemaV1` | ✅ Required                              |
 | `@igniter-js/telemetry` | `IgniterTelemetryManager`, `IgniterTelemetryEvents` | ⚙️ Optional                              |
 | `zod`                   | Schema validation (v4+)                             | ⚙️ Optional (any StandardSchemaV1 works) |
 
@@ -907,6 +932,10 @@ The package is distributed as a standard npm package with multiple entry points.
 │   ├── index.js              # CommonJS main entry
 │   ├── index.mjs            # ESM main entry
 │   ├── index.d.ts           # TypeScript definitions
+│   ├── client/
+│   │   ├── index.js         # React client entry (CJS)
+│   │   ├── index.mjs        # React client entry (ESM)
+│   │   └── index.d.ts       # React client types
 │   ├── telemetry/
 │   │   ├── index.js         # Telemetry definitions (CJS)
 │   │   ├── index.mjs       # Telemetry definitions (ESM)
@@ -930,6 +959,12 @@ import { IgniterCallerTelemetryEvents } from "@igniter-js/caller/telemetry";
 // Mock adapter - for testing
 import { MockCallerStoreAdapter } from "@igniter-js/caller/adapters";
 
+// React client - Provider + hooks
+import { IgniterCallerProvider, useIgniterCaller } from "@igniter-js/caller/client";
+
+// Typed mock registry
+import { IgniterCallerMock } from "@igniter-js/caller";
+
 // Types - for extending or advanced usage
 import type {
   IgniterCallerApiResponse,
@@ -1008,6 +1043,78 @@ const result = await api
   .execute();
 ```
 
+#### 9.6 React Client (Provider + Hooks)
+
+```tsx
+import { IgniterCallerProvider, useIgniterCaller } from "@igniter-js/caller/client";
+
+export function CallerProvider() {
+  return (
+    <IgniterCallerProvider callers={{ github: githubApi }}>
+      <App />
+    </IgniterCallerProvider>
+  );
+}
+
+export const useCaller = useIgniterCaller<{
+  github: typeof githubApi;
+}>();
+
+function Profile() {
+  const github = useCaller("github");
+  const { data, isLoading, error, refetch, invalidate } = github
+    .get("/me")
+    .useQuery({ staleTime: 5000 });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error</div>;
+  return <pre>{JSON.stringify(data, null, 2)}</pre>;
+}
+```
+
+Notes:
+
+- `@igniter-js/caller/client` is the only entrypoint that depends on React.
+- Global defaults can be set via `github.config.set(...)`.
+- Invalidation supports an optional data payload for optimistic updates.
+
+#### 9.7 Typed Mocks (IgniterCallerMock)
+
+```typescript
+import { IgniterCaller, IgniterCallerMock } from "@igniter-js/caller";
+
+const schemas = {
+  "/users/:id": {
+    GET: {
+      responses: {
+        200: UserSchema,
+      },
+    },
+  },
+};
+
+const mock = IgniterCallerMock.create()
+  .withSchemas(schemas)
+  .mock("/users/:id", {
+    GET: (request) => ({
+      response: { id: request.params.id },
+      status: 200,
+      delayMs: 150,
+    }),
+  })
+  .build();
+
+const api = IgniterCaller.create()
+  .withSchemas(schemas)
+  .withMock({ enabled: true, mock })
+  .build();
+```
+
+Notes:
+
+- Mock handlers receive the full request context (method, url, headers, query, params, body).
+- When mock is enabled and no handler is registered, the request falls back to the real transport.
+
 ---
 
 ### 10. Real-World Use Case Library

package/README.md

@@ -23,16 +23,16 @@ Type-safe HTTP client for Igniter.js apps. Built on top of `fetch`, it gives you
 
 ```bash
 # npm
-npm install @igniter-js/caller @igniter-js/core
+npm install @igniter-js/caller @igniter-js/common
 
 # pnpm
-pnpm add @igniter-js/caller @igniter-js/core
+pnpm add @igniter-js/caller @igniter-js/common
 
 # yarn
-yarn add @igniter-js/caller @igniter-js/core
+yarn add @igniter-js/caller @igniter-js/common
 
 # bun
-bun add @igniter-js/caller @igniter-js/core
+bun add @igniter-js/caller @igniter-js/common
 ```
 
 Optional dependencies:
@@ -45,7 +45,7 @@ npm install @igniter-js/telemetry
 npm install zod
 ```
 
-> `@igniter-js/core` is required. `@igniter-js/telemetry` and `zod` are optional peer dependencies.
+> `@igniter-js/common` is required. `@igniter-js/telemetry` and `zod` are optional peer dependencies.
 
 ## Quick Start
 
@@ -73,6 +73,124 @@ if (result.error) {
 console.log(result.data)
 ```
 
+## React Client (Provider + Hooks)
+
+The React client is exposed via the dedicated subpath export:
+
+```ts
+import { IgniterCallerProvider, useIgniterCaller } from '@igniter-js/caller/client'
+```
+
+This keeps the root entrypoint server-safe and avoids bundling React in non-React environments.
+
+### Basic usage
+
+```tsx
+import { IgniterCallerProvider, useIgniterCaller } from '@igniter-js/caller/client'
+
+export function CallerProvider() {
+  return (
+    <IgniterCallerProvider callers={{ github: githubApi }}>
+      <UserProfile />
+    </IgniterCallerProvider>
+  )
+}
+
+export const useCaller = useIgniterCaller<{
+  github: typeof githubApi
+}>()
+
+function UserProfile() {
+  const github = useCaller('github')
+  const { data, isLoading, error, refetch, invalidate } = github
+    .get('/me')
+    .useQuery({
+      params: {},
+      query: {},
+      headers: {},
+      cookies: {},
+      staleTime: 5000,
+      enabled: true,
+    })
+
+  if (isLoading) return <div>Loading...</div>
+  if (error) return <div>Error</div>
+  return <pre>{JSON.stringify(data, null, 2)}</pre>
+}
+```
+
+### Global config and invalidation
+
+```tsx
+const github = useCaller('github')
+
+// Global defaults
+github.config.set('headers', { Authorization: 'Bearer ...' })
+github.config.set('cookies', { session: '...' })
+github.config.set('query', { locale: 'en' })
+
+// Typed invalidation with optional optimistic data
+github.invalidate('/me', { id: 'user_123' })
+```
+
+### Client safety notes
+
+- If your Caller instance uses store adapters or telemetry managers that are server-only,
+  do not bundle that instance into browser code. Create a browser-safe instance instead.
+- The React client does not automatically wire store/telemetry to avoid bundler contamination.
+
+## Mocking (IgniterCallerMock)
+
+Use `IgniterCallerMock` to create a type-safe mock registry based on your schemas.
+
+```ts
+import { IgniterCaller, IgniterCallerMock } from '@igniter-js/caller'
+
+const schemas = {
+  '/users/:id': {
+    GET: {
+      responses: {
+        200: UserSchema,
+      },
+    },
+  },
+}
+
+const mock = IgniterCallerMock.create()
+  .withSchemas(schemas)
+  .mock('/users/:id', {
+    GET: {
+      response: { id: 'user_1' },
+    },
+  })
+  .build()
+
+const api = IgniterCaller.create()
+  .withSchemas(schemas)
+  .withMock({ enabled: true, mock })
+  .build()
+```
+
+Mock handlers receive the full request context:
+
+```ts
+const mock = IgniterCallerMock.create()
+  .withSchemas(schemas)
+  .mock('/users/:id', {
+    GET: (request) => ({
+      response: { id: request.params.id },
+      status: 200,
+      delayMs: 150,
+    }),
+  })
+  .build()
+```
+
+Notes:
+
+- If mock is enabled but there is no handler for a request, it falls back to the real request.
+- Mock responses can include `status`, `headers`, and optional `delayMs`.
+
 ## HTTP Methods
 
 All HTTP methods accept an optional URL directly:

package/dist/adapters/index.d.mts

@@ -1 +1,70 @@
-export { M as MockCallerStoreAdapter } from '../index-COZVROi_.mjs';
+import { I as IgniterCallerStoreAdapter, a as IgniterCallerStoreOptions } from '../store-D2p2dqGN.mjs';
+
+/**
+ * @fileoverview In-memory mock store adapter for @igniter-js/caller.
+ * @module @igniter-js/caller/adapters/mock
+ */
+
+/**
+ * In-memory mock adapter for request caching in tests.
+ */
+declare class MockCallerStoreAdapter implements IgniterCallerStoreAdapter<Map<string, unknown>> {
+    /** Creates a new mock adapter instance. */
+    static create(): MockCallerStoreAdapter;
+    /** Underlying in-memory store. */
+    readonly client: Map<string, unknown>;
+    /** Tracks all calls for assertions. */
+    readonly calls: {
+        get: number;
+        set: number;
+        delete: number;
+        has: number;
+    };
+    /** Captures recent operations. */
+    readonly history: {
+        get: string[];
+        set: Array<{
+            key: string;
+            value: unknown;
+            options?: IgniterCallerStoreOptions;
+        }>;
+        delete: string[];
+        has: string[];
+    };
+    /**
+     * Retrieves a cached value by key.
+     *
+     * @param key - Cache key (without prefix).
+     * @returns Cached value or null.
+     */
+    get<T = any>(key: string): Promise<T | null>;
+    /**
+     * Stores a cached value.
+     *
+     * @param key - Cache key (without prefix).
+     * @param value - Value to store.
+     * @param options - Cache options (ttl, etc).
+     */
+    set(key: string, value: any, options?: IgniterCallerStoreOptions): Promise<void>;
+    /**
+     * Removes a cached value.
+     *
+     * @param key - Cache key (without prefix).
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Checks if a cached value exists.
+     *
+     * @param key - Cache key (without prefix).
+     * @returns True when the key exists.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Clears all tracked state.
+     *
+     * @returns Nothing.
+     */
+    clear(): void;
+}
+
+export { MockCallerStoreAdapter };

package/dist/adapters/index.d.ts

@@ -1 +1,70 @@
-export { M as MockCallerStoreAdapter } from '../index-COZVROi_.js';
+import { I as IgniterCallerStoreAdapter, a as IgniterCallerStoreOptions } from '../store-D2p2dqGN.js';
+
+/**
+ * @fileoverview In-memory mock store adapter for @igniter-js/caller.
+ * @module @igniter-js/caller/adapters/mock
+ */
+
+/**
+ * In-memory mock adapter for request caching in tests.
+ */
+declare class MockCallerStoreAdapter implements IgniterCallerStoreAdapter<Map<string, unknown>> {
+    /** Creates a new mock adapter instance. */
+    static create(): MockCallerStoreAdapter;
+    /** Underlying in-memory store. */
+    readonly client: Map<string, unknown>;
+    /** Tracks all calls for assertions. */
+    readonly calls: {
+        get: number;
+        set: number;
+        delete: number;
+        has: number;
+    };
+    /** Captures recent operations. */
+    readonly history: {
+        get: string[];
+        set: Array<{
+            key: string;
+            value: unknown;
+            options?: IgniterCallerStoreOptions;
+        }>;
+        delete: string[];
+        has: string[];
+    };
+    /**
+     * Retrieves a cached value by key.
+     *
+     * @param key - Cache key (without prefix).
+     * @returns Cached value or null.
+     */
+    get<T = any>(key: string): Promise<T | null>;
+    /**
+     * Stores a cached value.
+     *
+     * @param key - Cache key (without prefix).
+     * @param value - Value to store.
+     * @param options - Cache options (ttl, etc).
+     */
+    set(key: string, value: any, options?: IgniterCallerStoreOptions): Promise<void>;
+    /**
+     * Removes a cached value.
+     *
+     * @param key - Cache key (without prefix).
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Checks if a cached value exists.
+     *
+     * @param key - Cache key (without prefix).
+     * @returns True when the key exists.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Clears all tracked state.
+     *
+     * @returns Nothing.
+     */
+    clear(): void;
+}
+
+export { MockCallerStoreAdapter };