mailgun.js 10.0.1 → 10.2.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [10.2.0](https://github.com/mailgun/mailgun.js/compare/v10.1.0...v10.2.0) (2024-02-15)
+
+
+### Features
+
+* Better types and handling for different FormData implementations ([c547be9](https://github.com/mailgun/mailgun.js/commits/c547be9895dc1fcfb625ddf0aadc82778e82a259))
+
+## [10.1.0](https://github.com/mailgun/mailgun.js/compare/v10.0.1...v10.1.0) (2024-01-31)
+
+
+### Features
+
+* Add proxy configuration to the client ([fa013f1](https://github.com/mailgun/mailgun.js/commits/fa013f1f49792d1e42b4e718b629514198393f4e))
+
+
+### Bug Fixes
+
+* **docs:** Add url param for EU infrastructure ([360b867](https://github.com/mailgun/mailgun.js/commits/360b867c03da6f70669e6bba0c3070fdd9f10885))
+
+
+### Other changes
+
+* Update readme ([3897e59](https://github.com/mailgun/mailgun.js/commits/3897e59554316994579960eb5f3ee7373b72f29d))
+
 ### [10.0.1](https://github.com/mailgun/mailgun.js/compare/v10.0.0...v10.0.1) (2024-01-26)
 
 

package/Classes/Validations/multipleValidation.d.ts

@@ -32,11 +32,13 @@ export declare class MultipleValidationJob implements MultipleValidationJobResul
 }
 export default class MultipleValidationClient extends NavigationThruPages<MultipleValidationJobsListResult> implements IMultipleValidationClient {
     request: Request;
+    private attachmentsHandler;
     constructor(request: Request);
     private handleResponse;
     protected parseList(response: MultipleValidationJobsListResponse): MultipleValidationJobsListResult;
     list(query?: MultipleValidationJobsListQuery): Promise<MultipleValidationJobsListResult>;
     get(listId: string): Promise<MultipleValidationJob>;
+    private convertToExpectedShape;
     create(listId: string, data: MultipleValidationCreationData): Promise<CreatedMultipleValidationJob>;
     destroy(listId: string): Promise<CanceledMultipleValidationJob>;
 }

package/Classes/common/AttachmentsHandler.d.ts

@@ -0,0 +1,27 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import { Readable } from 'stream';
+import { CustomFile, CustomFileData } from '../../Types';
+import { AttachmentInfo, StreamValue } from '../../Types/Common/Attachments';
+declare class BlobFromStream {
+    private _stream;
+    size: number;
+    constructor(stream: Readable, size: number);
+    stream(): Readable;
+    get [Symbol.toStringTag](): string;
+}
+declare class AttachmentsHandler {
+    private getAttachmentOptions;
+    private getFileInfo;
+    private getCustomFileInfo;
+    private getBufferInfo;
+    isStream(data: unknown): data is StreamValue;
+    isCustomFile(obj: unknown): obj is CustomFile;
+    isBrowserFile(obj: unknown): obj is File;
+    isBuffer(data: unknown): data is Buffer;
+    getAttachmentInfo(attachment: CustomFile | File | string | CustomFileData): AttachmentInfo;
+    convertToFDexpectedShape(userProvidedValue: CustomFile | File | string | CustomFileData): string | Blob | Buffer | NodeJS.ReadableStream | (CustomFile & StreamValue);
+    getBlobFromStream(stream: Readable, size: number): BlobFromStream;
+}
+export default AttachmentsHandler;

package/Classes/common/Error.d.ts

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

package/Classes/common/FormDataBuilder.d.ts

@@ -1,14 +1,17 @@
 import * as NodeFormData from 'form-data';
-import { InputFormData } from '../../Types/Common';
+import { FormDataInput, InputFormData } from '../../Types/Common';
+import { MimeMessage } from '../../Types';
 declare class FormDataBuilder {
     private FormDataConstructor;
+    private fileKeys;
+    private attachmentsHandler;
     constructor(FormDataConstructor: InputFormData);
-    createFormData(data: any): NodeFormData | FormData;
-    private isFormDataPackage;
-    private getAttachmentOptions;
+    createFormData(data: FormDataInput): NodeFormData | FormData;
     private addMimeDataToFD;
+    isMIME(data: unknown): data is MimeMessage;
+    private isFormDataPackage;
+    private isMessageAttachment;
     private addFilesToFD;
-    private isStream;
     private addCommonPropertyToFD;
 }
 export default FormDataBuilder;

package/Classes/common/Request.d.ts

@@ -1,5 +1,5 @@
 import * as NodeFormData from 'form-data';
-import { RequestOptions, InputFormData, APIResponse, IpPoolDeleteData } from '../../Types';
+import { RequestOptions, InputFormData, APIResponse, IpPoolDeleteData, FormDataInput } from '../../Types';
 declare class Request {
     private username;
     private key;
@@ -8,6 +8,7 @@ declare class Request {
     private headers;
     private formDataBuilder;
     private maxBodyLength;
+    private proxy;
     constructor(options: RequestOptions, formData: InputFormData);
     request(method: string, url: string, onCallOptions?: Record<string, unknown | Record<string, unknown>>): Promise<APIResponse>;
     private getResponseBody;
@@ -19,10 +20,10 @@ declare class Request {
     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>;
-    postWithFD(url: string, data: Record<string, unknown> | Record<string, unknown>[]): Promise<APIResponse>;
-    putWithFD(url: string, data: Record<string, unknown>): Promise<APIResponse>;
-    patchWithFD(url: string, data: Record<string, unknown>): Promise<APIResponse>;
-    put(url: string, data?: Record<string, unknown> | string, options?: Record<string, unknown>): 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>;
     delete(url: string, data?: IpPoolDeleteData): Promise<APIResponse>;
 }
 export default Request;

package/README.md

@@ -42,6 +42,8 @@ Next, require the module and instantiate a mailgun client by calling `new Mailgu
 
 NOTE: starting from version 3.0 you need to pass FormData (we need this to keep library universal). For node.js you can use `form-data` library.
 
+IMPORTANT: if you are using EU infrastructure, you need to also pass `url: 'https://api.eu.mailgun.net'` together with auth credentials as stated in [Mailgun docs](https://documentation.mailgun.com/en/latest/quickstart-sending.html#send-via-api)
+
 ### Imports
 Once the package is installed, you can import the library using `import` or `require` approach:
 
@@ -68,6 +70,29 @@ Primary accounts can make API calls on behalf of their subaccounts. [API documen
   // then, if you need to reset it back to the primary account:
   mg.resetSubaccount();
 ```
+
+### Proxy configuration
+By leveraging client configuration options, users can effortlessly establish proxy connections that align with their network requirements.
+Ex:
+```js
+  import * as FormData from 'form-data';
+  import Mailgun from 'mailgun.js';
+  const mailgun = new Mailgun(FormData);
+
+  const mg = mailgun.client({
+    username: 'api',
+    key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere',
+    proxy: {
+      protocol: 'https' // 'http' ,
+      host: '127.0.0.1', // use your proxy host here
+      port: 9000, // use your proxy port here
+      auth: { // may be omitted if proxy doesn't require authentication
+        username: 'user_name', // provide username
+        password: 'user_password' // provide password
+      }
+    },
+  });
+```
 ### Types imports
 Starting from version **9.0.0.** Types can be includes as named import:
 ```TS

package/Types/Common/Attachments.d.ts

@@ -0,0 +1,12 @@
+export type NodePipeFunction = (destination: WritableStream, options?: {
+    end?: boolean;
+}) => void;
+export type BrowserPipeFunction = (destination: WritableStream) => void;
+export type StreamValue = {
+    pipe: NodePipeFunction | BrowserPipeFunction;
+};
+export type AttachmentInfo = {
+    filename?: string;
+    contentType?: string;
+    knownLength?: number;
+};

package/Types/Common/FormData.d.ts

@@ -1,7 +1,13 @@
 import * as NodeFormData from 'form-data';
+import { FormDataInputValue } from '../Messages';
 export type FormDataOptions = {
-    [key: string]: any;
+    [key: string]: NodeFormData;
 };
 export type InputFormData = {
-    new (options?: HTMLFormElement | FormDataOptions): NodeFormData | FormData;
+    new (form?: HTMLFormElement | undefined, submitter?: HTMLElement | null | undefined): FormData;
+} | {
+    new (options?: FormDataOptions): NodeFormData;
+};
+export type FormDataInput = {
+    [key: string]: FormDataInputValue;
 };

package/Types/MailgunClient/MailgunClientOptions.d.ts

@@ -1,7 +1,9 @@
+import { AxiosProxyConfig } from 'axios';
 export type MailgunClientOptions = {
     username: string;
     key: string;
     url?: string;
     public_key?: string;
     timeout?: number;
+    proxy?: AxiosProxyConfig;
 };

package/Types/Messages/Messages.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 /**
  * Ensures the object has least one key present and not undefined
  *
@@ -7,6 +8,17 @@
 export type AtLeastOneKeyPresent<Object_, Keys extends keyof Object_ = keyof Object_> = Pick<Object_, Exclude<keyof Object_, Keys>> & {
     [K in Keys]-?: Required<Pick<Object_, K>> & Partial<Pick<Object_, Exclude<Keys, K>>>;
 }[Keys];
+export type MimeMessage = string | Blob | Buffer | NodeJS.ReadableStream;
+export type CustomFileData = string | Blob | File | Buffer | NodeJS.ReadableStream;
+export type CustomFile = {
+    data: CustomFileData;
+    filename?: string;
+    contentType?: string;
+    knownLength?: number;
+    [key: string]: unknown;
+};
+export type MessageAttachment = CustomFile | CustomFile[] | File | File[] | string | CustomFileData | CustomFileData[];
+export type FormDataInputValue = MimeMessage | CustomFileData | string | string[] | boolean | MessageAttachment | undefined | number;
 export type MailgunMessageContent = AtLeastOneKeyPresent<{
     /**
      * Body of the message. (text version)
@@ -19,7 +31,7 @@ export type MailgunMessageContent = AtLeastOneKeyPresent<{
     /**
      * Body of the message. (MIME version)
      */
-    message?: string | Buffer | Blob;
+    message?: MimeMessage;
     /**
     * Name of a template stored via [template API](https://documentation.mailgun.com/en/latest/api-templates.html#api-templates). See [Templates](https://documentation.mailgun.com/en/latest/user_manual.html#templating) for more information
     */
@@ -57,7 +69,7 @@ export type MailgunMessageData = MailgunMessageContent & {
      *
      * **Important:** You must use `multipart/form-data` encoding when sending attachments.
      */
-    attachment?: any;
+    attachment?: MessageAttachment;
     /**
      * Attachment with `inline` disposition. Can be used to send inline images (see example).
      *
@@ -163,7 +175,7 @@ export type MailgunMessageData = MailgunMessageContent & {
      * `v:` prefix followed by an arbitrary name allows to attach a custom JSON data to the message. See [Attaching Data to Messages](https://documentation.mailgun.com/en/latest/user_manual.html#manual-customdata) for more information.
      */
     'v:my-var'?: string;
-    [key: string]: unknown;
+    [key: string]: FormDataInputValue;
 };
 export type MessagesSendAPIResponse = {
     status: number;

package/Types/Validations/MultipleValidation.d.ts

@@ -1,4 +1,5 @@
 import { PagesList, ParsedPagesList } from '../Common';
+import { CustomFile, CustomFileData } from '../Messages';
 export type MultipleValidationJobData = {
     created_at: number;
     id: string;
@@ -57,12 +58,10 @@ export type CreatedMultipleValidationJob = {
     message: string;
 };
 export type MultipleValidationCreationData = {
-    file: Record<string, unknown>;
-    [key: string]: unknown | undefined;
+    file: CustomFileData | CustomFile;
 };
 export type MultipleValidationCreationDataUpdated = {
-    multipleValidationFile: Record<string, unknown>;
-    [key: string]: unknown | undefined;
+    multipleValidationFile: CustomFileData | CustomFile;
 };
 export type MultipleValidationJobsListResult = {
     jobs: MultipleValidationJobResult[];