mailgun.js 12.3.0 → 12.4.0

package/Types/Classes/Events.d.ts

@@ -1,10 +1,11 @@
 import NavigationThruPages from './common/NavigationThruPages.js';
 import { EventsList, EventsQuery, EventsResponse } from '../Types/Events/index.js';
 import Request from './common/Request.js';
-import { IEventClient } from '../Interfaces/index.js';
+import { IEventClient, ILogger } from '../Interfaces/index.js';
 export default class EventClient extends NavigationThruPages<EventsList> implements IEventClient {
     request: Request;
-    constructor(request: Request);
+    private logger;
+    constructor(request: Request, logger?: ILogger);
     protected parseList(response: EventsResponse): EventsList;
     get(domain: string, query?: EventsQuery): Promise<EventsList>;
 }

package/Types/Classes/Logs/LogsClient.d.ts

@@ -0,0 +1,12 @@
+import Request from '../common/Request.js';
+import { LogsList, LogsQuery } from '../../Types/Logs/Logs.js';
+import { ILogsClient } from '../../Interfaces/Logs/ILogsClient.js';
+export default class LogsClient implements ILogsClient {
+    request: Request;
+    constructor(request: Request);
+    private parseListResponse;
+    private prepareDate;
+    private parseQuery;
+    private validateQuery;
+    list(queryData: LogsQuery): Promise<LogsList>;
+}

package/Types/Classes/MailgunClient.d.ts

@@ -1,6 +1,7 @@
 import Request from './common/Request.js';
 import { MailgunClientOptions, InputFormData } from '../Types/index.js';
 import { IDomainsClient, IWebHooksClient, IMailgunClient, IMailingListsClient, IEventClient, IStatsClient, ISuppressionClient, IMessagesClient, IRoutesClient, IValidationClient, IIPsClient, IIPPoolsClient, ISubaccountsClient, IInboxPlacementsClient, IMetricsClient } from '../Interfaces/index.js';
