enlace 0.0.1-beta.4 → 0.0.1-beta.6

package/README.md

@@ -11,7 +11,8 @@ npm install enlace
 ## Quick Start
 
 ```typescript
-import { createEnlaceHook, Endpoint } from "enlace";
+import { createEnlaceHookReact } from "enlace/hook";
+import { Endpoint } from "enlace";
 
 type ApiSchema = {
   posts: {
@@ -24,7 +25,7 @@ type ApiSchema = {
   };
 };
 
-const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com");
+const useAPI = createEnlaceHookReact<ApiSchema>("https://api.example.com");
 ```
 
 ## Schema Conventions
@@ -33,13 +34,13 @@ Defining a schema is **recommended** for full type safety, but **optional**. You
 
 ```typescript
 // Without schema (untyped, but still works!)
-const useAPI = createEnlaceHook("https://api.example.com");
+const useAPI = createEnlaceHookReact("https://api.example.com");
 const { data } = useAPI((api) => api.any.path.you.want.get());
 ```
 
 ```typescript
 // With schema (recommended for type safety)
-const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com");
+const useAPI = createEnlaceHookReact<ApiSchema>("https://api.example.com");
 ```
 
 ### Schema Structure
@@ -310,7 +311,7 @@ trigger({ body: { title: "New" } });
 Control how long cached data is considered fresh:
 
 ```typescript
-const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com", {}, {
+const useAPI = createEnlaceHookReact<ApiSchema>("https://api.example.com", {}, {
   staleTime: 5000, // 5 seconds
 });
 ```
