update docs for release 0.8.x

Author: romanindev

docs/v1/api-reference.md

@@ -4,21 +4,58 @@
 
 Creates a configured HTTP client.
 
+```ts
+import { createClient } from '@dfsync/client';
+```
+
 ## Client methods
 
-- `get`
-- `post`
-- `put`
-- `patch`
-- `delete`
+```text
+client.get(path, options?)
+client.delete(path, options?)
+
+client.post(path, body?, options?)
+client.put(path, body?, options?)
+client.patch(path, body?, options?)
+
+client.request(config)
+```
 
 ## Configuration
 
 - `baseUrl`
 - `timeout`
+- `headers`
+- `fetch`
 - `retry`
 - `auth`
 - `hooks`
+- `validateResponse`
+
+## Request options
+
+- `query`
+- `headers`
+- `timeout`
+- `retry`
+- `signal`
+- `requestId`
+- `idempotencyKey`
+- `validateResponse`
+
+## Retry
+
+- `attempts`
+- `backoff`
+- `baseDelayMs`
+- `retryOn`
+- `retryMethods`
+
+## Response validation
+
+```ts
+type ResponseValidator<TData = unknown> = (data: TData) => boolean | void | Promise<boolean | void>;
+```
 
 ## Hooks
 
@@ -32,4 +69,22 @@ Creates a configured HTTP client.
 - `HttpError`
 - `NetworkError`
 - `TimeoutError`
+- `ValidationError`
 - `RequestAbortedError`
+
+## Exported types
+
+- `AuthConfig`
+- `Client`
+- `ClientConfig`
+- `RetryConfig`
+- `RetryCondition`
+- `RetryBackoff`
+- `ResponseValidator`
+- `BeforeRequestContext`
+- `AfterResponseContext`
+- `ErrorContext`
+- `RetryContext`
+- `HooksConfig`
+- `RequestConfig`
+- `RequestOptions`

docs/v1/create-client.md

@@ -9,6 +9,7 @@ It provides a consistent way to configure:
 - auth
 - lifecycle hooks
 - request observability metadata
+- response validation
 
 ## Basic client
 
@@ -64,6 +65,7 @@ type ClientConfig = {
     // see Hooks section
   };
   retry?: RetryConfig;
+  validateResponse?: ResponseValidator;
 };
 ```
 
@@ -100,7 +102,7 @@ client.request(config)
 
 - `get` and `delete` do not accept body
 - `post`, `put`, and `patch` accept request body as the second argument
-- `options` is used for headers, query, timeout, retry, and other settings
+- `options` is used for headers, query, timeout, retry, validation, idempotency keys, and other settings
 
 ## GET request
 
@@ -165,13 +167,17 @@ type RequestOptions = {
   retry?: RetryConfig;
   signal?: AbortSignal;
   requestId?: string;
+  idempotencyKey?: string;
+  validateResponse?: ResponseValidator;
 };
 ```
 
 `requestId` can be provided explicitly when you want to correlate logs or trace a request across services.
 
 Request-level `retry` overrides client-level retry settings.
 
+Request-level `validateResponse` overrides client-level response validation.
+
 ## Low-level request
 
 ```ts
@@ -201,6 +207,8 @@ type RequestConfig = {
   retry?: RetryConfig;
   signal?: AbortSignal;
   requestId?: string;
+  idempotencyKey?: string;
+  validateResponse?: ResponseValidator;
 };
 ```
 
