@getbrevo/brevo 2.5.0 → 3.0.2

package/README.md

@@ -1,156 +1,427 @@
-# Brevo typescript
+# Brevo Node.js SDK
+![](banner.png)
 
-Brevo's API v3 TypeScript-Node Library
+[![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github&utm_medium=github&utm_campaign=readme&utm_source=https%3A%2F%2Fgithub.com%2Fmourraille%2Fdemo-ts)
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+[![npm version](https://img.shields.io/npm/v/@getbrevo/brevo)](https://www.npmjs.com/package/@getbrevo/brevo)
+[![npm downloads](https://img.shields.io/npm/dm/@getbrevo/brevo)](https://www.npmjs.com/package/@getbrevo/brevo)
 
-Brevo's API exposes the entire Brevo features via a standardized programmatic interface. Please refer to the full [documentation](https://developers.brevo.com) to learn more.
+[Website](https://brevo.com) • [API Reference](https://developers.brevo.com) • [Support](mailto:support@brevo.com)
 
-This is the wrapper for the API. It implements all the features of the API v3. It supports promises.
-
-Brevo's API matches the [OpenAPI v2 definition](https://www.openapis.org/). The specification can be downloaded [here](https://api.brevo.com/v3/swagger_definition_v3.yml).
+---
 
 ## Installation
 
-### For [Node.js](https://nodejs.org/)
+```bash
+npm install getbrevo/brevo@^4.0.0
+```
+
+## Quick Start
+
+```typescript
+import { BrevoClient } from 'getbrevo/brevo@^4.0.0';
+
+const brevo = new BrevoClient({
+  apiKey: 'your-api-key',
+});
+
+const result = await brevo.transactionalEmails.sendTransacEmail({
+  subject: "Hello",
+  textContent: "Hello world!",
+  sender: { name: "Sender", email: "sender@example.com" },
+  to: [{ email: "recipient@example.com" }]
+});
 
-#### npm
+console.log('Email sent:', result);
+```
 
-The following recommended installation requires [npm](https://npmjs.org/). If you are unfamiliar with npm, see the [npm docs](https://npmjs.org/doc/).
+---
 
-Then install it via:
+## Configuration
 
-```shell
-npm i @getbrevo/brevo --save
-# or
-yarn add @getbrevo/brevo
+```typescript
+const brevo = new BrevoClient({
+  apiKey: 'your-api-key',
+  timeout: 30000,      // 30 seconds
+  maxRetries: 3        // Default: 2
+});
 ```
 
-## Getting Started
+---
+
+## Error Handling
 
+The SDK throws specific error types based on HTTP status codes.
 
+```typescript
+import { BrevoError, UnauthorizedError, TooManyRequestsError } from 'getbrevo/brevo@^4.0.0';
 
-# We have two options:
-- First example is where **typescript is not supported** i.e. [v1.0.1]([url](https://www.npmjs.com/package/@getbrevo/brevo/v/1.0.1))
-- Second example is where **typescript is supported** i.e. [v2.1.1]([url](https://www.npmjs.com/package/@getbrevo/brevo/v/2.1.1))
+try {
+  await brevo.transactionalEmails.sendTransacEmail({...});
+} catch (err) {
+  if (err instanceof UnauthorizedError) {
+    console.error('Invalid API key');
+  } else if (err instanceof TooManyRequestsError) {
+    const retryAfter = err.rawResponse.headers['retry-after'];
+    console.error(`Rate limited. Retry after ${retryAfter} seconds`);
+  } else if (err instanceof BrevoError) {
+    console.error(`API Error ${err.statusCode}:`, err.message);
+  }
+}
+```
 
+**Error Types:**
+- `400` - `BadRequestError`
+- `401` - `UnauthorizedError`
+- `403` - `ForbiddenError`
+- `404` - `NotFoundError`
+- `422` - `UnprocessableEntityError`
+- `429` - `TooManyRequestsError`
+- `500+` - `InternalServerError`
 
-```shell
--------------------------------------------------------------------------------------------------------------------------
-----------------------------------------------   Typescript not supported v1.0.1  ---------------------------------------
--------------------------------------------------------------------------------------------------------------------------
-const brevo = require('@getbrevo/brevo');
-let defaultClient = brevo.ApiClient.instance;
+<details>
+<summary>Error properties</summary>
 
-let apiKey = defaultClient.authentications['api-key'];
-apiKey.apiKey = 'YOUR API KEY';
+All `BrevoError` instances provide:
+- `statusCode`: HTTP status code
+- `message`: Error message
+- `body`: Parsed error response body
+- `rawResponse`: Raw response with headers
 
-let apiInstance = new brevo.TransactionalEmailsApi();
-let sendSmtpEmail = new brevo.SendSmtpEmail();
+</details>
 
-sendSmtpEmail.subject = "My {{params.subject}}";
-sendSmtpEmail.htmlContent = "<html><body><h1>Common: This is my first transactional email {{params.parameter}}</h1></body></html>";
-sendSmtpEmail.sender = { "name": "John", "email": "example@example.com" };
-sendSmtpEmail.to = [
-  { "email": "example@brevo.com", "name": "sample-name" }
-];
-sendSmtpEmail.replyTo = { "email": "example@brevo.com", "name": "sample-name" };
-sendSmtpEmail.headers = { "Some-Custom-Name": "unique-id-1234" };
-sendSmtpEmail.params = { "parameter": "My param value", "subject": "common subject" };
+---
 
+## Retries
 
-apiInstance.sendTransacEmail(sendSmtpEmail).then(function (data) {
-  console.log('API called successfully. Returned data: ' + JSON.stringify(data));
-}, function (error) {
-  console.error(error);
+Automatic retries with exponential backoff are enabled by default (2 retries).
+
+```typescript
+// Client-level
+const brevo = new BrevoClient({
+  apiKey: 'your-api-key',
+  maxRetries: 3
 });
 
+// Request-level
+await brevo.transactionalEmails.sendTransacEmail({...}, {
+  maxRetries: 5
+});
 ```
--------------------------------------------------------------------------------------------------------------------------
-## Typescript supported with version v2.1.1
 
-```shell
--------------------------------------------------------------------------------------------------------------------------
-----------------------------------------------   Typescript supported with v2.1.1  --------------------------------------
--------------------------------------------------------------------------------------------------------------------------
-const brevo = require('@getbrevo/brevo');
-let apiInstance = new brevo.TransactionalEmailsApi();
+**Retryable status codes:** `408`, `429`, `500`, `502`, `503`, `504`
+
+<details>
+<summary>How retries work</summary>
 
-let apiKey = apiInstance.authentications['api-key'];
-apiKey.apiKey = 'YOUR API KEY';
+- Exponential backoff: ~1s, ~2s, ~4s (with jitter)
+- Respects `Retry-After` header for rate limits
+- Can be disabled per request with `maxRetries: 0`
 
-let sendSmtpEmail = new brevo.SendSmtpEmail();
+</details>
 
-sendSmtpEmail.subject = "My {{params.subject}}";
-sendSmtpEmail.htmlContent = "<html><body><h1>Common: This is my first transactional email {{params.parameter}}</h1></body></html>";
-sendSmtpEmail.sender = { "name": "John", "email": "shubham.upadhyay@sendinblue.com" };
-sendSmtpEmail.to = [
-  { "email": "shubham.upadhyay@sendinblue.com", "name": "shubham upadhyay" }
-];
-sendSmtpEmail.replyTo = { "email": "shubham.upadhyay@sendinblue.com", "name": "Shubham Upadhyay" };
-sendSmtpEmail.headers = { "Some-Custom-Name": "unique-id-1234" };
-sendSmtpEmail.params = { "parameter": "My param value", "subject": "common subject" };
+---
 
+## Timeouts
 
-apiInstance.sendTransacEmail(sendSmtpEmail).then(function (data) {
-  console.log('API called successfully. Returned data: ' + JSON.stringify(data));
-}, function (error) {
-  console.error(error);
+Default timeout is 60 seconds. Configure at client or request level.
+
+```typescript
+// Client-level
+const brevo = new BrevoClient({
+  apiKey: 'your-api-key',
+  timeoutInSeconds: 30
 });
 
+// Request-level
+await brevo.transactionalEmails.sendTransacEmail({...}, {
+  timeoutInSeconds: 10
+});
 ```
--------------------------------------------------------------------------------------------------------------------------
-## Get Contact attributes API example:
 
-```shell
-const brevo = require('@getbrevo/brevo');
+**Recommended values:**
+- Standard API calls: `30-60s` (default)
+- Quick operations: `10-15s`
+- Bulk operations: `120-300s`
+- Real-time: `5-10s`
+
+---
+
+## Request Options
+
+### Additional Headers
+
+```typescript
+await brevo.transactionalEmails.sendTransacEmail({...}, {
+  headers: {
+    'X-Custom-Header': 'custom-value'
+  }
+});
+```
 
-let apiInstance = new brevo.ContactsApi()
+### Query Parameters
 
-let apiKey = apiInstance.authentications['api-key'];
-apiKey.apiKey = 'YOUR API KEY';
+```typescript
+await brevo.transactionalEmails.sendTransacEmail({...}, {
+  queryParams: {
+    'customParam': 'value'
+  }
+});
+```
 
-apiInstance.getAttributes().then(function(data) {
-  console.log('API called successfully. Returned data: ' + JSON.stringify(data));
+### Abort Signal
 
-}, function(error) {
-  console.error(error);
+```typescript
+const controller = new AbortController();
+await brevo.transactionalEmails.sendTransacEmail({...}, {
+  abortSignal: controller.signal
 });
+controller.abort();
+```
+
+### Raw Response
+
+```typescript
+const { data, rawResponse } = await brevo.transactionalEmails.sendTransacEmail({...})
+  .withRawResponse();
+
+console.log(rawResponse.headers['X-My-Header']);
+```
+
+---
+
+## Binary Responses
 
+```typescript
+const response = await brevo.inboundParsing.getInboundEmailAttachment(...);
+
+// Choose one:
+const stream = response.stream();
+// const arrayBuffer = await response.arrayBuffer();
+// const blob = await response.blob();
+// const bytes = await response.bytes();
 ```
--------------------------------------------------------------------------------------------------------------------------
-## Get Account API example:
 
-```shell
-const brevo = require('@getbrevo/brevo');
+<details>
+<summary>Save to file examples</summary>
+
+**Node.js (ReadableStream):**
+```typescript
+import { createWriteStream } from 'fs';
+import { Readable } from 'stream';
+import { pipeline } from 'stream/promises';
 
-let apiInstance = new brevo.AccountApi()
+const stream = response.stream();
+const nodeStream = Readable.fromWeb(stream);
+await pipeline(nodeStream, createWriteStream('path/to/file'));
+```
+
+**Bun:**
+```typescript
+await Bun.write('path/to/file', response.stream());
+```
+
+**Browser:**
+```typescript
+const blob = await response.blob();
+const url = URL.createObjectURL(blob);
+const a = document.createElement('a');
+a.href = url;
+a.download = 'filename';
+a.click();
+URL.revokeObjectURL(url);
+```
+
+</details>
+
+---
+
+## TypeScript Types
+
+All request and response types are exported.
+
+```typescript
+import { Brevo } from 'getbrevo/brevo@^4.0.0';
+
+const request: Brevo.SendTransacEmailRequest = {
+  subject: "First email",
+  textContent: "Hello world!",
+  sender: { name: "Bob Wilson", email: "bob.wilson@example.com" },
+  to: [{ email: "sarah.davis@example.com", name: "Sarah Davis" }]
+};
+```
 
-let apiKey = apiInstance.authentications['api-key'];
-apiKey.apiKey = 'YOUR API KEY';
+---
 
-apiInstance.getAccount().then(function(data) {
-  console.log('API called successfully. Returned data: ' + JSON.stringify(data));
+## Logging
 
-}, function(error) {
-  console.error(error);
+```typescript
+import { BrevoClient, logging } from 'getbrevo/brevo@^4.0.0';
+
+const brevo = new BrevoClient({
+  apiKey: 'your-api-key',
+  logging: {
+    level: logging.LogLevel.Debug,
+    logger: new logging.ConsoleLogger(),
+    silent: false
+  }
 });
+```
+
+<details>
+<summary>Custom logger example</summary>
 
+```typescript
+import winston from 'winston';
+
+const winstonLogger = winston.createLogger({...});
+
+const logger: logging.ILogger = {
+  debug: (msg, ...args) => winstonLogger.debug(msg, ...args),
+  info: (msg, ...args) => winstonLogger.info(msg, ...args),
+  warn: (msg, ...args) => winstonLogger.warn(msg, ...args),
+  error: (msg, ...args) => winstonLogger.error(msg, ...args),
+};
 ```
--------------------------------------------------------------------------------------------------------------------------
-## Get Contacts API example:
-```shell
-const brevo = require('@getbrevo/brevo');
 
-let apiInstance = new brevo.ContactsApi()
+</details>
+
+---
 
-let apiKey = apiInstance.authentications['api-key'];
-apiKey.apiKey = 'YOUR API KEY';
+## Custom Fetch Client
 
-apiInstance.getContacts().then(function(data) {
-  console.log('API called successfully. Returned data: ' + JSON.stringify(data));
+Override the default fetch implementation for advanced use cases.
 
-}, function(error) {
-  console.error(error);
+```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
+});
+```
+
+<details>
+<summary>Common use cases</summary>
+
+**Using node-fetch:**
+```typescript
+import fetch from 'node-fetch';
+const brevo = new BrevoClient({
+  apiKey: 'your-api-key',
+  fetcher: fetch as any
 });
 ```
 
-For more examples, refer the [Endpoints Guide](https://developers.brevo.com/reference)
+**Using undici:**
+```typescript
+import { fetch } from 'undici';
+const brevo = new BrevoClient({
+  apiKey: 'your-api-key',
+  fetcher: fetch as any
+});
+```
+
+**With interceptors:**
+```typescript
+const createFetcherWithInterceptors = () => {
+  return async (url: string, options?: RequestInit): Promise<Response> => {
+    const modifiedOptions = {
+      ...options,
+      headers: {
+        ...options?.headers,
+        'X-Request-ID': generateRequestId()
+      }
+    };
+    const response = await fetch(url, modifiedOptions);
+    console.log('Response:', response.status);
+    return response;
+  };
+};
+```
+
+</details>
+
+---
+
+## Runtime Compatibility
+
+- Node.js 18+
+- Vercel
+- Cloudflare Workers
+- Deno v1.25+
+- Bun 1.0+
+- React Native
+
+---
+
+## Migration from v3.x
+
+<details>
+<summary>View migration guide</summary>
+
+This version includes breaking changes:
+
+**Key Changes:**
+- New client initialization
+- Promise-based API
+- Improved TypeScript support
+- Standardized error handling
+
+**Example:**
+
+**v3.x:**
+```typescript
+import { TransactionalEmailsApi, SendSmtpEmail } from "@getbrevo/brevo";
+
+let emailAPI = new TransactionalEmailsApi();
+(emailAPI as any).authentications.apiKey.apiKey = "xkeysib-xxx";
+
+let message = new SendSmtpEmail();
+message.subject = "First email";
+message.textContent = "Hello world!";
+message.sender = { name: "Bob Wilson", email: "bob.wilson@example.com" };
+message.to = [{ email: "sarah.davis@example.com", name: "Sarah Davis" }];
+
+emailAPI.sendTransacEmail(message);
+```
+
+**v4.x:**
+```typescript
+import { BrevoClient } from 'getbrevo/brevo@^4.0.0';
+
+const brevo = new BrevoClient({
+  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" }]
+});
+```
+
+</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.
+
+---
+
+## Contributing
+
+This library is generated programmatically. Changes made directly to the library would be overwritten. Please open an issue first to discuss changes.
+
+Contributions to this README are always welcome!
+
+---
+
+## Support
+
+- [API Reference](https://developers.brevo.com)
+- [GitHub Issues](https://github.com/getbrevo/brevo-node/tree/main)
+- [Email Support](mailto:support@brevo.com)

package/dist/cjs/BaseClient.d.ts

@@ -0,0 +1,39 @@
+import { HeaderAuthProvider } from "./auth/HeaderAuthProvider.js";
+import * as core from "./core/index.js";
+import type * as environments from "./environments.js";
+export type BaseClientOptions = {
+    environment?: core.Supplier<environments.BrevoEnvironment | string>;
+    /** Specify a custom URL to connect the client to. */
+    baseUrl?: core.Supplier<string>;
+    /** Additional headers to include in requests. */
+    headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
+    /** The default maximum time to wait for a response in seconds. */
+    timeoutInSeconds?: number;
+    /** The default number of times to retry the request. Defaults to 2. */
+    maxRetries?: number;
+    /** Provide a custom fetch implementation. Useful for platforms that don't have a built-in fetch or need a custom implementation. */
+    fetch?: typeof fetch;
+    /** Configure logging for the client. */
+    logging?: core.logging.LogConfig | core.logging.Logger;
+} & HeaderAuthProvider.AuthOptions;
+export interface BaseRequestOptions {
+    /** The maximum time to wait for a response in seconds. */
+    timeoutInSeconds?: number;
+    /** The number of times to retry the request. Defaults to 2. */
+    maxRetries?: number;
+    /** A hook to abort the request. */
+    abortSignal?: AbortSignal;
+    /** Additional query string parameters to include in the request. */
+    queryParams?: Record<string, unknown>;
+    /** Additional headers to include in the request. */
+    headers?: Record<string, string | core.Supplier<string | null | undefined> | null | undefined>;
+}
+export type NormalizedClientOptions<T extends BaseClientOptions = BaseClientOptions> = T & {
+    logging: core.logging.Logger;
+    authProvider?: core.AuthProvider;
+};
+export type NormalizedClientOptionsWithAuth<T extends BaseClientOptions = BaseClientOptions> = NormalizedClientOptions<T> & {
+    authProvider: core.AuthProvider;
+};
+export declare function normalizeClientOptions<T extends BaseClientOptions = BaseClientOptions>(options: T): NormalizedClientOptions<T>;
+export declare function normalizeClientOptionsWithAuth<T extends BaseClientOptions = BaseClientOptions>(options: T): NormalizedClientOptionsWithAuth<T>;

package/dist/cjs/BaseClient.js

@@ -0,0 +1,62 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeClientOptions = normalizeClientOptions;
+exports.normalizeClientOptionsWithAuth = normalizeClientOptionsWithAuth;
+const HeaderAuthProvider_js_1 = require("./auth/HeaderAuthProvider.js");
+const headers_js_1 = require("./core/headers.js");
+const core = __importStar(require("./core/index.js"));
+function normalizeClientOptions(options) {
+    const headers = (0, headers_js_1.mergeHeaders)({
+        "X-Fern-Language": "JavaScript",
+        "X-Fern-SDK-Name": "@getbrevo/brevo",
+        "X-Fern-SDK-Version": "3.0.2",
+        "User-Agent": "@getbrevo/brevo/3.0.2",
+        "X-Fern-Runtime": core.RUNTIME.type,
+        "X-Fern-Runtime-Version": core.RUNTIME.version,
+    }, options === null || options === void 0 ? void 0 : options.headers);
+    return Object.assign(Object.assign({}, options), { logging: core.logging.createLogger(options === null || options === void 0 ? void 0 : options.logging), headers });
+}
+function normalizeClientOptionsWithAuth(options) {
+    var _a;
+    const normalized = normalizeClientOptions(options);
+    const normalizedWithNoOpAuthProvider = withNoOpAuthProvider(normalized);
+    (_a = normalized.authProvider) !== null && _a !== void 0 ? _a : (normalized.authProvider = new HeaderAuthProvider_js_1.HeaderAuthProvider(normalizedWithNoOpAuthProvider));
+    return normalized;
+}
+function withNoOpAuthProvider(options) {
+    return Object.assign(Object.assign({}, options), { authProvider: new core.NoOpAuthProvider() });
+}