feat: add clients for ads and ads sandbox (#566)

Author: dmty

README.md

@@ -72,13 +72,13 @@ using descriptive typings for read/write/DMs rights, request parameters and resp
 
 A small feature comparison with other libs:
 
-| Package        | API version(s) | Response typings | Media helpers | Pagination | Subdeps |  Size (gzip)  | Install size  |
-| -------------- | -------------- | ---------------- | ------------- | ---------- | --------------- | -------------:|  -------------:|
-| twitter-api-v2 | v1.1, v2, labs | ✅               | ✅             | ✅         | 0               | ~23 kB      | [![twitter-api-v2 install size badge](https://badgen.net/packagephobia/install/twitter-api-v2)](https://packagephobia.com/result?p=twitter-api-v2) |
-| twit           | v1.1           | ❌               | ✅             | ❌         | 51              | ~214.5 kB     | [![twit install size badge](https://badgen.net/packagephobia/install/twit)](https://packagephobia.com/result?p=twit) |
-| twitter        | v1.1           | ❌               | ❌             | ❌         | 50              | ~182.1 kB     | [![twitter install size badge](https://badgen.net/packagephobia/install/twitter)](https://packagephobia.com/result?p=twitter) |
-| twitter-lite   | v1.1, v2       | ❌               | ❌             | ❌         | 4               | ~5.3 kB       | [![twitter-lite install size badge](https://badgen.net/packagephobia/install/twitter-lite)](https://packagephobia.com/result?p=twitter-lite) |
-| twitter-v2     | v2             | ❌               | ❌             | ❌         | 7               | ~4.5 kB       | [![twitter-v2 install size badge](https://badgen.net/packagephobia/install/twitter-v2)](https://packagephobia.com/result?p=twitter-v2) |
+| Package        | API version(s)      | Response typings | Media helpers | Pagination | Subdeps |  Size (gzip)  | Install size  |
+| -------------- |---------------------| ---------------- | ------------- | ---------- | --------------- | -------------:|  -------------:|
+| twitter-api-v2 | v1.1, v2, labs, ads | ✅               | ✅             | ✅         | 0               | ~23 kB      | [![twitter-api-v2 install size badge](https://badgen.net/packagephobia/install/twitter-api-v2)](https://packagephobia.com/result?p=twitter-api-v2) |
+| twit           | v1.1                | ❌               | ✅             | ❌         | 51              | ~214.5 kB     | [![twit install size badge](https://badgen.net/packagephobia/install/twit)](https://packagephobia.com/result?p=twit) |
+| twitter        | v1.1                | ❌               | ❌             | ❌         | 50              | ~182.1 kB     | [![twitter install size badge](https://badgen.net/packagephobia/install/twitter)](https://packagephobia.com/result?p=twitter) |
+| twitter-lite   | v1.1, v2            | ❌               | ❌             | ❌         | 4               | ~5.3 kB       | [![twitter-lite install size badge](https://badgen.net/packagephobia/install/twitter-lite)](https://packagephobia.com/result?p=twitter-lite) |
+| twitter-v2     | v2                  | ❌               | ❌             | ❌         | 7               | ~4.5 kB       | [![twitter-v2 install size badge](https://badgen.net/packagephobia/install/twitter-v2)](https://packagephobia.com/result?p=twitter-v2) |
 
 ## Features
 

src/ads-sandbox/client.ads-sandbox.read.ts

@@ -0,0 +1,9 @@
+import TwitterApiSubClient from '../client.subclient';
+import { API_ADS_SANDBOX_PREFIX } from '../globals';
+
+/**
+ * Base Twitter ads sandbox client with only read rights.
+ */
+export default class TwitterAdsSandboxReadOnly extends TwitterApiSubClient {
+  protected _prefix = API_ADS_SANDBOX_PREFIX;
+}

src/ads-sandbox/client.ads-sandbox.ts

@@ -0,0 +1,18 @@
+import { API_ADS_SANDBOX_PREFIX } from '../globals';
+import TwitterAdsSandboxReadWrite from './client.ads-sandbox.write';
+
+/**
+ * Twitter ads sandbox client with all rights (read/write)
+ */
+export class TwitterAdsSandbox extends TwitterAdsSandboxReadWrite {
+  protected _prefix = API_ADS_SANDBOX_PREFIX;
+
+  /**
+   * Get a client with read/write rights.
+   */
+  public get readWrite() {
+    return this as TwitterAdsSandboxReadWrite;
+  }
+}
+
+export default TwitterAdsSandbox;

src/ads-sandbox/client.ads-sandbox.write.ts

@@ -0,0 +1,16 @@
+import { API_ADS_SANDBOX_PREFIX } from '../globals';
+import TwitterAdsSandboxReadOnly from './client.ads-sandbox.read';
+
+/**
+ * Base Twitter ads sandbox client with read/write rights.
+ */
+export default class TwitterAdsSandboxReadWrite extends TwitterAdsSandboxReadOnly {
+  protected _prefix = API_ADS_SANDBOX_PREFIX;
+
+  /**
+   * Get a client with only read rights.
+   */
+  public get readOnly() {
+    return this as TwitterAdsSandboxReadOnly;
+  }
+}

src/ads/client.ads.read.ts

@@ -0,0 +1,9 @@
+import TwitterApiSubClient from '../client.subclient';
+import { API_ADS_PREFIX } from '../globals';
+
+/**
+ * Base Twitter ads client with only read rights.
+ */
+export default class TwitterAdsReadOnly extends TwitterApiSubClient {
+  protected _prefix = API_ADS_PREFIX;
+}

src/ads/client.ads.ts

@@ -0,0 +1,28 @@
+import { API_ADS_PREFIX } from '../globals';
+import TwitterAdsReadWrite from './client.ads.write';
+import TwitterAdsSandbox from '../ads-sandbox/client.ads-sandbox';
+
+/**
+ * Twitter ads client with all rights (read/write)
+ */
+export class TwitterAds extends TwitterAdsReadWrite {
+  protected _prefix = API_ADS_PREFIX;
+  protected _sandbox?: TwitterAdsSandbox;
+
+  /**
+   * Get a client with read/write rights.
+   */
+  public get readWrite() {
+    return this as TwitterAdsReadWrite;
+  }
+
+  /**
+   * Get Twitter Ads Sandbox API client
+   */
+  public get sandbox() {
+    if (this._sandbox) return this._sandbox;
+    return this._sandbox = new TwitterAdsSandbox(this);
+  }
+}
+
+export default TwitterAds;

src/ads/client.ads.write.ts

@@ -0,0 +1,16 @@
+import { API_ADS_PREFIX } from '../globals';
+import TwitterAdsReadOnly from './client.ads.read';
+
+/**
+ * Base Twitter ads client with read/write rights.
+ */
+export default class TwitterAdsReadWrite extends TwitterAdsReadOnly {
+  protected _prefix = API_ADS_PREFIX;
+
+  /**
+   * Get a client with only read rights.
+   */
+  public get readOnly() {
+    return this as TwitterAdsReadOnly;
+  }
+}

src/client/index.ts

@@ -2,6 +2,7 @@ import TwitterApiv1 from '../v1/client.v1';
 import TwitterApiv2 from '../v2/client.v2';
 import { TwitterApiError } from '../types';
 import TwitterApiReadWrite from './readwrite';
+import TwitterAds from '../ads/client.ads';
 
 
 // "Real" exported client for usage of TwitterApi.
@@ -11,6 +12,7 @@ import TwitterApiReadWrite from './readwrite';
 export class TwitterApi extends TwitterApiReadWrite {
   protected _v1?: TwitterApiv1;
   protected _v2?: TwitterApiv2;
+  protected _ads?: TwitterAds;
 
   /* Direct access to subclients */
   public get v1() {
@@ -32,6 +34,14 @@ export class TwitterApi extends TwitterApiReadWrite {
     return this as TwitterApiReadWrite;
   }
 
+  /**
+   * Get Twitter Ads API client
+   */
+  public get ads() {
+    if (this._ads) return this._ads;
+    return this._ads = new TwitterAds(this);
+  }
+
   /* Static helpers */
   public static getErrors(error: any) {
     if (typeof error !== 'object')

src/globals.ts

@@ -3,3 +3,5 @@ export const API_V2_LABS_PREFIX = 'https://api.x.com/labs/2/';
 export const API_V1_1_PREFIX = 'https://api.x.com/1.1/';
 export const API_V1_1_UPLOAD_PREFIX = 'https://upload.x.com/1.1/';
 export const API_V1_1_STREAM_PREFIX = 'https://stream.x.com/1.1/';
+export const API_ADS_PREFIX = 'https://ads-api.x.com/12/';
+export const API_ADS_SANDBOX_PREFIX = 'https://ads-api-sandbox.twitter.com/12/';