mailgun.js 4.1.5 → 4.2.2

package/lib/client.ts

@@ -19,6 +19,7 @@ import { InputFormData } from './interfaces/IFormData';
 import DomainCredentialsClient from './domainsCredentials';
 import MultipleValidationClient from './multipleValidation';
 import DomainTemplatesClient from './domainsTemplates';
+import DomainTagsClient from './domainsTags';
 
 export default class Client {
   private request;
@@ -55,9 +56,15 @@ export default class Client {
     const mailListsMembers = new MailListsMembers(this.request);
     const domainCredentialsClient = new DomainCredentialsClient(this.request);
     const domainTemplatesClient = new DomainTemplatesClient(this.request);
+    const domainTagsClient = new DomainTagsClient(this.request);
     const multipleValidationClient = new MultipleValidationClient(this.request);
 
-    this.domains = new DomainClient(this.request, domainCredentialsClient, domainTemplatesClient);
+    this.domains = new DomainClient(
+      this.request,
+      domainCredentialsClient,
+      domainTemplatesClient,
+      domainTagsClient
+    );
     this.webhooks = new WebhookClient(this.request);
     this.events = new EventClient(this.request);
     this.stats = new StatsClient(this.request);

package/lib/domains.ts

@@ -41,6 +41,8 @@ import { IDomainCredentials } from './interfaces/DomainCredentials';
 import { IDomainTemplatesClient } from './interfaces/DomainTemplates';
 import DomainCredentialsClient from './domainsCredentials';
 import DomainTemplatesClient from './domainsTemplates';
+import { IDomainTagsClient } from './interfaces/DomainTags';
+import DomainTagsClient from './domainsTags';
 
 export class Domain {
   name: string;
@@ -76,16 +78,19 @@ export class Domain {
 export default class DomainClient {
   request: Request;
   public domainCredentials: IDomainCredentials;
-  public domainTemplates: IDomainTemplatesClient
+  public domainTemplates: IDomainTemplatesClient;
+  public domainTags: IDomainTagsClient;
 
   constructor(
     request: Request,
     domainCredentialsClient: DomainCredentialsClient,
-    domainTemplatesClient: DomainTemplatesClient
+    domainTemplatesClient: DomainTemplatesClient,
+    domainTagsClient: DomainTagsClient
   ) {
     this.request = request;
     this.domainCredentials = domainCredentialsClient;
     this.domainTemplates = domainTemplatesClient;
+    this.domainTags = domainTagsClient;
   }
 
   private _parseMessage(response: DestroyedDomainResponse) : MessageResponse {

package/lib/domainsTags.ts

@@ -0,0 +1,165 @@
+import urljoin from 'url-join';
+import APIResponse from './interfaces/ApiResponse';
+import Request from './request';
+
+import {
+  DomainTagAPIResponseStatsItem,
+  DomainTagCountriesAggregation,
+  DomainTagCountriesAPIResponse,
+  DomainTagDevicesAggregation,
+  DomainTagDevicesAPIResponse,
+  DomainTagProvidersAggregation,
+  DomainTagProvidersAPIResponse,
+  DomainTagsItem,
+  DomainTagsItemInfo,
+  DomainTagsList,
+  DomainTagsMessageRes,
+  DomainTagsQuery,
+  DomainTagsResponseData,
+  DomainTagsStatisticQuery,
+  DomainTagStatAPIResponse,
+  DomainTagStatisticItem,
+  DomainTagStatisticResult,
+  IDomainTagsClient,
+  PagesList,
+  PagesListAccumulator,
+  ParsedPagesList,
+  Resolution
+} from './interfaces/DomainTags';
+
+export class DomainTag implements DomainTagsItem {
+  tag: string;
+  description: string;
+  'first-seen': Date;
+  'last-seen': Date;
+
+  constructor(tagInfo: DomainTagsItemInfo) {
+    this.tag = tagInfo.tag;
+    this.description = tagInfo.description;
+    this['first-seen'] = new Date(tagInfo['first-seen']);
+    this['last-seen'] = new Date(tagInfo['last-seen']);
+  }
+}
+
+export class DomainTagStatistic implements DomainTagStatisticResult {
+  tag: string;
+  description: string;
+  start: Date;
+  end: Date;
+  resolution: Resolution;
+  stats: DomainTagStatisticItem[];
+
+  constructor(tagStatisticInfo: DomainTagStatAPIResponse) {
+    this.tag = tagStatisticInfo.body.tag;
+    this.description = tagStatisticInfo.body.description;
+    this.start = new Date(tagStatisticInfo.body.start);
+    this.end = new Date(tagStatisticInfo.body.end);
+    this.resolution = tagStatisticInfo.body.resolution;
+    this.stats = tagStatisticInfo.body.stats.map(function (stat: DomainTagAPIResponseStatsItem) {
+      const res = { ...stat, time: new Date(stat.time) };
+      return res;
+    });
+  }
+}
+
+export default class DomainTagsClient implements IDomainTagsClient {
+  baseRoute: string;
+  request: Request;
+
+  constructor(request: Request) {
+    this.request = request;
+    this.baseRoute = '/v3/';
+  }
+
+  private _parsePageLinks(response: DomainTagsResponseData): ParsedPagesList {
+    const pages = Object.entries(response.body.paging as PagesList);
+    return pages.reduce(
+      (acc: PagesListAccumulator, entrie: [url: string, id: string]) => {
+        const id = entrie[0];
+        const url = entrie[1];
+        acc[id] = {
+          id,
+          url
+        };
+        return acc;
+      }, {}
+    ) as unknown as ParsedPagesList;
+  }
+
+  private _parseDomainTagsList(
+    response: DomainTagsResponseData
+  ): DomainTagsList {
+    return {
+      items: response.body.items.map((tagInfo) => new DomainTag(tagInfo)),
+      pages: this._parsePageLinks(response)
+    };
+  }
+
+  private _parseTagStatistic(
+    response: DomainTagStatAPIResponse
+  ): DomainTagStatistic {
+    return new DomainTagStatistic(response);
+  }
+
+  list(domain: string, query?: DomainTagsQuery): Promise<DomainTagsList> {
+    return this.request.get(urljoin(this.baseRoute, domain, '/tags'), query)
+      .then(
+        (res: APIResponse) => this._parseDomainTagsList(res as DomainTagsResponseData)
+      );
+  }
+
+  get(domain: string, tag: string): Promise<DomainTagsItem> {
+    return this.request.get(urljoin(this.baseRoute, domain, '/tags', tag))
+      .then(
+        (res: APIResponse) => new DomainTag(res.body)
+      );
+  }
+
+  update(domain: string, tag: string, description: string): Promise<DomainTagsMessageRes> {
+    return this.request.put(urljoin(this.baseRoute, domain, '/tags', tag), description)
+      .then(
+        (res: APIResponse) => res.body as DomainTagsMessageRes
+      );
+  }
+
+  destroy(
+    domain: string,
+    tag: string
+  ): Promise<DomainTagsMessageRes> {
+    return this.request.delete(`${this.baseRoute}${domain}/tags/${tag}`)
+      .then((res: APIResponse) => (
+        {
+          message: res.body.message,
+          status: res.status
+        } as DomainTagsMessageRes));
+  }
+
+  statistic(domain: string, tag: string, query: DomainTagsStatisticQuery)
+    : Promise<DomainTagStatistic> {
+    return this.request.get(urljoin(this.baseRoute, domain, '/tags', tag, 'stats'), query)
+      .then(
+        (res: APIResponse) => this._parseTagStatistic(res)
+      );
+  }
+
+  countries(domain: string, tag: string): Promise<DomainTagCountriesAggregation> {
+    return this.request.get(urljoin(this.baseRoute, domain, '/tags', tag, 'stats/aggregates/countries'))
+      .then(
+        (res: DomainTagCountriesAPIResponse) => res.body as DomainTagCountriesAggregation
+      );
+  }
+
+  providers(domain: string, tag: string): Promise<DomainTagProvidersAggregation> {
+    return this.request.get(urljoin(this.baseRoute, domain, '/tags', tag, 'stats/aggregates/providers'))
+      .then(
+        (res: DomainTagProvidersAPIResponse) => res.body as DomainTagProvidersAggregation
+      );
+  }
+
+  devices(domain: string, tag: string): Promise<DomainTagDevicesAggregation> {
+    return this.request.get(urljoin(this.baseRoute, domain, '/tags', tag, 'stats/aggregates/devices'))
+      .then(
+        (res: DomainTagDevicesAPIResponse) => res.body as DomainTagDevicesAggregation
+      );
+  }
+}

package/lib/interfaces/DomainTags.ts

@@ -0,0 +1,262 @@
+/* eslint-disable camelcase */
+import { DomainTagStatistic } from '../domainsTags';
+
+export enum Resolution {
+    HOUR = 'hour',
+    DAY = 'day',
+    MONTH = 'month'
+}
+export interface DomainTagsQuery {
+    limit: number;
+}
+
+export interface DomainTagsStatisticQuery {
+    event: string;
+    start?: number;
+    end?: number;
+    resolution?: Resolution;
+    duration?: string;
+}
+
+export interface DomainTagsItemInfo {
+    tag: string,
+    description: string,
+    'first-seen': string,
+    'last-seen': string
+}
+
+export interface DomainTagsItem {
+    tag: string,
+    description: string,
+    'first-seen': Date,
+    'last-seen': Date
+}
+
+export interface PagesList {
+    previous: string;
+    first: string;
+    last: string;
+    next: string;
+}
+
+export interface ParsedPage{
+    id: string;
+    url: string
+}
+export interface ParsedPagesList {
+    previous: ParsedPage;
+    first: ParsedPage;
+    last: ParsedPage;
+    next: ParsedPage;
+}
+
+export interface TagsPage {
+    id: string;
+    url: string;
+}
+
+export interface PagesListAccumulator {
+    [index: string]: TagsPage
+}
+export interface DomainTagsResponseData {
+    status: number;
+    body: {
+        items: DomainTagsItemInfo[];
+        paging: PagesList
+    }
+}
+
+export interface DomainTagsList {
+    items: DomainTagsItem[];
+    pages: ParsedPagesList;
+}
+
+export interface DomainTagsMessageRes {
+    message: string;
+    status?: number;
+}
+
+export interface DomainTagAPIResponseStatsItem {
+    time:string
+    accepted?: {
+        incoming: number;
+        outgoing: number;
+        total: number
+    }
+    delivered?: {
+        smtp: number;
+        http: number;
+        optimized: number;
+        total: number;
+    };
+    opened?: {
+        total: number;
+    };
+    failed?: {
+        temporary:{
+            espblock: number;
+            total: number;
+        };
+        permanent: {
+            'suppress-bounce': number;
+            'suppress-unsubscribe': number;
+            'suppress-complaint': number;
+            bounce: number;
+            'delayed-bounce': number;
+            webhook: number;
+            optimized: number;
+            total: number;
+        };
+    },
+    clicked?: {
+        total: number;
+    };
+    unsubscribed?: {
+        total: number;
+    };
+    complained?: {
+        total: number;
+    };
+    stored?: {
+        total: number;
+    }
+}
+export interface DomainTagStatAPIResponse {
+    body:{
+        tag: string;
+        description: string;
+        start: string;
+        end: string;
+        resolution: Resolution;
+        stats: DomainTagAPIResponseStatsItem[];
+    }
+}
+export interface DomainTagStatisticItem extends Omit <DomainTagAPIResponseStatsItem, 'time'>{
+    time: Date
+}
+
+export interface DomainTagStatisticResult {
+    tag: string;
+    description: string;
+    start: Date;
+    end: Date;
+    resolution: Resolution;
+    stats: DomainTagStatisticItem[];
+}
+
+export interface DomainTagCountriesAPIResponse {
+    body: {
+        tag:string;
+        country: {
+            [key:string]: {
+                clicked: number;
+                complained: number;
+                opened: number;
+                unique_clicked: number;
+                unique_opened: number;
+                unsubscribed: number;
+            }
+        };
+    }
+}
+
+export interface DomainTagCountriesAggregation {
+    tag:string;
+    country: {
+        [key: string]: {
+            clicked: number;
+            complained: number;
+            opened: number;
+            unique_clicked: number;
+            unique_opened: number;
+            unsubscribed: number;
+        }
+    }
+}
+
+export interface DomainTagProvidersAPIResponse {
+    body: {
+        tag:string;
+        provider: {
+            [key:string]: {
+                accepted: number;
+                clicked: number;
+                complained: number;
+                delivered: number;
+                opened: number;
+                unique_clicked: number;
+                unique_opened: number;
+                unsubscribed: number;
+            }
+        };
+    }
+    status: number;
+}
+
+export interface DomainTagProvidersAggregation {
+    tag: string;
+    provider: {
+        [key: string]: {
+            accepted: number;
+            clicked: number;
+            complained: number;
+            delivered: number;
+            opened: number;
+            unique_clicked: number;
+            unique_opened: number;
+            unsubscribed: number;
+        }
+    };
+}
+
+export interface DeviceStatistic {
+    clicked: number;
+    complained: number;
+    opened: number;
+    unique_clicked: number;
+    unique_opened: number;
+    unsubscribed: number;
+}
+
+export interface DevicesTypes {
+    desktop: DeviceStatistic;
+    mobile: DeviceStatistic;
+    tablet: DeviceStatistic;
+    unknown: DeviceStatistic;
+}
+
+export interface DomainTagDevicesAPIResponse {
+    body: {
+        tag:string;
+        device: DevicesTypes;
+    }
+    status: number;
+}
+
+export interface DomainTagDevicesAggregation {
+    tag: string;
+    device: DevicesTypes;
+}
+
+
+export interface IDomainTagsClient {
+    list(domain: string): Promise<DomainTagsList>
+    get(domain: string, tag: string): Promise<DomainTagsItem>
+    update(
+        domain: string,
+        tag: string,
+        description: string
+    ): Promise<DomainTagsMessageRes>
+    destroy(
+        domain: string,
+        tag: string
+    ): Promise<DomainTagsMessageRes>
+    statistic(
+        domain: string,
+        tag: string,
+        query: DomainTagsStatisticQuery
+    ): Promise<DomainTagStatistic>
+    countries(domain: string, tag: string): Promise<DomainTagCountriesAggregation>
+    providers(domain: string, tag: string): Promise<DomainTagProvidersAggregation>
+    devices(domain: string, tag: string): Promise<DomainTagDevicesAggregation>
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mailgun.js",
-  "version": "4.1.5",
+  "version": "4.2.2",
   "main": "dist/mailgun.node.js",
   "browser": "dist/mailgun.web.js",
   "types": "dist/index.d.ts",
@@ -60,7 +60,7 @@
     "form-data": "^3.0.1",
     "husky": "^7.0.1",
     "json-loader": "^0.5.7",
-    "mocha": "^9.1.3",
+    "mocha": "^9.2.0",
     "mocha-multi": "^1.1.3",
     "nock": "^13.0.4",
     "nyc": "^15.1.0",
@@ -69,7 +69,7 @@
     "terser-webpack-plugin": "^5.2.0",
     "ts-loader": "^8.0.12",
     "ts-node": "^9.1.1",
-    "typedoc": "^0.20.36",
+    "typedoc": "^0.22.11",
     "typescript": "^4.1.3",
     "webpack": "^5.3.2",
     "webpack-cli": "^4.1.0"

package/test/domains.test.ts

@@ -15,6 +15,7 @@ import {
   UpdatedDKIMSelectorResponse, UpdatedWebPrefixResponse
 } from '../lib/interfaces/Domains';
 import DomainTemplatesClient from '../lib/domainsTemplates';
+import DomainTagsClient from '../lib/domainsTags';
 
 // TODO: fix types
 describe('DomainClient', function () {
@@ -25,7 +26,13 @@ describe('DomainClient', function () {
     const reqObject = new Request({ url: 'https://api.mailgun.net' } as RequestOptions, formData as InputFormData);
     const domainCredentialsClient = new DomainCredentialsClient(reqObject);
     const domainTemplatesClient = new DomainTemplatesClient(reqObject);
-    client = new DomainClient(reqObject, domainCredentialsClient, domainTemplatesClient);
+    const domainTagsClient = new DomainTagsClient(reqObject);
+    client = new DomainClient(
+      reqObject,
+      domainCredentialsClient,
+      domainTemplatesClient,
+      domainTagsClient
+    );
     api = nock('https://api.mailgun.net');
   });