rettiwt-api 2.7.0 → 3.0.0

package/dist/services/public/TweetService.d.ts

@@ -1,12 +1,12 @@
 import { TweetFilter } from 'rettiwt-core';
-import { FetcherService } from '../internal/FetcherService';
-import { IRettiwtConfig } from '../../types/RettiwtConfig';
+import { TweetArgs } from '../../models/args/PostArgs';
+import { CursoredData } from '../../models/data/CursoredData';
 import { Tweet } from '../../models/data/Tweet';
 import { User } from '../../models/data/User';
-import { CursoredData } from '../../models/data/CursoredData';
-import { TweetMediaArgs } from '../../models/args/TweetArgs';
+import { IRettiwtConfig } from '../../types/RettiwtConfig';
+import { FetcherService } from './FetcherService';
 /**
- * Handles fetching of data related to tweets.
+ * Handles interacting with resources related to tweets.
  *
  * @public
  */
@@ -21,7 +21,10 @@ export declare class TweetService extends FetcherService {
      * Get the details of a tweet.
      *
      * @param id - The id of the target tweet.
-     * @returns The details of a single tweet with the given tweet id.
+     *
+     * @returns
+     * The details of the tweet with the given id.
+     * If no tweet matches the given id, returns `undefined`.
      *
      * @example
      * ```
@@ -30,8 +33,8 @@ export declare class TweetService extends FetcherService {
      * // Creating a new Rettiwt instance using the given 'API_KEY'
      * const rettiwt = new Rettiwt({ apiKey: API_KEY });
      *
-     * // Fetching the details of the tweet with the id '12345678'
-     * rettiwt.tweet.details('12345678')
+     * // Fetching the details of the tweet with the id '1234567890'
+     * rettiwt.tweet.details('1234567890')
      * .then(res => {
      * 	console.log(res);
      * })
@@ -39,17 +42,14 @@ export declare class TweetService extends FetcherService {
      * 	console.log(err);
      * });
      * ```
-     *
-     * @public
      */
-    details(id: string): Promise<Tweet>;
+    details(id: string): Promise<Tweet | undefined>;
     /**
-     * Search for tweets using a query.
+     * Like a tweet.
      *
-     * @param query - The query be used for searching the tweets.
-     * @param count - The number of tweets to fetch, must be \<= 20.
-     * @param cursor - The cursor to the batch of tweets to fetch.
-     * @returns The list of tweets that match the given filter.
+     * @param id - The id of the tweet to be liked.
+     *
+     * @returns Whether liking was successful or not.
      *
      * @example
      * ```
@@ -58,8 +58,8 @@ export declare class TweetService extends FetcherService {
      * // Creating a new Rettiwt instance using the given 'API_KEY'
      * const rettiwt = new Rettiwt({ apiKey: API_KEY });
      *
-     * // Fetching the most recent 5 tweets from user 'user1'
-     * rettiwt.tweet.search({ fromUsers: ['user1'] }, 5)
+     * // Liking the Tweet with id '1234567890'
+     * rettiwt.tweet.like('1234567890')
      * .then(res => {
      * 	console.log(res);
      * })
@@ -67,18 +67,16 @@ export declare class TweetService extends FetcherService {
      * 	console.log(err);
      * });
      * ```
-     *
-     * @remarks For details about available filters, refer to {@link TweetFilter}
-     *
-     * @public
      */
-    search(query: TweetFilter, count?: number, cursor?: string): Promise<CursoredData<Tweet>>;
+    like(id: string): Promise<boolean>;
     /**
-     * Stream tweets in pseudo real-time using a filter.
+     * Get the list of users who liked a tweet.
      *
-     * @param filter - The filter to be used for searching the tweets.
-     * @param pollingInterval - The interval in milliseconds to poll for new tweets. Default interval is 60000 ms.
-     * @returns An async generator that yields matching tweets as they are found.
+     * @param id - The id of the target tweet.
+     * @param count - The number of likers to fetch, must be \<= 100.
+     * @param cursor - The cursor to the batch of likers to fetch.
+     *
+     * @returns The list of users who liked the given tweet.
      *
      * @example
      * ```
@@ -87,29 +85,25 @@ export declare class TweetService extends FetcherService {
      * // Creating a new Rettiwt instance using the given 'API_KEY'
      * const rettiwt = new Rettiwt({ apiKey: API_KEY });
      *
-     * // Streaming all upcoming tweets from user 'user1'
-     * (async () => {
-     * 	try {
-     * 		for await (const tweet of rettiwt.tweet.stream({ fromUsers: ['user1'] }, 1000)) {
-     * 			console.log(tweet.fullText);
-     * 		}
-     * 	}
-     * 	catch (err) {
-     * 		console.log(err);
-     * 	}
-     * })();
+     * // Fetching the most recent 100 likers of the Tweet with id '1234567890'
+     * rettiwt.tweet.likers('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
      * ```
-     *
-     * @public
      */
-    stream(filter: TweetFilter, pollingInterval?: number): AsyncGenerator<Tweet>;
+    likers(id: string, count?: number, cursor?: string): Promise<CursoredData<User>>;
     /**
-     * Get the tweets from the tweet list with the given id.
+     * Get the list of tweets from a tweet list.
      *
-     * @param listId - The id of list from where the tweets are to be fetched.
+     * @param id - The id of target list.
      * @param count - The number of tweets to fetch, must be \<= 100.
      * @param cursor - The cursor to the batch of tweets to fetch.
-     * @returns The list tweets present in the given list.
+     *
+     * @returns The list tweets in the given list.
      *
      * @example
      * ```
@@ -118,8 +112,8 @@ export declare class TweetService extends FetcherService {
      * // Creating a new Rettiwt instance using the given 'API_KEY'
      * const rettiwt = new Rettiwt({ apiKey: API_KEY });
      *
-     * // Fetching the most recent 100 tweets of the Twitter list with id '12345678'
-     * rettiwt.tweet.list('12345678')
+     * // Fetching the most recent 100 tweets of the Twitter list with id '1234567890'
+     * rettiwt.tweet.list('1234567890')
      * .then(res => {
      * 	console.log(res);
      * })
@@ -130,24 +124,78 @@ export declare class TweetService extends FetcherService {
      *
      * @remarks Due a bug in Twitter API, the count is ignored when no cursor is provided and defaults to 100.
      */
-    list(listId: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>>;
+    list(id: string, count?: number, cursor?: string): Promise<CursoredData<Tweet>>;
     /**
-     * Get the list of users who liked a tweet.
+     * Post a tweet.
      *
-     * @param tweetId - The rest id of the target tweet.
-     * @param count - The number of favoriters to fetch, must be \<= 100.
-     * @param cursor - The cursor to the batch of favoriters to fetch.
-     * @returns The list of users who liked the given tweet.
+     * @param options - The options describing the tweet to be posted. Check {@link TweetArgs} for available options.
+     *
+     * @returns Whether posting was successful or not.
      *
      * @example
+     * Posting a simple text
+     * ```
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Posting a tweet to twitter
+     * rettiwt.tweet.post({ text: 'Hello World!' })
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     *
+     * @example
+     * Posting a tweet with an image that has been already uploaded
+     * ```
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Posting a tweet, containing an image called 'mountains.jpg', to twitter
+     * rettiwt.tweet.post({ text: 'What a nice view!', media: [{ id: '1234567890' }] })
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     *
+     * @example
+     * Posting a reply to a tweet
+     * ```
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Posting a simple text reply, to a tweet with id "1234567890"
+     * rettiwt.tweet.post({ text: 'Hello!', replyTo: "1234567890" })
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     *
+     * * @example
+     * Posting a tweet that quotes another tweet
      * ```
      * import { Rettiwt } from 'rettiwt-api';
      *
      * // Creating a new Rettiwt instance using the given 'API_KEY'
      * const rettiwt = new Rettiwt({ apiKey: API_KEY });
      *
-     * // Fetching the most recent 100 likers of the Tweet with id '12345678'
-     * rettiwt.tweet.favoriters('12345678')
+     * // Posting a simple text tweet, quoting a tweet with id "1234567890"
+     * rettiwt.tweet.post({ text: 'Hello!', quote: "1234567890" })
      * .then(res => {
      * 	console.log(res);
      * })
@@ -155,16 +203,40 @@ export declare class TweetService extends FetcherService {
      * 	console.log(err);
      * });
      * ```
+     */
+    post(options: TweetArgs): Promise<string | undefined>;
+    /**
+     * Retweet a tweet.
+     *
+     * @param id - The id of the target tweet.
      *
-     * @public
+     * @returns Whether retweeting was successful or not.
+     *
+     * @example
+     * ```
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Retweeting the Tweet with id '1234567890'
+     * rettiwt.tweet.retweet('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
      */
-    favoriters(tweetId: string, count?: number, cursor?: string): Promise<CursoredData<User>>;
+    retweet(id: string): Promise<boolean>;
     /**
      * Get the list of users who retweeted a tweet.
      *
-     * @param tweetId - The rest id of the target tweet.
+     * @param id - The id of the target tweet.
      * @param count - The number of retweeters to fetch, must be \<= 100.
      * @param cursor - The cursor to the batch of retweeters to fetch.
+     *
      * @returns The list of users who retweeted the given tweet.
      *
      * @example
@@ -174,8 +246,8 @@ export declare class TweetService extends FetcherService {
      * // Creating a new Rettiwt instance using the given 'API_KEY'
      * const rettiwt = new Rettiwt({ apiKey: API_KEY });
      *
-     * // Fetching the most recent 100 retweeters of the Tweet with id '12345678'
-     * rettiwt.tweet.retweeters('12345678')
+     * // Fetching the most recent 100 retweeters of the Tweet with id '1234567890'
+     * rettiwt.tweet.retweeters('1234567890')
      * .then(res => {
      * 	console.log(res);
      * })
@@ -183,27 +255,26 @@ export declare class TweetService extends FetcherService {
      * 	console.log(err);
      * });
      * ```
-     *
-     * @public
      */
-    retweeters(tweetId: string, count?: number, cursor?: string): Promise<CursoredData<User>>;
+    retweeters(id: string, count?: number, cursor?: string): Promise<CursoredData<User>>;
     /**
-     * Post a tweet.
+     * Search for tweets using a filter.
      *
-     * @param text - The text to be posted, length must be \<= 280 characters.
-     * @param media - The list of media to post in the tweet, max number of media must be \<= 4.
-     * @param replyTo - The id of the tweet to which the reply is to be made.
-     * @returns Whether posting was successful or not.
+     * @param filter - The filter to be used for searching the tweets.
+     * @param count - The number of tweets to fetch, must be \<= 20.
+     * @param cursor - The cursor to the batch of tweets to fetch.
+     *
+     * @returns The list of tweets that match the given filter.
      *
-     * @example Posting a simple text
+     * @example
      * ```
      * import { Rettiwt } from 'rettiwt-api';
      *
      * // Creating a new Rettiwt instance using the given 'API_KEY'
      * const rettiwt = new Rettiwt({ apiKey: API_KEY });
      *
-     * // Posting a tweet to twitter
-     * rettiwt.tweet.tweet('Hello World!')
+     * // Fetching the most recent 5 tweets from user 'user1'
+     * rettiwt.tweet.search({ fromUsers: ['user1'] }, 5)
      * .then(res => {
      * 	console.log(res);
      * })
@@ -212,15 +283,54 @@ export declare class TweetService extends FetcherService {
      * });
      * ```
      *
-     * @example Posting a tweet with an image
+     * @remarks For details about available filters, refer to {@link TweetFilter}
+     */
+    search(filter: TweetFilter, count?: number, cursor?: string): Promise<CursoredData<Tweet>>;
+    /**
+     * Stream tweets in pseudo real-time using a filter.
+     *
+     * @param filter - The filter to be used for searching the tweets.
+     * @param pollingInterval - The interval in milliseconds to poll for new tweets. Default interval is 60000 ms.
+     *
+     * @returns An async generator that yields matching tweets as they are found.
+     *
+     * @example
+     * ```
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Streaming all upcoming tweets from user 'user1'
+     * (async () => {
+     * 	try {
+     * 		for await (const tweet of rettiwt.tweet.stream({ fromUsers: ['user1'] }, 1000)) {
+     * 			console.log(tweet.fullText);
+     * 		}
+     * 	}
+     * 	catch (err) {
+     * 		console.log(err);
+     * 	}
+     * })();
+     * ```
+     */
+    stream(filter: TweetFilter, pollingInterval?: number): AsyncGenerator<Tweet>;
+    /**
+     * Unlike a tweet.
+     *
+     * @param id - The id of the target tweet.
+     *
+     * @returns Whether unliking was successful or not.
+     *
+     * @example
      * ```
      * import { Rettiwt } from 'rettiwt-api';
      *
      * // Creating a new Rettiwt instance using the given 'API_KEY'
      * const rettiwt = new Rettiwt({ apiKey: API_KEY });
      *
-     * // Posting a tweet, containing an image called 'mountains.jpg', to twitter
-     * rettiwt.tweet.tweet('What a nice view!', [{ path: 'mountains.jpg' }])
+     * // Unliking the Tweet with id '1234567890'
+     * rettiwt.tweet.unlike('1234567890')
      * .then(res => {
      * 	console.log(res);
      * })
@@ -228,16 +338,24 @@ export declare class TweetService extends FetcherService {
      * 	console.log(err);
      * });
      * ```
+     */
+    unlike(id: string): Promise<boolean>;
+    /**
+     * Unpost a tweet.
      *
-     * @example Posting a reply to a tweet
+     * @param id - The id of the target tweet.
+     *
+     * @returns Whether unposting was successful or not.
+     *
+     * @example
      * ```
      * import { Rettiwt } from 'rettiwt-api';
      *
      * // Creating a new Rettiwt instance using the given 'API_KEY'
      * const rettiwt = new Rettiwt({ apiKey: API_KEY });
      *
-     * // Posting a simple text reply, to a tweet with id "1234567890"
-     * rettiwt.tweet.tweet('Hello!', undefined, "1234567890")
+     * // Unposting the Tweet with id '1234567890'
+     * rettiwt.tweet.unpost('1234567890')
      * .then(res => {
      * 	console.log(res);
      * })
@@ -245,15 +363,14 @@ export declare class TweetService extends FetcherService {
      * 	console.log(err);
      * });
      * ```
-     *
-     * @public
      */
-    tweet(text: string, media?: TweetMediaArgs[], replyTo?: string): Promise<boolean>;
+    unpost(id: string): Promise<boolean>;
     /**
-     * Favorite the tweet with the given id.
+     * Unretweet a tweet.
      *
-     * @param tweetId - The id of the tweet to be favorited.
-     * @returns Whether favoriting was successful or not.
+     * @param id - The id of the target tweet.
+     *
+     * @returns Whether unretweeting was successful or not.
      *
      * @example
      * ```
@@ -262,8 +379,8 @@ export declare class TweetService extends FetcherService {
      * // Creating a new Rettiwt instance using the given 'API_KEY'
      * const rettiwt = new Rettiwt({ apiKey: API_KEY });
      *
-     * // Liking the Tweet with id '12345678'
-     * rettiwt.tweet.favorite('12345678')
+     * // Unretweeting the Tweet with id '1234567890'
+     * rettiwt.tweet.unretweet('1234567890')
      * .then(res => {
      * 	console.log(res);
      * })
@@ -271,15 +388,14 @@ export declare class TweetService extends FetcherService {
      * 	console.log(err);
      * });
      * ```
-     *
-     * @public
      */
-    favorite(tweetId: string): Promise<boolean>;
+    unretweet(id: string): Promise<boolean>;
     /**
-     * Retweet the tweet with the given id.
+     * Upload a media file to Twitter.
      *
-     * @param tweetId - The id of the tweet with the given id.
-     * @returns Whether retweeting was successful or not.
+     * @param media - The path or ArrayBuffer to the media file to upload.
+     *
+     * @returns The id of the uploaded media.
      *
      * @example
      * ```
@@ -288,8 +404,8 @@ export declare class TweetService extends FetcherService {
      * // Creating a new Rettiwt instance using the given 'API_KEY'
      * const rettiwt = new Rettiwt({ apiKey: API_KEY });
      *
-     * // Retweeting the Tweet with id '12345678'
-     * rettiwt.tweet.retweet('12345678')
+     * // Uploading a file called mountains.jpg
+     * rettiwt.tweet.upload('mountains.jpg')
      * .then(res => {
      * 	console.log(res);
      * })
@@ -298,7 +414,10 @@ export declare class TweetService extends FetcherService {
      * });
      * ```
      *
-     * @public
+     * @remarks
+     * - The uploaded media exists for 24 hrs within which it can be included in a tweet to be posted.
+     * If not posted in a tweet within this period, the uploaded media is removed.
+     * - Instead of a path to the media, an ArrayBuffer containing the media can also be uploaded.
      */
-    retweet(tweetId: string): Promise<boolean>;
+    upload(media: string | ArrayBuffer): Promise<string>;
 }