Skip to content

docs(readme): align with v6 SDK surface #88

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mourraille merged 1 commit into from
May 14, 2026
Merged

docs(readme): align with v6 SDK surface #88

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 99 additions & 37 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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',
Expand Down Expand Up @@ -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;
},
});
```

Expand All @@ -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>
Expand All @@ -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
Expand All @@ -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.

---

Expand Down
Loading