diff --git a/README.md b/README.md
index 83077ed..a8d457f 100644
--- a/README.md
+++ b/README.md
@@ -42,11 +42,24 @@ console.log('Email sent:', result);
 ```typescript
 const brevo = new BrevoClient({
   apiKey: 'your-api-key',
-  timeout: 30000,      // 30 seconds
-  maxRetries: 3        // Default: 2
+  timeoutInSeconds: 30,
+  maxRetries: 3,
 });
 ```
 
+### Constructor options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | Required (unless `auth` is provided) | Your Brevo API key |
+| `auth` | `AuthProvider` | `null` | Custom auth provider (OAuth, dynamic tokens, key rotation). Mutually exclusive with `apiKey`. |
+| `timeoutInSeconds` | `number` | `60` | Default request timeout in seconds |
+| `maxRetries` | `number` | `2` | Maximum retry attempts on retryable errors |
+| `baseUrl` | `string` | `null` | Override the default API base URL |
+| `fetch` | `typeof fetch` | `null` | Custom fetch implementation |
+| `headers` | `Record<string, string>` | `null` | Additional default headers sent with every request |
+| `logging` | `LogConfig \| Logger` | `null` | Logging configuration |
+
 ---
 
 ## Error Handling
@@ -256,7 +269,7 @@ const request: Brevo.SendTransacEmailRequest = {
 ## Logging
 
 ```typescript
-import { BrevoClient, logging } from 'getbrevo/brevo';
+import { BrevoClient, logging } from '@getbrevo/brevo';
 
 const brevo = new BrevoClient({
   apiKey: 'your-api-key',
@@ -293,14 +306,14 @@ const logger: logging.ILogger = {
 Override the default fetch implementation for advanced use cases.
 
 ```typescript
-const customFetcher = async (url: string, options?: RequestInit): Promise<Response> => {
-  // Your custom implementation
-  return fetch(url, options);
-};
-
 const brevo = new BrevoClient({
   apiKey: 'your-api-key',
-  fetcher: customFetcher
+  fetch: async (url, options) => {
+    console.log('→', url);
+    const response = await fetch(url, options);
+    console.log('←', response.status);
+    return response;
+  },
 });
 ```
 
@@ -310,37 +323,39 @@ const brevo = new BrevoClient({
 **Using node-fetch:**
 ```typescript
 import fetch from 'node-fetch';
+
 const brevo = new BrevoClient({
   apiKey: 'your-api-key',
-  fetcher: fetch as any
+  fetch: fetch as typeof globalThis.fetch,
 });
 ```
 
 **Using undici:**
 ```typescript
 import { fetch } from 'undici';
+
 const brevo = new BrevoClient({
   apiKey: 'your-api-key',
-  fetcher: fetch as any
+  fetch: fetch as typeof globalThis.fetch,
 });
 ```
 
-**With interceptors:**
+**With a request ID header:**
 ```typescript
-const createFetcherWithInterceptors = () => {
-  return async (url: string, options?: RequestInit): Promise<Response> => {
-    const modifiedOptions = {
+import { randomUUID } from 'crypto';
+
+const brevo = new BrevoClient({
+  apiKey: 'your-api-key',
+  fetch: async (url, options) => {
+    return fetch(url, {
       ...options,
       headers: {
         ...options?.headers,
-        'X-Request-ID': generateRequestId()
-      }
-    };
-    const response = await fetch(url, modifiedOptions);
-    console.log('Response:', response.status);
-    return response;
-  };
-};
+        'X-Request-ID': randomUUID(),
+      },
+    });
+  },
+});
 ```
 
 </details>
@@ -358,20 +373,67 @@ const createFetcherWithInterceptors = () => {
 
 ---
 
-## Migration from v3.x
+## Upgrading from v5.x
+
+v6 is a major release. Most breaking changes come from an internal effort at Brevo to make endpoints, parameters and models more **self-descriptive** — so names, shapes and required fields convey intent without needing to cross-reference external docs (both for developers and for AI agents working against the Brevo API).
+
+v5.x remains supported. If you need to hold on v5 temporarily, pin it:
+
+```bash
+npm install @getbrevo/brevo@^5.0
+```
 
 <details>
-<summary>View migration guide</summary>
+<summary>View v5 → v6 migration guide</summary>
 
-This version includes breaking changes:
+### Breaking changes
 
-**Key Changes:**
-- New client initialization
-- Promise-based API
-- Improved TypeScript support
-- Standardized error handling
+**Companies — `getCompanies` filter parameter renamed**
+```typescript
+// v5
+await brevo.companies.getCompanies({ filters: 'foo' });
 
