mailgun.js 12.0.3 → 12.1.0

package/README.md

@@ -10,11 +10,14 @@ __Table of Contents__
   - [Install](#install)
   - [Setup Client](#setup-client)
     - [Available Imports](#imports)
-    - [Using Subaccounts](#using-subaccounts)
     - [Types imports](#types-imports)
     - [Interfaces and Enums imports](#interfaces-and-enums-imports)
+    - [Fetch API usage](#fetch-api-usage)
+    - [Proxy configuration](proxy-configuration)
+    - [SubAccounts](#using-subaccounts)
   - [Generated docs](#generated-docs)
   - [Methods](#methods)
+  - [Pagination](#pagination)
   - [Browser Demo](#browser-demo)
   - [Examples](https://github.com/mailgun/mailgun-js/tree/master/examples)
 - [Development](#development)
@@ -48,16 +51,14 @@ NOTE: starting from version 3.0 you need to pass FormData (we need this to keep
 Once the package is installed, you can import the library using `import` or `require` approach:
 
 ```js
-  const formData = require('form-data'); // or built-in FormData
   const Mailgun = require('mailgun.js');
-  const mailgun = new Mailgun(formData);
-  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
+  const mailgun = new Mailgun(FormData); // or const formData = require('form-data');
+  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-{yourkeyhere}'});
 ```
 ```js
-  import FormData from 'form-data'; // or built-in FormData
   import Mailgun from 'mailgun.js';
-  const mailgun = new Mailgun(FormData);
-  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
+  const mailgun = new Mailgun(FormData); // or import formData from 'form-data';
+  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-{yourkeyhere}'});
 ```
 
 Be aware that there are four bundles available for usage. All of them are conditionally exported by package.json and separated by environment (Browser/Node.js):
@@ -122,25 +123,50 @@ Be aware that there are four bundles available for usage. All of them are condit
       })
       </script>
       ```
-### Using Subaccounts
-Primary accounts can make API calls on behalf of their subaccounts. [API documentation](https://documentation.mailgun.com/en/latest/subaccounts.html#subaccounts)
-```js
-  import FormData from 'form-data'; // or built-in FormData
-  import Mailgun from 'mailgun.js';
-  const mailgun = new Mailgun(FormData);
-  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
-  mg.setSubaccount('subaccount-id');
-  // then, if you need to reset it back to the primary account:
-  mg.resetSubaccount();
+
+### Types imports
+Types defined by SDK can be imported from 'definitions' submodule:
+```TS
+ import { MailgunClientOptions, MessagesSendResult } from 'mailgun.js/definitions';
+```
+
+### Interfaces and Enums imports
+Interfaces and Enums defined by SDK can be imported from 'definitions' submodule:
+```TS
+  import { Interfaces, Enums } from 'mailgun.js/definitions';
+  ...
+  const mailgunClient: Interfaces.IMailgunClient = mailgun.client(clientOptions);
+  const yes = Enums.YesNo.YES;
+  ...
+```
+### Fetch API usage
+
+Starting from version `12.1.0`, the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) is available for use in environments that do not support `XMLHttpRequest`.
+
+The new `useFetch` configuration parameter is responsible for this.
+
+***Note that proxy configuration and the `form-data` NPM package are not supported in this case.***
+
+Example:
+
+```TS
+import Mailgun from 'mailgun.js';
+const mailgun = new Mailgun(FormData);
+
+const mg = mailgun.client({
+  username: 'api',
+  key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere',
+  useFetch: true,
+});
 ```
 
+
 ### Proxy configuration
 By leveraging client configuration options, users can effortlessly establish proxy connections that align with their network requirements.
-Ex:
+Example:
 ```js
-  import FormData from 'form-data'; // or built-in FormData
   import Mailgun from 'mailgun.js';
-  const mailgun = new Mailgun(FormData);
+  const mailgun = new Mailgun(FormData);// or import FormData from 'form-data';
 
   const mg = mailgun.client({
     username: 'api',
@@ -156,22 +182,21 @@ Ex:
     },
   });
 ```
-### Types imports
-Types defined by SDK can be imported from 'definitions' submodule:
-```TS
- import { MailgunClientOptions, MessagesSendResult } from 'mailgun.js/definitions';
-```
 
-### Interfaces and Enums imports
-Interfaces and Enums defined by SDK can be imported from 'definitions' submodule:
-```TS
-  import { Interfaces, Enums } from 'mailgun.js/definitions';
-  ...
-  const mailgunClient: Interfaces.IMailgunClient = mailgun.client(clientOptions);
-  const yes = Enums.YesNo.YES;
-  ...
+
+
+### SubAccounts Usage
+Primary accounts can make API calls on behalf of their subaccounts. [API documentation](https://documentation.mailgun.com/en/latest/subaccounts.html#subaccounts)
+```js
+  import Mailgun from 'mailgun.js';
+  const mailgun = new Mailgun(FormData); // or import FormData from 'form-data'
+  const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
+  mg.setSubaccount('subaccount-id');
+  // then, if you need to reset it back to the primary account:
+  mg.resetSubaccount();
 ```
 
+
 ### Generated docs
 The list of all available Types, Interfaces and Enums is auto-generated and located in the [docs](./docs/modules.md) folder.
 
@@ -4131,21 +4156,21 @@ A client to manage members within a specific mailing list.
     }
   }
 
-## Navigation thru lists
+## Pagination
   Most of the methods that return items in a list support pagination.
   There are two ways to receive part of the list:
-  1. Provide properties 'limit' and 'page' in the query.
+  1. Provide properties `limit` and `page` in the query.
   This way uses more frequently in the SDK and works for the next methods:
-  - mg.domains.domainTags.list()
-  - mg.domains.domainTemplates.list()
-  - mg.domains.domainTemplates.listVersions()
-  - mg.events.get()
-  - mg.lists.list()
-  - mg.lists.members.listMembers()
-  - mg.validate.list()
-  - mg.suppressions.list()
+  - `mg.domains.domainTags.list()`
+  - `mg.domains.domainTemplates.list()`
+  - `mg.domains.domainTemplates.listVersions()`
+  - `mg.events.get()`
+  - `mg.lists.list()`
+  - `mg.lists.members.listMembers()`
+  - `mg.validate.list()`
+  - `mg.suppressions.list()`
 
-    The general idea is that after you made the first call with a limit property in the query you will receive a response with a property called pages in it. This property implements the next interface:
+    The general idea is that after you made the first call with a limit property in the query you will receive a response with `pages` property in it. This property implements the next interface:
 
     ```TS
     {
@@ -4175,7 +4200,7 @@ A client to manage members within a specific mailing list.
         };
     }
     ```
-    To receive the next page you need to add the page property to the query argument. This property should contain a string value from 'page' property in response.pages.(previous/first/last/next).
+    To receive the next page you need to add the `page` property to the query argument. This property should contain a string value from `page` property in response.pages.(previous/first/last/next).
 
     Example:
     ```Js
@@ -4280,12 +4305,13 @@ A client to manage members within a specific mailing list.
     }
     */
     ```
-    2. The second option of navigation is to provide properties 'limit' and 'skip' in the query. This way uses only in a few places for now:
-      - mg.domains.list()
-      - mg.domains.domainCredentials.list()
-      - mg.routes.list()
-      - mg.webhooks.list()
-    The main idea here is quite simple you just need to provide how many records from the start of a list you want to skip and how many to receive. You can do it using the query parameter in each method.
+    2. The second option of navigation is to provide properties `limit` and `skip` in the query. Currently this way is being used only in a few places:
+      - `mg.domains.list()`
+      - `mg.domains.domainCredentials.list()`
+      - `mg.routes.list()`
+      - `mg.webhooks.list()`
+
+    The main idea here is quite simple, you just need to provide how many records from the start of a list you want to skip and how many to receive. You can do it with the query parameter in each method.
     Example:
     ```js
     const listDomainCredentials = await client.domains.domainCredentials.list(

package/Types/Classes/common/Error.d.ts

@@ -4,6 +4,7 @@ export default class APIError extends Error implements APIErrorType {
     stack: string;
     details: string;
     type: string;
+    static isApiError(err: unknown): err is APIError;
     static getUserDataError(statusText: string, message: string): APIError;
     constructor({ status, statusText, message, body }: APIErrorOptions);
 }

package/Types/Classes/common/FormDataBuilder.d.ts

@@ -1,12 +1,12 @@
-import * as NodeFormData from 'form-data';
-import { FormDataInput, InputFormData } from '../../Types/Common/index.js';
+import { FormDataInput, InputFormData, FormDataBuilderConfig, CreatedFormData } from '../../Types/Common/index.js';
 import { MimeMessage } from '../../Types/index.js';
 declare class FormDataBuilder {
     private FormDataConstructor;
     private fileKeys;
     private attachmentsHandler;
-    constructor(FormDataConstructor: InputFormData);
-    createFormData(data: FormDataInput): NodeFormData | FormData;
+    private useFetch?;
+    constructor(FormDataConstructor: InputFormData, config: FormDataBuilderConfig);
+    createFormData(data: FormDataInput): Promise<CreatedFormData>;
     private addMimeDataToFD;
     isMIME(data: unknown): data is MimeMessage;
     private isFormDataPackage;

package/Types/Classes/common/Request.d.ts

@@ -1,29 +1,24 @@
-import * as NodeFormData from 'form-data';
-import { RequestOptions, InputFormData, APIResponse, IpPoolDeleteData, FormDataInput } from '../../Types/index.js';
+import { RequestOptions, InputFormData, APIResponse, IpPoolDeleteData, FormDataInput, RequestData, GetQueryTypes, PostDataTypes, PutDataTypes, CommandQuery, PutOptionsType, PutQueryTypes, onCallReqConfig } from '../../Types/index.js';
+import { IRequestProvider } from '../../Interfaces/index.js';
 declare class Request {
-    private username;
-    private key;
     private url;
-    private timeout;
-    private headers;
     private formDataBuilder;
-    private maxBodyLength;
-    private proxy;
+    requestProvider: IRequestProvider;
     constructor(options: RequestOptions, formData: InputFormData);
-    request(method: string, url: string, onCallOptions?: Record<string, unknown | Record<string, unknown>>): Promise<APIResponse>;
-    private getResponseBody;
-    private joinAndTransformHeaders;
-    private makeHeadersFromObject;
-    setSubaccountHeader(subaccountId: string): void;
+    request(method: string, url: string, onCallOptions?: {
+        body?: RequestData;
+        query?: GetQueryTypes | PutQueryTypes;
+    }, config?: onCallReqConfig): Promise<APIResponse>;
+    setSubaccountHeader(subAccountId: string): void;
     resetSubaccountHeader(): void;
-    query(method: string, url: string, query?: Record<string, unknown> | Array<Array<string>>, options?: Record<string, unknown>): Promise<APIResponse>;
-    command(method: string, url: string, data?: Record<string, unknown> | Record<string, unknown>[] | string | NodeFormData | FormData, options?: Record<string, unknown>, addDefaultHeaders?: boolean): Promise<APIResponse>;
-    get(url: string, query?: Record<string, unknown> | Array<Array<string>>, options?: Record<string, unknown>): Promise<APIResponse>;
-    post(url: string, data?: Record<string, unknown> | string, options?: Record<string, unknown>): Promise<APIResponse>;
+    query(method: string, url: string, query?: GetQueryTypes): Promise<APIResponse>;
+    command(method: string, url: string, data?: RequestData, config?: onCallReqConfig, queryObject?: CommandQuery): Promise<APIResponse>;
+    get(url: string, query?: GetQueryTypes): Promise<APIResponse>;
+    post(url: string, data?: PostDataTypes, config?: Omit<onCallReqConfig, 'isFormURLEncoded' | 'isMultipartFormData'>): Promise<APIResponse>;
     postWithFD(url: string, data: FormDataInput): Promise<APIResponse>;
     putWithFD(url: string, data: FormDataInput): Promise<APIResponse>;
     patchWithFD(url: string, data: FormDataInput): Promise<APIResponse>;
-    put(url: string, data?: FormDataInput | string, options?: Record<string, unknown>): Promise<APIResponse>;
+    put(url: string, data?: PutDataTypes, queryObject?: PutOptionsType): Promise<APIResponse>;
     delete(url: string, data?: IpPoolDeleteData): Promise<APIResponse>;
 }
 export default Request;

package/Types/Classes/common/RequestProviders/AxiosProvider.d.ts

@@ -0,0 +1,20 @@
+import { APIResponse, onCallReqConfig, RequestProviderConfig, RequestProviderData } from '../../../Types/index.js';
+import { IRequestProvider } from '../../../Interfaces/index.js';
+declare class AxiosProvider implements IRequestProvider {
+    private timeout;
+    private maxBodyLength;
+    private proxy;
+    private username;
+    private key;
+    private headers;
+    private useFetch;
+    constructor({ username, key, timeout, maxBodyLength, proxy, configHeaders, useFetch }: RequestProviderConfig);
+    private getResponseBody;
+    private getDataRelatedHeaders;
+    private addRequestLevelHeaders;
+    private makeHeadersFromObject;
+    setSubAccountHeader(subAccountId: string): void;
+    resetSubAccountHeader(): void;
+    makeRequest(url: string, method: string, data: RequestProviderData, config?: onCallReqConfig): Promise<APIResponse>;
+}
+export default AxiosProvider;

package/Types/Interfaces/Common/RequestProviders/RequestProvider.d.ts

@@ -0,0 +1,6 @@
+import { APIResponse, onCallReqConfig, RequestData } from '../../../Types/index.js';
+export interface IRequestProvider {
+    makeRequest(url: string, method: string, data: RequestData, config?: onCallReqConfig): Promise<APIResponse>;
+    setSubAccountHeader(subAccountId: string): void;
+    resetSubAccountHeader(): void;
+}

package/Types/Interfaces/Common/index.d.ts

@@ -1 +1,2 @@
 export * from './Logger.js';
+export * from './RequestProviders/RequestProvider.js';

package/Types/Interfaces/Domains/DomainTemplates.d.ts

@@ -1,4 +1,4 @@
-import type { CreateDomainTemplateVersionResult, DomainTemplateData, DomainTemplatesQuery, DomainTemplateUpdateData, DomainTemplateUpdateVersionData, DomainTemplateVersionData, ListDomainTemplatesResult, ListDomainTemplateVersionsResult, MutateDomainTemplateVersionResult, NotificationResult, ShortTemplateVersion, TemplateQuery, TemplateVersion, UpdateOrDeleteDomainTemplateResult } from '../../Types/Domains/index.js';
+import type { CreateDomainTemplateVersionResult, DomainTemplateData, DomainTemplatesQuery, DomainTemplateUpdateData, DomainTemplateUpdateVersionData, DomainTemplateVersionData, ListDomainTemplatesResult, ListDomainTemplateVersionsResult, MutateDomainTemplateVersionResult, NotificationResult, ShortTemplateVersion, TemplateQuery, TemplateVersion, UpdateOrDeleteDomainTemplateResult } from '../../Types/Domains/DomainTemplates.js';
 export interface IDomainTemplate {
     name: string;
     description: string;

package/Types/Types/Common/FormData.d.ts

@@ -11,3 +11,10 @@ export type InputFormData = {
 export type FormDataInput = {
     [key: string]: FormDataInputValue;
 };
+export type FormDataBuilderConfig = {
+    useFetch?: boolean;
+};
+export type CreatedFormData = {
+    dataSize?: number;
+    formData: NodeFormData | FormData;
+};

package/Types/Types/Common/RequestOptions.d.ts

@@ -1,15 +1,59 @@
-import { AxiosRequestHeaders, RawAxiosRequestHeaders } from 'axios';
-import { MailgunClientOptions } from '../MailgunClient/index.js';
+import * as NodeFormData from 'form-data';
+import type { MailgunClientOptions } from '../MailgunClient/index.js';
+import type { IPsListQuery } from '../IPs/index.js';
+import type { RoutesListQuery } from '../Routes/index.js';
+import type { SubaccountsQuery } from '../Subaccounts/index.js';
+import type { WebhooksQuery } from '../Webhooks/index.js';
+import type { ConnectionSettings, DomainCredentialsQuery, DomainGetAPIQuery, DomainsQuery, DomainTagsStatisticQuery, DomainTemplatesQuery, TemplateQuery } from '../Domains/index.js';
+import type { InboxPlacementsData, InboxPlacementsResultsApiQuery, SeedsListsAPIQuery, SeedsListsUpdatingData } from '../InboxPlacements/index.js';
+import type { ValidationQuery } from '../Validations/index.js';
+import type { IpPoolDeleteData } from '../IPPools/index.js';
+import type { MetricsQuery } from '../Metrics/index.js';
+import type { FormDataInput } from './FormData.js';
 export type OnCallEmptyHeaders = {
     [key: string]: undefined;
 };
+type HeaderValue = string | string[] | number | boolean | null;
+type CommonRequestHeadersList = 'Accept' | 'Content-Length' | 'User-Agent' | 'Content-Encoding' | 'Authorization';
+type ContentType = HeaderValue | 'text/html' | 'text/plain' | 'multipart/form-data' | 'application/json' | 'application/x-www-form-urlencoded' | 'application/octet-stream';
+export type RequestHeaders = Partial<{
+    [key: string]: HeaderValue;
+} & {
+    [Key in CommonRequestHeadersList]: HeaderValue;
+} & {
+    'Content-Type': ContentType;
+}>;
 export type RequestOptions = MailgunClientOptions & {
-    headers: AxiosRequestHeaders | RawAxiosRequestHeaders;
-    timeout: number;
+    headers?: RequestHeaders;
+    timeout?: number;
 };
 export type OnCallRequestOptions = {
     timeout?: number;
-    headers?: AxiosRequestHeaders | RawAxiosRequestHeaders;
     query?: any;
     [key: string]: unknown | undefined;
 };
+export type GetQueryTypes = IPsListQuery | RoutesListQuery | SubaccountsQuery | WebhooksQuery | DomainsQuery | DomainGetAPIQuery | DomainCredentialsQuery | DomainTagsStatisticQuery | TemplateQuery | DomainTemplatesQuery | InboxPlacementsResultsApiQuery | SeedsListsAPIQuery | {
+    searchParams?: Array<Array<string>>;
+} | ValidationQuery;
+export type PostDataTypes = InboxPlacementsData | MetricsQuery | string;
+export type PutDataTypes = SeedsListsUpdatingData | object | FormDataInput | ConnectionSettings;
+export type RequestData = IpPoolDeleteData | PostDataTypes | PutDataTypes | NodeFormData | FormData;
+export type ContainsPrefix<T extends string> = `${T}${string}`;
+type EnableQuery = ContainsPrefix<'enabled='>;
+type DkimSelectorQuery = ContainsPrefix<'dkim_selector='>;
+type SelfQuery = ContainsPrefix<'self='>;
+type WebPrefixQuery = ContainsPrefix<'web_prefix='>;
+export type PutQueryTypes = EnableQuery | DkimSelectorQuery | SelfQuery | WebPrefixQuery;
+export type PutOptionsType = {
+    query?: PutQueryTypes;
+};
+export type CommandQuery = {
+    query?: PutQueryTypes;
+};
+export type onCallReqConfig = {
+    isFormURLEncoded?: boolean;
+    isMultipartFormData?: boolean;
+    isApplicationJSON?: boolean;
+    dataSize?: number;
+};
+export {};

package/Types/Types/Common/RequestProvider.d.ts

@@ -0,0 +1,30 @@
+import type { RequestData, RequestHeaders } from './index.js';
+export type ClientProxyConfig = {
+    host: string;
+    port: number;
+    auth?: {
+        username: string;
+        password: string;
+    };
+    protocol?: string;
+};
+export type RequestProviderConfig = {
+    username: string;
+    key: string;
+    timeout?: number;
+    maxBodyLength: number;
+    proxy?: ClientProxyConfig;
+    configHeaders?: RequestHeaders;
+    useFetch?: boolean;
+};
+export type RequestProviderData = {
+    params?: URLSearchParams;
+    data?: RequestData;
+};
+export type FetchSupportedData = Blob | BufferSource | FormData | URLSearchParams | string;
+export type KeysWithToArray = {
+    toArray: () => string[];
+};
+export type HeadersWithKeysMethod = Headers & {
+    keys: () => KeysWithToArray;
+};

package/Types/Types/Common/index.d.ts

@@ -4,3 +4,4 @@ export * from './Error.js';
 export * from './FormData.js';
 export * from './NavigationThruPages.js';
 export * from './RequestOptions.js';
+export * from './RequestProvider.js';

package/Types/Types/Domains/Domains.d.ts

@@ -175,3 +175,7 @@ export type DomainGetQuery = {
     extended?: boolean;
     with_dns?: boolean;
 };
+export type DomainGetAPIQuery = {
+    'h:extended'?: boolean;
+    'h:with_dns'?: boolean;
+};

package/Types/Types/MailgunClient/MailgunClientOptions.d.ts

@@ -1,9 +1,10 @@
-import { AxiosProxyConfig } from 'axios';
+import type { ClientProxyConfig } from '../Common/index.js';
 export type MailgunClientOptions = {
     username: string;
     key: string;
     url?: string;
     public_key?: string;
     timeout?: number;
-    proxy?: AxiosProxyConfig;
+    proxy?: ClientProxyConfig;
+    useFetch?: boolean;
 };