@@ -337,7 +338,7 @@ trigger({
 ### Disable Auto-Revalidation
 
 ```typescript
-const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com", {}, {
+const useAPI = createEnlaceHookReact<ApiSchema>("https://api.example.com", {}, {
   autoGenerateTags: false,     // Disable auto tag generation
   autoRevalidateTags: false,   // Disable auto revalidation
 });
@@ -346,7 +347,7 @@ const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com", {}, {
 ## Hook Options
 
 ```typescript
-const useAPI = createEnlaceHook<ApiSchema>(
+const useAPI = createEnlaceHookReact<ApiSchema>(
   "https://api.example.com",
   {
     // Default fetch options
@@ -361,6 +362,92 @@ const useAPI = createEnlaceHook<ApiSchema>(
 );
 ```
 
+### Async Headers
+
+Headers can be provided as a static value, sync function, or async function. This is useful when you need to fetch headers dynamically (e.g., auth tokens from async storage):
+
+```typescript
+// Static headers
+const useAPI = createEnlaceHookReact<ApiSchema>("https://api.example.com", {
+  headers: { Authorization: "Bearer token" },
+});
+
+// Sync function
+const useAPI = createEnlaceHookReact<ApiSchema>("https://api.example.com", {
+  headers: () => ({ Authorization: `Bearer ${getToken()}` }),
+});
+
+// Async function
+const useAPI = createEnlaceHookReact<ApiSchema>("https://api.example.com", {
+  headers: async () => {
+    const token = await getTokenFromStorage();
+    return { Authorization: `Bearer ${token}` };
+  },
+});
+```
+
+This also works for per-request headers:
+
+```typescript
+const { data } = useAPI((api) =>
+  api.posts.get({
+    headers: async () => {
+      const token = await refreshToken();
+      return { Authorization: `Bearer ${token}` };
+    },
+  })
+);
+```
+
+### Global Callbacks
+
+You can set up global `onSuccess` and `onError` callbacks that are called for every request:
+
+```typescript
+const useAPI = createEnlaceHookReact<ApiSchema>(
+  "https://api.example.com",
+  {
+    headers: { Authorization: "Bearer token" },
+  },
+  {
+    onSuccess: (payload) => {
+      console.log("Request succeeded:", payload.status, payload.data);
+    },
+    onError: (payload) => {
+      if (payload.status === 0) {
+        // Network error
+        console.error("Network error:", payload.error.message);
+      } else {
+        // HTTP error (4xx, 5xx)
+        console.error("HTTP error:", payload.status, payload.error);
+      }
+    },
+  }
+);
+```
+
+**Callback Payloads:**
+
+```typescript
+// onSuccess payload
+type EnlaceCallbackPayload<T> = {
+  status: number;
+  data: T;
+  headers: Headers;
+};
+
+// onError payload (HTTP error or network error)
+type EnlaceErrorCallbackPayload<T> =
+  | { status: number; error: T; headers: Headers }  // HTTP error
+  | { status: 0; error: Error; headers: null };     // Network error
+```
+
+**Use cases:**
+- Global error logging/reporting
+- Toast notifications for all API errors
+- Authentication refresh on 401 errors
+- Analytics tracking
+
 ## Return Types
 
 ### Query Mode
@@ -403,6 +490,7 @@ type UseEnlaceSelectorResult<TMethod> = {
 type RequestOptions = {
   query?: Record<string, unknown>;        // Query parameters
   body?: TBody;                           // Request body
+  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);  // Request headers
   tags?: string[];                        // Cache tags (GET only)
   revalidateTags?: string[];              // Tags to invalidate after mutation
   pathParams?: Record<string, string | number>;  // Dynamic path parameters
@@ -415,12 +503,12 @@ type RequestOptions = {
 
 ### Server Components
 
-Use `createEnlace` from `enlace/next` for server components:
+Use `createEnlaceNext` from `enlace` for server components:
 
 ```typescript
-import { createEnlace } from "enlace/next";
+import { createEnlaceNext } from "enlace";
 
-const api = createEnlace<ApiSchema>("https://api.example.com", {}, {
+const api = createEnlaceNext<ApiSchema>("https://api.example.com", {}, {
   autoGenerateTags: true,
 });
 
@@ -435,14 +523,14 @@ export default async function Page() {
 
 ### Client Components
 
-Use `createEnlaceHook` from `enlace/next/hook` for client components:
+Use `createEnlaceHookNext` from `enlace/hook` for client components:
 
 ```typescript
 "use client";
 
-import { createEnlaceHook } from "enlace/next/hook";
+import { createEnlaceHookNext } from "enlace/hook";
 
-const useAPI = createEnlaceHook<ApiSchema>("https://api.example.com");
+const useAPI = createEnlaceHookNext<ApiSchema>("https://api.example.com");
 ```
 
 ### Server-Side Revalidation
@@ -467,10 +555,10 @@ export async function revalidateAction(tags: string[], paths: string[]) {
 
 ```typescript
 // useAPI.ts
-import { createEnlaceHook } from "enlace/next/hook";
+import { createEnlaceHookNext } from "enlace/hook";
 import { revalidateAction } from "./actions";
 
-const useAPI = createEnlaceHook<ApiSchema>("/api", {}, {
+const useAPI = createEnlaceHookNext<ApiSchema>("/api", {}, {
   revalidator: revalidateAction,
 });
 ```
@@ -509,17 +597,21 @@ Works with Next.js API routes:
 
 ```typescript
 // Client component calling /api/posts
-const useAPI = createEnlaceHook<ApiSchema>("/api");
+const useAPI = createEnlaceHookNext<ApiSchema>("/api");
 ```
 
 ---
 
 ## API Reference
 
-### `createEnlaceHook<TSchema>(baseUrl, options?, hookOptions?)`
+### `createEnlaceHookReact<TSchema>(baseUrl, options?, hookOptions?)`
 
 Creates a React hook for making API calls.
 
+### `createEnlaceHookNext<TSchema>(baseUrl, options?, hookOptions?)`
+
+Creates a Next.js hook with server revalidation support.
+
 **Parameters:**
 - `baseUrl` — Base URL for requests
 - `options` — Default fetch options (headers, cache, etc.)
@@ -531,6 +623,8 @@ type EnlaceHookOptions = {
   autoGenerateTags?: boolean;    // default: true
   autoRevalidateTags?: boolean;  // default: true
   staleTime?: number;            // default: 0
+  onSuccess?: (payload: EnlaceCallbackPayload<unknown>) => void;
+  onError?: (payload: EnlaceErrorCallbackPayload<unknown>) => void;
 };
 ```
 

package/dist/{next/hook → hook}/index.d.mts

@@ -1,4 +1,4 @@
-import { WildcardClient, EnlaceClient, EnlaceResponse, EnlaceOptions } from 'enlace-core';
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, EnlaceResponse, WildcardClient, EnlaceClient, EnlaceOptions, EnlaceCallbacks } from 'enlace-core';
 
 /** Per-request options for React hooks */
 type ReactRequestOptionsBase = {
@@ -31,6 +31,19 @@ type UseEnlaceQueryOptions = {
 type ApiClient<TSchema, TOptions = ReactRequestOptionsBase> = unknown extends TSchema ? WildcardClient<TOptions> : EnlaceClient<TSchema, TOptions>;
 type QueryFn<TSchema, TData, TError, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => Promise<EnlaceResponse<TData, TError>>;
 type SelectorFn<TSchema, TMethod, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => TMethod;
+type HookState = {
+    loading: boolean;
+    fetching: boolean;
+    ok: boolean | undefined;
+    data: unknown;
+    error: unknown;
+};
+type TrackedCall = {
+    path: string[];
+    method: string;
+    options: unknown;
+};
+declare const HTTP_METHODS: readonly ["get", "post", "put", "patch", "delete"];
 type ExtractData<T> = T extends (...args: any[]) => Promise<EnlaceResponse<infer D, unknown>> ? D : never;
 type ExtractError<T> = T extends (...args: any[]) => Promise<EnlaceResponse<unknown, infer E>> ? E : never;
 /** Discriminated union for hook response state - enables type narrowing on ok check */
@@ -58,7 +71,7 @@ type UseEnlaceSelectorResult<TMethod> = {
     loading: boolean;
     fetching: boolean;
 } & HookResponseState<ExtractData<TMethod>, ExtractError<TMethod>>;
-
+/** Options for createEnlaceHookReact factory */
 type EnlaceHookOptions = {
     /**
      * Auto-generate cache tags from URL path for GET requests.
@@ -70,29 +83,54 @@ type EnlaceHookOptions = {
     autoRevalidateTags?: boolean;
     /** Time in ms before cached data is considered stale. @default 0 (always stale) */
     staleTime?: number;
+    /** Callback called on successful API responses */
+    onSuccess?: (payload: EnlaceCallbackPayload<unknown>) => void;
+    /** Callback called on error responses (HTTP errors or network failures) */
+    onError?: (payload: EnlaceErrorCallbackPayload<unknown>) => void;
+};
+/** Hook type returned by createEnlaceHookReact */
+type EnlaceHook<TSchema> = {
+    <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: SelectorFn<TSchema, TMethod>): UseEnlaceSelectorResult<TMethod>;
+    <TData, TError>(queryFn: QueryFn<TSchema, TData, TError>, options?: UseEnlaceQueryOptions): UseEnlaceQueryResult<TData, TError>;
 };
 
+/**
+ * Creates a React hook for making API calls.
+ * Called at module level to create a reusable hook.
+ *
+ * @example
+ * const useAPI = createEnlaceHookReact<ApiSchema>('https://api.com');
+ *
+ * // Query mode - auto-fetch (auto-tracks changes, no deps array needed)
+ * const { loading, data, error } = useAPI((api) => api.posts.get({ query: { userId } }));
+ *
+ * // Selector mode - typed trigger for lazy calls
+ * const { trigger, loading, data, error } = useAPI((api) => api.posts.delete);
+ * onClick={() => trigger({ body: { id: 1 } })}
+ */
+declare function createEnlaceHookReact<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: EnlaceHookOptions): EnlaceHook<TSchema>;
+
 /**
  * Handler function called after successful mutations to trigger server-side revalidation.
  * @param tags - Cache tags to revalidate
  * @param paths - URL paths to revalidate
  */
 type RevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
-/** Next.js-specific options (third argument for createEnlace) */
-type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateTags"> & {
+/** Next.js-specific options (third argument for createEnlaceNext) */
+type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateTags"> & EnlaceCallbacks & {
     /**
      * Handler called after successful mutations to trigger server-side revalidation.
      * Receives auto-generated or manually specified tags and paths.
      * @example
      * ```ts
-     * createEnlace("http://localhost:3000/api/", {}, {
+     * createEnlaceNext("http://localhost:3000/api/", {}, {
      *   revalidator: (tags, paths) => revalidateServerAction(tags, paths)
      * });
      * ```
      */
     revalidator?: RevalidateHandler;
 };
-/** Next.js hook options (third argument for createEnlaceHook) - extends React's EnlaceHookOptions */
+/** Next.js hook options (third argument for createEnlaceHookNext) - extends React's EnlaceHookOptions */
 type NextHookOptions = EnlaceHookOptions & Pick<NextOptions, "revalidator">;
 /** Per-request options for Next.js fetch - extends React's base options */
 type NextRequestOptionsBase = ReactRequestOptionsBase & {
@@ -113,19 +151,20 @@ type NextRequestOptionsBase = ReactRequestOptionsBase & {
      */
     skipRevalidator?: boolean;
 };
-
 type NextQueryFn<TSchema, TData, TError> = QueryFn<TSchema, TData, TError, NextRequestOptionsBase>;
 type NextSelectorFn<TSchema, TMethod> = SelectorFn<TSchema, TMethod, NextRequestOptionsBase>;
+/** Hook type returned by createEnlaceHookNext */
 type NextEnlaceHook<TSchema> = {
     <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: NextSelectorFn<TSchema, TMethod>): UseEnlaceSelectorResult<TMethod>;
     <TData, TError>(queryFn: NextQueryFn<TSchema, TData, TError>, options?: UseEnlaceQueryOptions): UseEnlaceQueryResult<TData, TError>;
 };
+
 /**
  * Creates a React hook for making API calls in Next.js Client Components.
  * Uses Next.js-specific features like revalidator for server-side cache invalidation.
  *
  * @example
- * const useAPI = createEnlaceHook<ApiSchema>('https://api.com', {}, {
+ * const useAPI = createEnlaceHookNext<ApiSchema>('https://api.com', {}, {
  *   revalidator: (tags) => revalidateTagsAction(tags),
  *   staleTime: 5000,
  * });
@@ -136,6 +175,6 @@ type NextEnlaceHook<TSchema> = {
  * // Selector mode - trigger for mutations
  * const { trigger } = useAPI((api) => api.posts.delete);
  */
-declare function createEnlaceHook<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: NextHookOptions): NextEnlaceHook<TSchema>;
+declare function createEnlaceHookNext<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: NextHookOptions): NextEnlaceHook<TSchema>;
 
-export { createEnlaceHook };
+export { type ApiClient, type EnlaceHook, type EnlaceHookOptions, HTTP_METHODS, type HookState, type NextEnlaceHook, type NextHookOptions, type QueryFn, type ReactRequestOptionsBase, type SelectorFn, type TrackedCall, type UseEnlaceQueryOptions, type UseEnlaceQueryResult, type UseEnlaceSelectorResult, createEnlaceHookNext, createEnlaceHookReact };

package/dist/{next/hook → hook}/index.d.ts

@@ -1,4 +1,4 @@
-import { WildcardClient, EnlaceClient, EnlaceResponse, EnlaceOptions } from 'enlace-core';
+import { EnlaceCallbackPayload, EnlaceErrorCallbackPayload, EnlaceResponse, WildcardClient, EnlaceClient, EnlaceOptions, EnlaceCallbacks } from 'enlace-core';
 
 /** Per-request options for React hooks */
 type ReactRequestOptionsBase = {
@@ -31,6 +31,19 @@ type UseEnlaceQueryOptions = {
 type ApiClient<TSchema, TOptions = ReactRequestOptionsBase> = unknown extends TSchema ? WildcardClient<TOptions> : EnlaceClient<TSchema, TOptions>;
 type QueryFn<TSchema, TData, TError, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => Promise<EnlaceResponse<TData, TError>>;
 type SelectorFn<TSchema, TMethod, TOptions = ReactRequestOptionsBase> = (api: ApiClient<TSchema, TOptions>) => TMethod;
+type HookState = {
+    loading: boolean;
+    fetching: boolean;
+    ok: boolean | undefined;
+    data: unknown;
+    error: unknown;
+};
+type TrackedCall = {
+    path: string[];
+    method: string;
+    options: unknown;
+};
+declare const HTTP_METHODS: readonly ["get", "post", "put", "patch", "delete"];
 type ExtractData<T> = T extends (...args: any[]) => Promise<EnlaceResponse<infer D, unknown>> ? D : never;
 type ExtractError<T> = T extends (...args: any[]) => Promise<EnlaceResponse<unknown, infer E>> ? E : never;
 /** Discriminated union for hook response state - enables type narrowing on ok check */
@@ -58,7 +71,7 @@ type UseEnlaceSelectorResult<TMethod> = {
     loading: boolean;
     fetching: boolean;
 } & HookResponseState<ExtractData<TMethod>, ExtractError<TMethod>>;
-
+/** Options for createEnlaceHookReact factory */
 type EnlaceHookOptions = {
     /**
      * Auto-generate cache tags from URL path for GET requests.
@@ -70,29 +83,54 @@ type EnlaceHookOptions = {
     autoRevalidateTags?: boolean;
     /** Time in ms before cached data is considered stale. @default 0 (always stale) */
     staleTime?: number;
+    /** Callback called on successful API responses */
+    onSuccess?: (payload: EnlaceCallbackPayload<unknown>) => void;
+    /** Callback called on error responses (HTTP errors or network failures) */
+    onError?: (payload: EnlaceErrorCallbackPayload<unknown>) => void;
+};
+/** Hook type returned by createEnlaceHookReact */
+type EnlaceHook<TSchema> = {
+    <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: SelectorFn<TSchema, TMethod>): UseEnlaceSelectorResult<TMethod>;
+    <TData, TError>(queryFn: QueryFn<TSchema, TData, TError>, options?: UseEnlaceQueryOptions): UseEnlaceQueryResult<TData, TError>;
 };
 
+/**
+ * Creates a React hook for making API calls.
+ * Called at module level to create a reusable hook.
+ *
+ * @example
+ * const useAPI = createEnlaceHookReact<ApiSchema>('https://api.com');
+ *
+ * // Query mode - auto-fetch (auto-tracks changes, no deps array needed)
+ * const { loading, data, error } = useAPI((api) => api.posts.get({ query: { userId } }));
+ *
+ * // Selector mode - typed trigger for lazy calls
+ * const { trigger, loading, data, error } = useAPI((api) => api.posts.delete);
+ * onClick={() => trigger({ body: { id: 1 } })}
+ */
+declare function createEnlaceHookReact<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: EnlaceHookOptions): EnlaceHook<TSchema>;
+
 /**
  * Handler function called after successful mutations to trigger server-side revalidation.
  * @param tags - Cache tags to revalidate
  * @param paths - URL paths to revalidate
  */
 type RevalidateHandler = (tags: string[], paths: string[]) => void | Promise<void>;
-/** Next.js-specific options (third argument for createEnlace) */
-type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateTags"> & {
+/** Next.js-specific options (third argument for createEnlaceNext) */
+type NextOptions = Pick<EnlaceHookOptions, "autoGenerateTags" | "autoRevalidateTags"> & EnlaceCallbacks & {
     /**
      * Handler called after successful mutations to trigger server-side revalidation.
      * Receives auto-generated or manually specified tags and paths.
      * @example
      * ```ts
-     * createEnlace("http://localhost:3000/api/", {}, {
+     * createEnlaceNext("http://localhost:3000/api/", {}, {
      *   revalidator: (tags, paths) => revalidateServerAction(tags, paths)
      * });
      * ```
      */
     revalidator?: RevalidateHandler;
 };
-/** Next.js hook options (third argument for createEnlaceHook) - extends React's EnlaceHookOptions */
+/** Next.js hook options (third argument for createEnlaceHookNext) - extends React's EnlaceHookOptions */
 type NextHookOptions = EnlaceHookOptions & Pick<NextOptions, "revalidator">;
 /** Per-request options for Next.js fetch - extends React's base options */
 type NextRequestOptionsBase = ReactRequestOptionsBase & {
@@ -113,19 +151,20 @@ type NextRequestOptionsBase = ReactRequestOptionsBase & {
      */
     skipRevalidator?: boolean;
 };
-
 type NextQueryFn<TSchema, TData, TError> = QueryFn<TSchema, TData, TError, NextRequestOptionsBase>;
 type NextSelectorFn<TSchema, TMethod> = SelectorFn<TSchema, TMethod, NextRequestOptionsBase>;
+/** Hook type returned by createEnlaceHookNext */
 type NextEnlaceHook<TSchema> = {
     <TMethod extends (...args: any[]) => Promise<EnlaceResponse<unknown, unknown>>>(selector: NextSelectorFn<TSchema, TMethod>): UseEnlaceSelectorResult<TMethod>;
     <TData, TError>(queryFn: NextQueryFn<TSchema, TData, TError>, options?: UseEnlaceQueryOptions): UseEnlaceQueryResult<TData, TError>;
 };
+
 /**
  * Creates a React hook for making API calls in Next.js Client Components.
  * Uses Next.js-specific features like revalidator for server-side cache invalidation.
  *
  * @example
- * const useAPI = createEnlaceHook<ApiSchema>('https://api.com', {}, {
+ * const useAPI = createEnlaceHookNext<ApiSchema>('https://api.com', {}, {
  *   revalidator: (tags) => revalidateTagsAction(tags),
  *   staleTime: 5000,
  * });
@@ -136,6 +175,6 @@ type NextEnlaceHook<TSchema> = {
  * // Selector mode - trigger for mutations
  * const { trigger } = useAPI((api) => api.posts.delete);
  */
-declare function createEnlaceHook<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: NextHookOptions): NextEnlaceHook<TSchema>;
+declare function createEnlaceHookNext<TSchema = unknown>(baseUrl: string, defaultOptions?: EnlaceOptions, hookOptions?: NextHookOptions): NextEnlaceHook<TSchema>;
 
-export { createEnlaceHook };
+export { type ApiClient, type EnlaceHook, type EnlaceHookOptions, HTTP_METHODS, type HookState, type NextEnlaceHook, type NextHookOptions, type QueryFn, type ReactRequestOptionsBase, type SelectorFn, type TrackedCall, type UseEnlaceQueryOptions, type UseEnlaceQueryResult, type UseEnlaceSelectorResult, createEnlaceHookNext, createEnlaceHookReact };