-**Example:**
+// v6
+await brevo.companies.getCompanies({ 'filters[attributes.name]': 'foo' });
+```
+The old `filters` name still compiles but the filter is silently dropped server-side and you get an unfiltered list. Audit every call site.
+
+**Events — `createBatchEvents` payload shape**
+```typescript
+// v5
+await brevo.event.createBatchEvents([{ /* event */ }]);
+
+// v6
+await brevo.event.createBatchEvents({ events: [{ /* event */ }] });
+```
+
+**Balance — `getActiveBalancesApi` response & parameter rename**
+- Response type replaced: `BalanceLimit` → `GetLoyaltyBalanceProgramsPidActiveBalanceResponse`.
+- Parameters renamed from snake_case to camelCase: `contact_id` → `contactId`, `balance_definition_id` → `balanceDefinitionId`, `sort_field` → `sortField`.
+
+**Balance — `getContactBalances` requires `balanceDefinitionId`**
+
+**CRM — `getCrmTasktypes` returns an array** (`GetCrmTasktypesResponseItem[]`).
+
+**Model fields removed**: `GetWebhook.channel`, `GetProcessResponseInfo.export`, `GetEventsList.events[].source`, `GetExtendedCampaignOverview.utmIDActive` (replaced by `utmID: number`).
+
+**Model fields renamed**: `ConversationsMessage.File.filename` → `name`, `.url` → `link`; `SendTransacSms.tag` is now `string | string[]`.
+
+**Now-required fields**: `GetContactDetails.whatsappBlacklisted`, `Note.text`, `Task.date`.
+
+### Added
+
+- `BrevoClient` accepts a new `auth` option for custom `AuthProvider` injection (existing `apiKey` continues to work unchanged).
+- New optional fields and filters across `contacts.createContact`, `contacts.updateContact`, `emailCampaigns.getEmailCampaigns`, `ecommerce.getProducts`, and several other endpoints.
+
+</details>
+
+---
+
+## Migration from v3.x
+
+<details>
+<summary>View migration guide</summary>
 
 **v3.x:**
 ```typescript
@@ -389,26 +451,26 @@ message.to = [{ email: "sarah.davis@example.com", name: "Sarah Davis" }];
 emailAPI.sendTransacEmail(message);
 ```
 
-**v4.x:**
+**v6.x:**
 ```typescript
-import { BrevoClient } from 'getbrevo/brevo';
+import { BrevoClient } from '@getbrevo/brevo';
 
 const brevo = new BrevoClient({
-  apiKey: 'xkeysib-xxx'
+  apiKey: 'xkeysib-xxx',
 });
 
 await brevo.transactionalEmails.sendTransacEmail({
   subject: "First email",
   textContent: "Hello world!",
   sender: { name: "Bob Wilson", email: "bob.wilson@example.com" },
-  to: [{ email: "sarah.davis@example.com", name: "Sarah Davis" }]
+  to: [{ email: "sarah.davis@example.com", name: "Sarah Davis" }],
 });
 ```
 
 </details>
 
 > [!WARNING]
-> The legacy v3.x SDK (`@getbrevo/brevo@^3.0.1`) will continue to receive critical security updates but no new features. We recommend migrating to v4.x.
+> The legacy v3.x SDK (`@getbrevo/brevo@^3.0.1`) will continue to receive critical security updates but no new features. We recommend migrating to v6.x.
 
 ---