+import { ILogsClient } from '../Interfaces/Logs/ILogsClient.js';
 export default class MailgunClient implements IMailgunClient {
     request: Request;
     domains: IDomainsClient;
@@ -17,6 +18,7 @@ export default class MailgunClient implements IMailgunClient {
     lists: IMailingListsClient;
     subaccounts: ISubaccountsClient;
     inboxPlacements: IInboxPlacementsClient;
+    logs: ILogsClient;
     constructor(options: MailgunClientOptions, formData: InputFormData);
     setSubaccount(subaccountId: string): void;
     resetSubaccount(): void;

package/Types/Interfaces/Logs/ILogsClient.d.ts

@@ -0,0 +1,4 @@
+import { LogsList, LogsQuery } from '../../Types/Logs/index.js';
+export interface ILogsClient {
+    list(query: LogsQuery): Promise<LogsList>;
+}

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

@@ -0,0 +1 @@
+export * from './ILogsClient.js';

package/Types/Interfaces/MailgunClient/IMailgunClient.d.ts

@@ -13,6 +13,7 @@ import { ISubaccountsClient } from '../Subaccounts/index.js';
 import { IInboxPlacementsClient } from '../InboxPlacements/index.js';
 import { IMetricsClient } from '../Metrics/MetricsClient.js';
 import type Request from '../../Classes/common/Request.js';
+import { ILogsClient } from '../Logs/ILogsClient.js';
 export interface IMailgunClient {
     request: Request;
     domains: IDomainsClient;
@@ -31,4 +32,5 @@ export interface IMailgunClient {
     inboxPlacements: IInboxPlacementsClient;
     setSubaccount(subaccountId: string): void;
     resetSubaccount(): void;
+    logs: ILogsClient;
 }

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

@@ -10,6 +10,7 @@ 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';
+import { LogsQuery } from '../Logs/Logs.js';
 export type OnCallEmptyHeaders = {
     [key: string]: undefined;
 };
@@ -36,7 +37,7 @@ export type GetQueryTypes = IPsListQuery | RoutesListQuery | SubaccountsQuery |
     searchParams?: Array<Array<string>>;
 } | ValidationQuery;
 export type DeleteQueryTypes = DeletedDomainKeysQuery;
-export type PostDataTypes = InboxPlacementsData | MetricsQuery | string;
+export type PostDataTypes = InboxPlacementsData | MetricsQuery | LogsQuery | string;
 export type PutDataTypes = SeedsListsUpdatingData | object | FormDataInput | ConnectionSettings;
 export type RequestData = IpPoolDeleteData | PostDataTypes | PutDataTypes | NodeFormData | FormData;
 export type ContainsPrefix<T extends string> = `${T}${string}`;

package/Types/Types/Logs/Logs.d.ts

@@ -0,0 +1,172 @@
+export type LogsFilterValue = {
+    label: string;
+    value: string;
+};
+export type LogsFilter = {
+    AND: {
+        attribute: string;
+        comparator: string;
+        values: LogsFilterValue[];
+    }[];
+};
+export type LogsQuery = {
+    start?: Date;
+    end?: Date;
+    events?: string[];
+    'metric_events'?: string[];
+    'include_subaccounts'?: boolean;
+    'include_totals'?: boolean;
+    pagination?: {
+        sort?: string;
+        token?: string;
+        limit?: number;
+    };
+    filter?: LogsFilter;
+};
+export type LogsParsedQuery = Omit<LogsQuery, 'start' | 'end'> & {
+    start?: string;
+    end?: string;
+};
+export type LogsDeliveryStatus = {
+    message?: string;
+    'attempt-no'?: number;
+    'code'?: number;
+    'bounce-type'?: string;
+    description?: string;
+    'session-seconds'?: number;
+    'retry-seconds'?: number;
+    'enhanced-code'?: string;
+    'mx-host'?: string;
+    'certificate-verified'?: boolean;
+    'tls'?: boolean;
+    'utf8'?: boolean;
+    'first-delivery-attempt-seconds'?: number;
+    'last-code'?: number;
+    'last-message'?: string;
+};
+export type LogsEvent = {
+    id: string;
+    event: string;
+    '@timestamp': string;
+    account?: {
+        'parent-id': string;
+        'id': string;
+    };
+    campaigns?: {
+        id: string;
+        name: string;
+    }[];
+    tags?: string[];
+    method?: string;
+    'originating-ip'?: string;
+    'api-key-id'?: string;
+    'delivery-status'?: LogsDeliveryStatus;
+    'i-delivery-optimizer'?: string;
+    domain: {
+        name: string;
+    };
+    recipient?: string;
+    'recipient-domain'?: string;
+    'recipient-provider'?: string;
+    envelope?: {
+        sender?: string;
+        transport?: string;
+        'sending-ip'?: string;
+        targets?: string;
+        'i-ip-pool-id'?: string;
+    };
+    storage?: {
+        region?: string;
+        env?: string;
+        key?: string;
+        url?: string[];
+    };
+    template?: {
+        name?: string;
+        version?: string;
+        'is-text'?: boolean;
+    };
+    'log-level'?: string;
+    'user-variables'?: string;
+    'message'?: {
+        headers?: {
+            to: string;
+            'message-id': string;
+            from: string;
+            subject: string;
+        };
+        attachments?: {
+            filename?: string;
+            'content-type'?: string;
+            size?: number;
+        }[];
+        recipients?: string[];
+        size?: number;
+        'scheduled-for'?: number;
+    };
+    flags?: {
+        'is-authenticated': boolean;
+        'is-system-test': boolean;
+        'is-routed': boolean;
+        'is-amp'?: boolean;
+        'is-test-mode': boolean;
+        'is-delayed-bounce': boolean;
+        'is-callback': boolean;
+        'is-encrypted': boolean;
+    };
+    'primary-dkim'?: string;
+    ip?: string;
+    geolocation?: {
+        city?: string;
+        country?: string;
+        region?: string;
+        timezone?: string;
+    };
+    'client-info'?: {
+        'client-name'?: string;
+        'client-os'?: string;
+        'client-type'?: string;
+        'device-type'?: string;
+        'user-agent'?: string;
+        ip?: string;
+        bot?: string;
+    };
+    severity?: string;
+    reason?: string;
+    routes?: {
+        actions?: string;
+        description?: string;
+        expression?: string;
+        id?: string;
+        priority?: number;
+        match?: {
+            recipient?: string;
+        };
+    };
+    'mailing-list'?: {
+        address?: string;
+        'list-id'?: string;
+        sid?: string;
+    };
+    url?: string;
+};
+export type LogsEventItem = Omit<LogsEvent, '@timestamp'> & {
+    '@timestamp': Date;
+};
+export type LogsList = {
+    start: Date;
+    end: Date;
+    items: LogsEventItem[];
+    pagination: {
+        previous?: string;
+        first?: string;
+        last?: string;
+        next?: string;
+        total?: number;
+    };
+    aggregates: {
+        all: number;
+        metrics: object;
+    };
+    status: number;
+};

package/Types/Types/Logs/index.d.ts

@@ -0,0 +1 @@
+export * from './Logs.js';

package/Types/index.js

@@ -5216,9 +5216,11 @@ var NavigationThruPages = /** @class */ (function () {
 
 var EventClient = /** @class */ (function (_super) {
     __extends(EventClient, _super);
-    function EventClient(request) {
+    function EventClient(request, logger) {
+        if (logger === void 0) { logger = console; }
         var _this = _super.call(this, request) || this;
         _this.request = request;
+        _this.logger = logger;
         return _this;
     }
     EventClient.prototype.parseList = function (response) {
@@ -5231,6 +5233,7 @@ var EventClient = /** @class */ (function (_super) {
     EventClient.prototype.get = function (domain, query) {
         return __awaiter(this, void 0, void 0, function () {
             return __generator(this, function (_a) {
+                this.logger.warn('"events.get" method is deprecated. Please use "logs.list" instead');
                 return [2 /*return*/, this.requestListWithPages(urljoin('/v3', domain, 'events'), query)];
             });
         });
@@ -7113,6 +7116,97 @@ var DomainKeysClient = /** @class */ (function (_super) {
     return DomainKeysClient;
 }(NavigationThruPages));
 
+var LogsClient = /** @class */ (function () {
+    function LogsClient(request) {
+        this.request = request;
+    }
+    LogsClient.prototype.parseListResponse = function (response) {
+        var parsedResponse = {
+            start: new Date(response.body.start),
+            end: new Date(response.body.end),
+            status: response.status,
+            pagination: response.body.pagination,
+            items: response.body.items.map(function (item) {
+                var responseItem = __assign(__assign({}, item), { '@timestamp': new Date(item['@timestamp']) });
+                return responseItem;
+            }),
+            aggregates: response.body.aggregates
+        };
+        return parsedResponse;
+    };
+    LogsClient.prototype.prepareDate = function (date) {
+        // 'Wed, 03 Dec 2025 00:00:00 -0000'
+        var formattedDate = "".concat(date.toUTCString().slice(0, 25), " -0000");
+        return formattedDate;
+    };
+    LogsClient.prototype.parseQuery = function (queryData) {
+        var res = __assign(__assign({}, queryData), { start: '', end: '' });
+        if (queryData.start) {
+            res.start = this.prepareDate(queryData.start);
+        }
+        if (queryData.end) {
+            res.end = this.prepareDate(queryData.end);
+        }
+        return res;
+    };
+    LogsClient.prototype.validateQuery = function (queryData) {
+        if (!queryData) {
+            throw APIError.getUserDataError('Missed parameter "query"', '"logs.list": Query data is required');
+        }
+        if (queryData === null || queryData === void 0 ? void 0 : queryData.start) {
+            if ((!((queryData === null || queryData === void 0 ? void 0 : queryData.start) instanceof Date) || Number.isNaN(queryData.start.getTime()))) {
+                throw APIError.getUserDataError('Incorrect type', '"logs.list": Type of "start" must be valid JS Data object');
+            }
+        }
+        else {
+            throw APIError.getUserDataError('Missed property', '"logs.list": "start" property is required');
+        }
+        if (queryData === null || queryData === void 0 ? void 0 : queryData.end) {
+            if ((!((queryData === null || queryData === void 0 ? void 0 : queryData.end) instanceof Date) || Number.isNaN(queryData.end.getTime()))) {
+                throw APIError.getUserDataError('Incorrect type', '"logs.list": Type of "end" must be valid JS Data object');
+            }
+        }
+        if (queryData.filter) {
+            if (!queryData.filter.AND) {
+                throw APIError.getUserDataError('Incorrect filter', '"logs.list": Logs filter must have AND operator');
+            }
+            if (!Array.isArray(queryData.filter.AND) || queryData.filter.AND.length === 0) {
+                throw APIError.getUserDataError('Incorrect filter', '"logs.list": Logs filter AND operator must be an array');
+            }
+            queryData.filter.AND.forEach(function (condition) {
+                if (!condition.attribute || !condition.comparator || !condition.values) {
+                    throw APIError.getUserDataError('Incorrect filter', '"logs.list": Each condition in Logs filter AND operator must have attribute, comparator and values');
+                }
+                if (!Array.isArray(condition.values) || condition.values.length === 0) {
+                    throw APIError.getUserDataError('Incorrect filter', '"logs.list": Values in each condition of Logs filter AND operator must be an array');
+                }
+                condition.values.forEach(function (value) {
+                    if (!value.label || !value.value) {
+                        throw APIError.getUserDataError('Incorrect filter', '"logs.list": Each value in Logs filter condition must have label and value');
+                    }
+                });
+            });
+        }
+    };
+    LogsClient.prototype.list = function (queryData) {
+        return __awaiter(this, void 0, void 0, function () {
+            var preparedQuery, response;
+            return __generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        this.validateQuery(queryData);
+                        preparedQuery = this.parseQuery(queryData);
+                        return [4 /*yield*/, this.request.post(urljoin('/v1/analytics/logs'), preparedQuery)];
+                    case 1:
+                        response = _a.sent();
+                        return [2 /*return*/, this.parseListResponse(response)];
+                }
+            });
+        });
+    };
+    return LogsClient;
+}());
+
 var MailgunClient = /** @class */ (function () {
     function MailgunClient(options, formData) {
         var config = __assign({}, options);
@@ -7159,6 +7253,7 @@ var MailgunClient = /** @class */ (function () {
         this.validate = new ValidateClient(this.request, multipleValidationClient);
         this.subaccounts = new SubaccountsClient(this.request);
         this.inboxPlacements = new InboxPlacementsClient(this.request, seedsListsClient, inboxPlacementsResultsClient, inboxPlacementsProvidersClient);
+        this.logs = new LogsClient(this.request);
     }
     MailgunClient.prototype.setSubaccount = function (subaccountId) {
         var _a;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailgun.js",
-  "version": "12.3.0",
+  "version": "12.4.0",
   "author": "Mailgun",
   "license": "MIT",
   "type": "module",

package/version.md

@@ -1 +1 @@
-12.3.0
+12.4.0