Merge pull request #392 from mailgun/DE-1204-implement-subaccounts-an…

…d-add-on-behalf-of-header

feature: Add Subaccounts and 'On-behalf-of' header

README.md

@@ -10,6 +10,7 @@ __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)
   - [Generated docs](#generated-docs)
@@ -56,6 +57,17 @@ Once the package is installed, you can import the library using `import` or `req
   const mailgun = new Mailgun(FormData);
   const mg = mailgun.client({username: 'api', key: process.env.MAILGUN_API_KEY || 'key-yourkeyhere'});
 ```
+### 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 * 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'});
+  mg.setSubaccount('subaccount-id');
+  // then, if you need to reset it back to the primary account:
+  mg.resetSubaccount();
+```
 ### Types imports
 Starting from version **9.0.0.** Types can be includes as named import:
 ```TS
@@ -152,6 +164,12 @@ The following service methods are available to instantiated clients. The example
       - [createMembers](#createmembers)
       - [updateMember](#updatemember)
       - [destroyMember](#destroymember)
+    - [subaccounts](#subaccounts)
+      - [list](#list-6)
+      - [get](#get-8)
+      - [create](#create-7)
+      - [enable](#enable)
+      - [disable](#disable)
   - [Navigation thru lists](#navigation-thru-lists)
   - [Browser Demo](#browser-demo)
 - [Development](#development)
@@ -2044,6 +2062,115 @@ A client to manage members within a specific mailing list.
     message: 'Mailing list member has been deleted'
   }
   ```
+### Subaccounts
+
+  A client to manage subaccounts.
+
+- #### list
+
+  `mg.subaccounts.list(query)` - [api docs](https://documentation.mailgun.com/en/latest/subaccounts.html)
+
+  Example:
+
+  ```js
+  mg.subaccounts.list()
+    .then(subaccounts => console.log(subaccounts)) // logs array of subaccounts
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns: array of Subaccounts instances
+
+  ```JS
+  [
+    { id: "XYZ", name: "test.subaccount1", status: "open" },
+    { id: "YYY", name: "test.subaccount2", status: "open" }
+  ]
+  ```
+
+  Query data may have next properties:
+
+  | Property | Description                                                            |
+  |:---------|:-----------------------------------------------------------------------|
+  | limit    | Maximum number of records to return. (10 by default)                   |
+  | skip     | Number of records to skip. (0 by default)                              |
+  | sort     | "asc" or "desc".                                                       |
+  | enabled  | Returns all enabled/disabled subaccounts. (Defaults to all if omitted) |
+
+- #### get
+
+  `mg.subaccounts.get(subaccount_id)`
+
+  Example:
+
+  ```JS
+  mg.subaccounts.get('123')
+    .then(subaccount => console.log(subaccount)) // logs subaccount object
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns: Subaccount instance
+
+  ```JS
+  { id: "123", name: "test.subaccount1", status: "open" }
+  ```
+
+- #### create
+
+  `mg.subaccounts.create(name)`
+
+  Example:
+
+  ```js
+  mg.subaccounts.create('foobar')
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+
+  Promise returns: Subaccount instance
+
+  ```JS
+  { id: "123", name: "foobar", status: "open" }
+  ```
+
+  Create method accepts data object with next properties:
+
+  | Parameter 	 | Description 	                                             |
+  |-------------|-----------------------------------------------------------|
+  | name 	     | Name of the subaccount being created (ex. 'mysubaccount') 	 |
+
+- #### enable
+
+  `mg.subaccounts.enable(subaccount_id)`
+
+  Example:
+
+  ```js
+  mg.subaccounts.enable('123')
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+  Promise returns: Subaccount instance
+
+  ```JS
+  { id: "123", name: "foobar", status: "open" }
+  ```
+
+- #### disable
+
+  `mg.subaccounts.disable(subaccount_id)`
+
+  Example:
+
+  ```js
+  mg.subaccounts.disable('123')
+    .then(msg => console.log(msg)) // logs response data
+    .catch(err => console.error(err)); // logs any error
+  ```
+  Promise returns: Subaccount instance
+
+  ```JS
+  { id: "123", name: "foobar", status: "disabled" }
+  ```
 
 ## Navigation thru lists
   Most of the methods that return items in a list support pagination.
@@ -2211,7 +2338,6 @@ A client to manage members within a specific mailing list.
     );
     ```
 
-
 ## Browser Demo
 
 ![image](https://cloud.githubusercontent.com/assets/399776/10718632/e8fe56e4-7b34-11e5-84c8-cfcfde978711.png)

dist/Classes/MailgunClient.d.ts

@@ -1,6 +1,5 @@
-import { MailgunClientOptions } from '../Types/MailgunClient';
-import { InputFormData } from '../Types/Common';
-import { IDomainsClient, IWebHooksClient, IMailgunClient, IMailingListsClient, IEventClient, IStatsClient, ISuppressionClient, IMessagesClient, IRoutesClient, IValidationClient, IIPsClient, IIPPoolsClient } from '../Interfaces';
+import { MailgunClientOptions, InputFormData } from '../Types';
+import { IDomainsClient, IWebHooksClient, IMailgunClient, IMailingListsClient, IEventClient, IStatsClient, ISuppressionClient, IMessagesClient, IRoutesClient, IValidationClient, IIPsClient, IIPPoolsClient, ISubaccountsClient } from '../Interfaces';
 export default class MailgunClient implements IMailgunClient {
     private request;
     domains: IDomainsClient;
@@ -14,5 +13,8 @@ export default class MailgunClient implements IMailgunClient {
     ips: IIPsClient;
     ip_pools: IIPPoolsClient;
     lists: IMailingListsClient;
+    subaccounts: ISubaccountsClient;
     constructor(options: MailgunClientOptions, formData: InputFormData);
+    setSubaccount(subaccountId: string): void;
+    resetSubaccount(): void;
 }

dist/Classes/Messages.d.ts

@@ -1,4 +1,4 @@
-import { MailgunMessageData, MessagesSendAPIResponse, MessagesSendResult } from '../Types/Messages';
+import { MailgunMessageData, MessagesSendAPIResponse, MessagesSendResult } from '../Types';
 import Request from './common/Request';
 import { IMessagesClient } from '../Interfaces';
 export default class MessagesClient implements IMessagesClient {

dist/Classes/Subaccounts.d.ts

@@ -0,0 +1,13 @@
+import Request from './common/Request';
+import { ISubaccountsClient } from '../Interfaces';
+import { SubaccountListResponseData, SubaccountResponseData, SubaccountsQuery } from '../Types';
+export default class SubaccountsClient implements ISubaccountsClient {
+    request: Request;
+    static SUBACCOUNT_HEADER: string;
+    constructor(request: Request);
+    list(query?: SubaccountsQuery): Promise<SubaccountListResponseData>;
+    get(id: string): Promise<SubaccountResponseData>;
+    create(name: string): Promise<SubaccountResponseData>;
+    enable(id: string): Promise<SubaccountResponseData>;
+    disable(id: string): Promise<SubaccountResponseData>;
+}

dist/Classes/common/Request.d.ts

@@ -1,6 +1,5 @@
 import * as NodeFormData from 'form-data';
-import { RequestOptions, InputFormData, APIResponse } from '../../Types/Common';
-import { IpPoolDeleteData } from '../../Types/IPPools';
+import { RequestOptions, InputFormData, APIResponse, IpPoolDeleteData } from '../../Types';
 declare class Request {
     private username;
     private key;
@@ -14,6 +13,8 @@ declare class Request {
     private getResponseBody;
     private joinAndTransformHeaders;
     private makeHeadersFromObject;
+    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>;

dist/Interfaces/MailgunClient/IMailgunClient.d.ts

@@ -9,6 +9,7 @@ import { IValidationClient } from '../Validations';
 import { IIPsClient } from '../IPs';
 import { IIPPoolsClient } from '../IPPools';
 import { IMailingListsClient } from '../MailingLists';
+import { ISubaccountsClient } from '../Subaccounts';
 export interface IMailgunClient {
     domains: IDomainsClient;
     webhooks: IWebHooksClient;
@@ -21,4 +22,7 @@ export interface IMailgunClient {
     ips: IIPsClient;
     ip_pools: IIPPoolsClient;
     lists: IMailingListsClient;
+    subaccounts: ISubaccountsClient;
+    setSubaccount(subaccountId: string): void;
+    resetSubaccount(): void;
 }

dist/Interfaces/Subaccounts/ISubaccountsClient.d.ts

@@ -0,0 +1,8 @@
+import { SubaccountListResponseData, SubaccountResponseData, SubaccountsQuery } from '../../Types';
+export interface ISubaccountsClient {
+    list(query?: SubaccountsQuery): Promise<SubaccountListResponseData>;
+    get(id: string): Promise<SubaccountResponseData>;
+    create(name: string): Promise<SubaccountResponseData>;
+    disable(id: string): Promise<SubaccountResponseData>;
+    enable(id: string): Promise<SubaccountResponseData>;
+}

dist/Interfaces/Subaccounts/index.d.ts

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

dist/Interfaces/index.d.ts

@@ -11,3 +11,4 @@ export * from './Messages';
 export * from './Routes';
 export * from './IPs';
 export * from './IPPools';
+export * from './Subaccounts';