@getbrevo/brevo 5.0.4 → 6.0.1

package/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.
 
 ---
 

package/dist/cjs/BaseClient.d.ts

@@ -1,6 +1,7 @@
 import { HeaderAuthProvider } from "./auth/HeaderAuthProvider.js";
 import * as core from "./core/index.js";
 import type * as environments from "./environments.js";
+export type AuthOption = false | core.AuthProvider["getAuthRequest"] | core.AuthProvider | HeaderAuthProvider.AuthOptions;
 export type BaseClientOptions = {
     environment?: core.Supplier<environments.BrevoEnvironment | string>;
     /** Specify a custom URL to connect the client to. */
@@ -15,6 +16,8 @@ export type BaseClientOptions = {
     fetch?: typeof fetch;
     /** Configure logging for the client. */
     logging?: core.logging.LogConfig | core.logging.Logger;
+    /** Override auth. Pass false to disable, a function returning auth headers, an AuthProvider, or auth options. */
+    auth?: AuthOption;
 } & HeaderAuthProvider.AuthOptions;
 export interface BaseRequestOptions {
     /** The maximum time to wait for a response in seconds. */

package/dist/cjs/BaseClient.js

@@ -43,8 +43,8 @@ function normalizeClientOptions(options) {
     const headers = (0, headers_js_1.mergeHeaders)({
         "X-Fern-Language": "JavaScript",
         "X-Fern-SDK-Name": "@getbrevo/brevo",
-        "X-Fern-SDK-Version": "5.0.4",
-        "User-Agent": "@getbrevo/brevo/5.0.4",
+        "X-Fern-SDK-Version": "6.0.1",
+        "User-Agent": "@getbrevo/brevo/6.0.1",
         "X-Fern-Runtime": core.RUNTIME.type,
         "X-Fern-Runtime-Version": core.RUNTIME.version,
     }, options === null || options === void 0 ? void 0 : options.headers);
@@ -53,6 +53,21 @@ function normalizeClientOptions(options) {
 function normalizeClientOptionsWithAuth(options) {
     var _a;
     const normalized = normalizeClientOptions(options);
+    if (options.auth === false) {
+        normalized.authProvider = new core.NoOpAuthProvider();
+        return normalized;
+    }
+    if (options.auth != null) {
+        if (typeof options.auth === "function") {
+            normalized.authProvider = { getAuthRequest: options.auth };
+            return normalized;
+        }
+        if (core.isAuthProvider(options.auth)) {
+            normalized.authProvider = options.auth;
+            return normalized;
+        }
+        Object.assign(normalized, options.auth);
+    }
     const normalizedWithNoOpAuthProvider = withNoOpAuthProvider(normalized);
     (_a = normalized.authProvider) !== null && _a !== void 0 ? _a : (normalized.authProvider = new HeaderAuthProvider_js_1.HeaderAuthProvider(normalizedWithNoOpAuthProvider));
     return normalized;

package/dist/cjs/api/resources/account/client/Client.d.ts

@@ -18,29 +18,28 @@ export declare class AccountClient {
      * - Check plan details (type, credits, expiration)
      * - Get relay information (for transactional emails)
      * - Check Marketing Automation status
-     * - View date/time preferences and account settings
      * - Access organization and user identifiers
      *
      * **Key information returned:**
      * - Complete account details (organization ID, user ID, company information)
      * - Address and contact information
      * - Plan configurations and credit allocations across different verticals
-     * - Marketing Automation settings and tracker key
+     * - Marketing Automation settings and tracker key (when enabled)
      * - SMTP relay configuration for transactional emails
-     * - Date/time preferences and account settings
      * - Enterprise features availability status
      *
      * **Important considerations:**
      * - Provides comprehensive account overview for billing and configuration management
      * - Essential for understanding current plan limitations and feature availability
-     * - Marketing Automation key required for advanced automation features
-     * - Plan verticals show detailed breakdown across Marketing, Chat, and CRM categories
+     * - Marketing Automation key is only returned when Marketing Automation is enabled on the account
+     * - Plan verticals show detailed breakdown across Marketing, Chat, and CRM categories (only returned when plan verticals are available)
      * - Relay configuration crucial for transactional email setup and deliverability
-     * - Date/time preferences affect campaign scheduling and reporting displays
      * - Enterprise status determines access to advanced features and sub-account management
      *
      * @param {AccountClient.RequestOptions} requestOptions - Request-specific configuration.
      *
+     * @throws {@link Brevo.BadRequestError}
+     *
      * @example
      *     await client.account.getAccount()
      */

package/dist/cjs/api/resources/account/client/Client.js

@@ -63,29 +63,28 @@ class AccountClient {
      * - Check plan details (type, credits, expiration)
      * - Get relay information (for transactional emails)
      * - Check Marketing Automation status
-     * - View date/time preferences and account settings
      * - Access organization and user identifiers
      *
      * **Key information returned:**
      * - Complete account details (organization ID, user ID, company information)
      * - Address and contact information
      * - Plan configurations and credit allocations across different verticals
-     * - Marketing Automation settings and tracker key
+     * - Marketing Automation settings and tracker key (when enabled)
      * - SMTP relay configuration for transactional emails
-     * - Date/time preferences and account settings
      * - Enterprise features availability status
      *
      * **Important considerations:**
      * - Provides comprehensive account overview for billing and configuration management
      * - Essential for understanding current plan limitations and feature availability
-     * - Marketing Automation key required for advanced automation features
-     * - Plan verticals show detailed breakdown across Marketing, Chat, and CRM categories
+     * - Marketing Automation key is only returned when Marketing Automation is enabled on the account
+     * - Plan verticals show detailed breakdown across Marketing, Chat, and CRM categories (only returned when plan verticals are available)
      * - Relay configuration crucial for transactional email setup and deliverability
-     * - Date/time preferences affect campaign scheduling and reporting displays
      * - Enterprise status determines access to advanced features and sub-account management
      *
      * @param {AccountClient.RequestOptions} requestOptions - Request-specific configuration.
      *
+     * @throws {@link Brevo.BadRequestError}
+     *
      * @example
      *     await client.account.getAccount()
      */
@@ -101,7 +100,7 @@ class AccountClient {
                 url: core.url.join((_c = (_b = (yield core.Supplier.get(this._options.baseUrl))) !== null && _b !== void 0 ? _b : (yield core.Supplier.get(this._options.environment))) !== null && _c !== void 0 ? _c : environments.BrevoEnvironment.Default, "account"),
                 method: "GET",
                 headers: _headers,
-                queryParameters: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams,
+                queryString: core.url.queryBuilder().mergeAdditional(requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams).build(),
                 timeoutMs: ((_f = (_d = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _d !== void 0 ? _d : (_e = this._options) === null || _e === void 0 ? void 0 : _e.timeoutInSeconds) !== null && _f !== void 0 ? _f : 60) * 1000,
                 maxRetries: (_g = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries) !== null && _g !== void 0 ? _g : (_h = this._options) === null || _h === void 0 ? void 0 : _h.maxRetries,
                 abortSignal: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.abortSignal,
@@ -112,11 +111,16 @@ class AccountClient {
                 return { data: _response.body, rawResponse: _response.rawResponse };
             }
             if (_response.error.reason === "status-code") {
-                throw new errors.BrevoError({
-                    statusCode: _response.error.statusCode,
-                    body: _response.error.body,
-                    rawResponse: _response.rawResponse,
-                });
+                switch (_response.error.statusCode) {
+                    case 400:
+                        throw new Brevo.BadRequestError(_response.error.body, _response.rawResponse);
+                    default:
+                        throw new errors.BrevoError({
+                            statusCode: _response.error.statusCode,
+                            body: _response.error.body,
+                            rawResponse: _response.rawResponse,
+                        });
+                }
             }
             return (0, handleNonStatusCodeError_js_1.handleNonStatusCodeError)(_response.error, _response.rawResponse, "GET", "/account");
         });
@@ -168,7 +172,11 @@ class AccountClient {
                 url: core.url.join((_c = (_b = (yield core.Supplier.get(this._options.baseUrl))) !== null && _b !== void 0 ? _b : (yield core.Supplier.get(this._options.environment))) !== null && _c !== void 0 ? _c : environments.BrevoEnvironment.Default, "organization/activities"),
                 method: "GET",
                 headers: _headers,
-                queryParameters: Object.assign(Object.assign({}, _queryParams), requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams),
+                queryString: core.url
+                    .queryBuilder()
+                    .addMany(_queryParams)
+                    .mergeAdditional(requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.queryParams)
+                    .build(),
                 timeoutMs: ((_f = (_d = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.timeoutInSeconds) !== null && _d !== void 0 ? _d : (_e = this._options) === null || _e === void 0 ? void 0 : _e.timeoutInSeconds) !== null && _f !== void 0 ? _f : 60) * 1000,
                 maxRetries: (_g = requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.maxRetries) !== null && _g !== void 0 ? _g : (_h = this._options) === null || _h === void 0 ? void 0 : _h.maxRetries,
                 abortSignal: requestOptions === null || requestOptions === void 0 ? void 0 : requestOptions.abortSignal,

package/dist/cjs/api/resources/account/types/GetAccountResponse.d.ts

@@ -14,9 +14,7 @@ export interface GetAccountResponse {
     /** Last Name */
     lastName: string;
     /** Address informations */
-    address: GetAccountResponse.Address;
-    /** User's date and time preferences */
-    dateTimePreferences: GetAccountResponse.DateTimePreferences;
+    address?: GetAccountResponse.Address | undefined;
     marketingAutomation?: GetAccountResponse.MarketingAutomation | undefined;
     /** Information about your plans and credits */
     plan: GetAccountResponse.Plan.Item[];
@@ -39,17 +37,6 @@ export declare namespace GetAccountResponse {
         /** Zip Code information */
         zipCode: string;
     }
-    /**
-     * User's date and time preferences
-     */
-    interface DateTimePreferences {
-        /** User's timezone setting */
-        timezone: string;
-        /** Preferred time format (12 or 24 hour) */
-        timeFormat: string;
-        /** Preferred date format */
-        dateFormat: string;
-    }
     interface MarketingAutomation {
         /**
          * Status of Marketing Automation Plateform activation
@@ -107,11 +94,11 @@ export declare namespace GetAccountResponse {
             /** Current status of the plan */
             status: Item.Status;
             /** Plan start date (Unix timestamp) */
-            startDate: string;
+            startDate?: string | undefined;
             /** Plan end date (Unix timestamp) */
-            endDate: string;
+            endDate?: string | undefined;
             /** User seat information for the plan */
-            users: Item.Users | null;
+            users?: (Item.Users | null) | undefined;
             /** Credits allocated for this plan category (optional, may not be present for all plan categories) */
             credits?: string | undefined;
         }

package/dist/cjs/api/resources/balance/client/Client.d.ts

@@ -25,11 +25,11 @@ export declare class BalanceClient {
      * @example
      *     await client.balance.getActiveBalancesApi({
      *         pid: "pid",
-     *         contact_id: 1,
-     *         balance_definition_id: "balance_definition_id"
+     *         contactId: 1000000,
+     *         balanceDefinitionId: "balanceDefinitionId"
      *     })
      */
-    getActiveBalancesApi(request: Brevo.GetLoyaltyBalanceProgramsPidActiveBalanceRequest, requestOptions?: BalanceClient.RequestOptions): core.HttpResponsePromise<Brevo.BalanceLimit>;
+    getActiveBalancesApi(request: Brevo.GetLoyaltyBalanceProgramsPidActiveBalanceRequest, requestOptions?: BalanceClient.RequestOptions): core.HttpResponsePromise<Brevo.GetLoyaltyBalanceProgramsPidActiveBalanceResponse>;
     private __getActiveBalancesApi;
     /**
      * Returns balance definition page
@@ -227,7 +227,7 @@ export declare class BalanceClient {
     deleteBalanceLimit(request: Brevo.DeleteBalanceLimitRequest, requestOptions?: BalanceClient.RequestOptions): core.HttpResponsePromise<void>;
     private __deleteBalanceLimit;
     /**
-     * Returns balance list
+     * Returns contact balances for a given balance definition across all subscriptions.
      *
      * @param {Brevo.GetContactBalancesRequest} request
      * @param {BalanceClient.RequestOptions} requestOptions - Request-specific configuration.
@@ -240,7 +240,8 @@ export declare class BalanceClient {
      *
      * @example
      *     await client.balance.getContactBalances({
-     *         pid: "pid"
+     *         pid: "pid",
+     *         balanceDefinitionId: "balanceDefinitionId"
      *     })
      */
     getContactBalances(request: Brevo.GetContactBalancesRequest, requestOptions?: BalanceClient.RequestOptions): core.HttpResponsePromise<Brevo.GetContactBalancesResponse>;
@@ -263,7 +264,7 @@ export declare class BalanceClient {
      *         balanceDefinitionId: "balanceDefinitionId",
      *         contactId: 1,
      *         dueAt: "dueAt",
-     *         source: "source"
+     *         source: "engine"
      *     })
      */
     createBalanceOrder(request: Brevo.CreateBalanceOrderRequest, requestOptions?: BalanceClient.RequestOptions): core.HttpResponsePromise<Brevo.CreateBalanceOrderResponse>;
@@ -324,7 +325,7 @@ export declare class BalanceClient {
      * @example
      *     await client.balance.getTransactionHistoryApi({
      *         pid: "pid",
-     *         contactId: 1,
+     *         contactId: 1000000,
      *         balanceDefinitionId: "balanceDefinitionId"
      *     })
      */