@@ -258,6 +266,55 @@ await client.get('/users', {
 });
 ```
 
+## Idempotency key
+
+Use `idempotencyKey` for non-idempotent operations that may be retried safely.
+
+```ts
+await client.post(
+  '/payments',
+  { amount: 100 },
+  {
+    idempotencyKey: 'payment-123',
+  },
+);
+```
+
+This adds:
+
+```http
+idempotency-key: payment-123
+```
+
+If both `idempotencyKey` and an explicit `idempotency-key` header are provided, the explicit header takes precedence.
+
+`POST` and `PATCH` requests are retried only when the method is included in `retry.retryMethods` and the request provides `idempotencyKey`.
+
+## Response validation
+
+Use `validateResponse` to validate parsed response data before it is returned.
+
+```ts
+const client = createClient({
+  baseUrl: 'https://api.example.com',
+  validateResponse(data) {
+    return typeof data === 'object' && data !== null && 'id' in data;
+  },
+});
+```
+
+You can override validation per request:
+
+```ts
+await client.get('/users/1', {
+  validateResponse(data) {
+    return typeof data === 'object' && data !== null && 'email' in data;
+  },
+});
+```
+
+Returning `false` throws `ValidationError`. Returning `true` or `undefined` passes validation.
+
 ## Request cancellation
 
 Requests can be cancelled using `AbortSignal`:
@@ -361,5 +418,6 @@ If the header value is invalid, `@dfsync/client` falls back to normal retry back
 ## Related guides
 
 - See **Hooks** for lifecycle hooks and observability metadata
+- See **Response Handling** for parsing and response validation
 - See **Retry** for retry conditions, backoff, and `Retry-After`
 - See **Errors** for failure behavior and error types

docs/v1/errors.md

@@ -8,9 +8,10 @@
 - `HttpError` — non-2xx responses
 - `NetworkError` — network failures
 - `TimeoutError` — request timed out
+- `ValidationError` — response validation failed
 - `RequestAbortedError` — request was cancelled
 
-- This allows you to handle failures more precisely.
+This allows you to handle failures more precisely.
 
 ## Base error
 
@@ -114,14 +115,68 @@ try {
 
 Properties:
 
-- `code` → `"NETWORK_ERROR"`
+- `code` → `"TIMEOUT_ERROR"`
 - `timeout`
 - optional `cause`
 
+## ValidationError
+
+Thrown when a successful response fails `validateResponse`.
+
+```ts
+import { ValidationError } from '@dfsync/client';
+
+try {
+  await client.get('/users/1');
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error(error.data);
+    console.error(error.response.status);
+  }
+}
+```
+
+Properties:
+
+- `code` → `"VALIDATION_ERROR"`
+- `data`
+- `response`
+
+Validation failures are not retried.
+
+## RequestAbortedError
+
+Thrown when the request is cancelled by an external `AbortSignal`.
+
+```ts
+import { RequestAbortedError } from '@dfsync/client';
+
+const controller = new AbortController();
+
+const promise = client.get('/users', {
+  signal: controller.signal,
+});
+
+controller.abort();
+
+try {
+  await promise;
+} catch (error) {
+  if (error instanceof RequestAbortedError) {
+    console.error('Request was cancelled');
+  }
+}
+```
+
+Properties:
+
+- `code` → `"REQUEST_ABORTED"`
+- optional `cause`
+
 ## Error handling example
 
 ```ts
-import { HttpError, NetworkError, TimeoutError } from '@dfsync/client';
+import { HttpError, NetworkError, TimeoutError, ValidationError } from '@dfsync/client';
 
 try {
   const result = await client.get('/users/1');
@@ -143,6 +198,11 @@ try {
     throw error;
   }
 
+  if (error instanceof ValidationError) {
+    console.error('Unexpected response payload:', error.data);
+    throw error;
+  }
+
   throw error;
 }
 ```

docs/v1/examples.md

@@ -3,8 +3,10 @@
 ## Basic client
 
 ```ts
+import { createClient } from '@dfsync/client';
+
 const client = createClient({
-  baseURL: 'https://api.example.com',
+  baseUrl: 'https://api.example.com',
 });
 ```
 
@@ -49,10 +51,53 @@ const singleUser = await client.request<User>({
 
 ```ts
 const client = createClient({
-  baseURL: 'https://api.example.com',
+  baseUrl: 'https://api.example.com',
+  auth: {
+    type: 'bearer',
+    token: 'TOKEN',
+  },
+});
+```
+
+## Response validation
+
+```ts
+import { ValidationError } from '@dfsync/client';
+
+const client = createClient({
+  baseUrl: 'https://api.example.com',
+  validateResponse(data) {
+    return typeof data === 'object' && data !== null && 'id' in data;
+  },
+});
+
+try {
+  const user = await client.get('/users/1');
+  console.log(user);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    console.error(error.data);
+  }
+}
+```
+
+## Safe POST retry
 
-  auth: async ({ request }) => {
-    request.headers.set('Authorization', 'Bearer TOKEN');
+```ts
+const client = createClient({
+  baseUrl: 'https://api.example.com',
+  retry: {
+    attempts: 2,
+    retryMethods: ['POST'],
+    retryOn: ['5xx'],
   },
 });
+
+const payment = await client.post(
+  '/payments',
+  { amount: 100 },
+  {
+    idempotencyKey: 'payment-123',
+  },
+);
 ```

docs/v1/getting-started.md

@@ -17,13 +17,15 @@ The client focuses on predictable behavior, extensibility, and a clean developer
 - request ID propagation (`x-request-id`)
 - request cancellation via `AbortSignal`
 - built-in retry with configurable policies
-- lifecycle hooks: `beforeRequest`, `afterResponse`, `onError`
+- lifecycle hooks: `beforeRequest`, `afterResponse`, `onError`, `onRetry`
 
 - typed responses
 - automatic JSON parsing
+- response validation with `ValidationError`
 - consistent error handling
 
 - auth support: bearer, API key, custom
+- idempotency key support for safer retries
 - support for `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`
 
 ## Quick example