feat: get tweet usage v2 (#555)

Author: jiahuijiang

doc/v2.md

@@ -62,6 +62,8 @@ This is a comprehensive guide of all methods available for the Twitter API v2 on
     - [Mute someone](#mute-someone)
     - [Unmute someone](#unmute-someone)
     - [Get users that are muted by you](#get-users-that-are-muted-by-you)
+  - [Usage](#usage)
+    - [Get usage](#get-usage)
   - [Lists](#lists)
     - [Single list by id](#single-list-by-id)
     - [Owned lists](#owned-lists)
@@ -997,6 +999,24 @@ for await (const mutedUser of mutedPaginator) {
 }
 ```
 
+### Get usage
+
+**Method**: `.usage()`
+
+**Endpoint**: `usage/tweets`
+
+**Right level**: `Read-only`
+
+**Arguments**:
+  - `options: TweetUsageV2Params`
+
+**Returns**: `TweetV2UsageResult`
+
+**Example**
+```ts
+const usage = await client.v2.usage({ 'usage.fields': ['daily_project_usage'] });
+```
+
 ## Lists
 
 ### Single list by id

src/types/v2/tweet.v2.types.ts

@@ -186,3 +186,32 @@ export interface BatchComplianceV2JobResult {
 export type BatchComplianceListV2Result = DataV2<BatchComplianceJobV2[]>;
 
 export type BatchComplianceV2Result = DataV2<BatchComplianceJobV2>;
+
+/// -- Usage --
+
+type TUsageField = 'cap_reset_day' | 'daily_client_app_usage' | 'daily_project_usage' | 'project_cap' | 'project_id' | 'project_usage';
+
+export type TweetUsageV2Params = {
+  days?: number;
+  'usage.fields'?: TUsageField[];
+}
+
+type TUsageDaily = {
+  /** ISO date string */
+  date: string;
+  usage: string;
+};
+
+export type TweetV2UsageResult = DataV2<{
+  project_id?: string;
+  project_cap?: string;
+  project_usage?: string;
+  cap_reset_day?: number;
+  daily_project_usage?: {
+    project_id: string;
+    usage: TUsageDaily[];
+  }[];
+  daily_client_app_usage?: {
+    usage: TUsageDaily[];
+  }[];
+}>;

src/v2/client.v2.read.ts

@@ -54,6 +54,8 @@ import {
   TweetV2PaginableTimelineResult,
   TweetV2HomeTimelineParams,
   TweetV2HomeTimelineResult,
+  TweetUsageV2Params,
+  TweetV2UsageResult,
 } from '../types';
 import {
   TweetSearchAllV2Paginator,
@@ -862,4 +864,15 @@ export default class TwitterApiv2ReadOnly extends TwitterApiSubClient {
       .filter(line => line)
       .map(line => JSON.parse(line)) as BatchComplianceV2JobResult[];
   }
+
+  /* Usage */
+
+  /**
+   * Allows you to retrieve your project usage.
+   * 
+   * https://developer.x.com/en/docs/x-api/usage/tweets/introduction
+   */
+  public async usage(options: Partial<TweetUsageV2Params> = {}) {
+    return this.get<TweetV2UsageResult>('usage/tweets', options);
+  }
 }