feat: add docs (#3)

Author: romanindev

docs/v1/auth.md

@@ -0,0 +1,40 @@
+# Auth
+
+`@dfsync/client` supports auth configuration so you can attach tokens or other credentials to requests.
+
+This allows you to centralize auth logic instead of repeating it in every request.
+
+## Example
+
+```ts
+import { createClient } from '@dfsync/client';
+
+const client = createClient({
+  baseURL: 'https://api.example.com',
+
+  auth: async ({ request }) => {
+    request.headers.set('Authorization', 'Bearer TOKEN');
+  },
+});
+```
+
+Every request sent by the client will include the Authorization header.
+
+## Common use cases
+
+- internal service authentication
+- bearer tokens
+- API tokens
+- integration services
+
+## Why configure auth on the client?
+
+Centralizing authentication inside the client configuration provides:
+
+- consistent authentication across requests
+- cleaner application code
+- easier token rotation or refresh logic
+
+## Notes
+
+Keep auth logic centralized in the client configuration instead of repeating it in every request.

docs/v1/create-client.md

@@ -0,0 +1,37 @@
+# Create Client
+
+Use `createClient` to configure a reusable HTTP client.
+
+## Basic example
+
+```ts
+import { createClient } from '@dfsync/client';
+
+const client = createClient({
+  baseURL: 'https://api.example.com',
+});
+```
+
+## Configuration
+
+```ts
+const client = createClient({
+  baseURL: 'https://api.example.com',
+  timeout: 5000,
+  headers: {
+    Accept: 'application/json',
+  },
+});
+```
+
+## Making requests
+
+```ts
+const users = await client.get('/users');
+
+const createdUser = await client.post('/users', {
+  name: 'Roman',
+});
+```
+
+Using a shared client keeps configuration centralized and consistent across requests.

docs/v1/errors.md

@@ -0,0 +1,25 @@
+# Errors
+
+Requests may fail due to different reasons such as HTTP errors, network issues, or timeouts.
+
+Use standard `try/catch` handling to handle failures.
+
+## Example
+
+```ts
+try {
+  const users = await client.get('/users');
+} catch (error) {
+  console.error(error);
+}
+```
+
+## Typical error types
+
+- HTTP errors (non-2xx responses)
+- network errors
+- timeout errors
+
+## Note
+
+Handle errors close to the application logic that depends on the request result.

docs/v1/examples.md

@@ -0,0 +1,35 @@
+# Examples
+
+## Basic client
+
+```ts
+const client = createClient({
+  baseURL: 'https://api.example.com',
+});
+```
+
+## GET request
+
+```ts
+const users = await client.get('/users');
+```
+
+## POST JSON
+
+```ts
+const createdUser = await client.post('/users', {
+  name: 'Tom',
+});
+```
+
+## Client with auth
+
+```ts
+const client = createClient({
+  baseURL: 'https://api.example.com',
+
+  auth: async ({ request }) => {
+    request.headers.set('Authorization', 'Bearer TOKEN');
+  },
+});
+```

docs/v1/getting-started.md

@@ -0,0 +1,32 @@
+# Getting Started
+
+`@dfsync/client` is a lightweight TypeScript HTTP client designed for reliable service-to-service communication.
+
+It provides sensible defaults for:
+
+- microservices
+- internal APIs
+- worker and integration services
+- external API communication
+
+The client focuses on predictable behavior, extensibility, and a clean developer experience.
+
+## Quick example
+
+```ts
+import { createClient } from '@dfsync/client';
+
+const client = createClient({
+  baseURL: 'https://api.example.com',
+});
+
+const users = await client.get('/users');
+```
+
+## Features
+
+- simple HTTP client API
+- built-in auth support
+- lifecycle hooks
+- consistent error handling
+- good defaults for service communication

docs/v1/hooks.md

@@ -0,0 +1,41 @@
+# Hooks
+
+Hooks allow you to extend the behavior of the HTTP client during the request lifecycle.
+
+They can be used to implement cross-cutting concerns such as logging, tracing, or instrumentation.
+
+## Example
+
+```ts
+import { createClient } from '@dfsync/client';
+
+const client = createClient({
+  baseURL: 'https://api.example.com',
+  hooks: {
+    beforeRequest: [
+      async (ctx) => {
+        console.log('Outgoing request:', ctx.request.url);
+      },
+    ],
+    afterResponse: [
+      async (ctx) => {
+        console.log('Response status:', ctx.response.status);
+      },
+    ],
+  },
+});
+```
+
+## Common use cases
+
+Hooks can be used for:
+
+- request logging
+- tracing and correlation IDs
+- metrics and observability
+- debugging outgoing requests
+- modifying requests before they are sent
+
+## Note
+
+Use hooks for infrastructure concerns instead of duplicating logic across your application.

docs/v1/installation.md

@@ -0,0 +1,26 @@
+# Installation
+
+Install the package with your preferred package manager.
+
+## npm
+
+```bash
+npm install @dfsync/client
+```
+
+## Requirements
+
+- Node.js 18+
+- TypeScript (recommended)
+
+## After installation
+
+Create your first client instance:
+
+```typescript
+import { createClient } from '@dfsync/client';
+
+const client = createClient({
+  baseURL: 'https://api.example.com',
+});
+```