mailgun.js 10.1.0 → 10.2.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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)
 
 

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;
@@ -20,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/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/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[];