@youmind-openlab/rettiwt-api 1.0.0

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

@@ -0,0 +1,586 @@
+import { TweetRepliesSortType } from '../../enums/Tweet';
+import { CursoredData } from '../../models/data/CursoredData';
+import { Tweet } from '../../models/data/Tweet';
+import { User } from '../../models/data/User';
+import { RettiwtConfig } from '../../models/RettiwtConfig';
+import { ITweetFilter } from '../../types/args/FetchArgs';
+import { INewTweet } from '../../types/args/PostArgs';
+import { FetcherService } from './FetcherService';
+/**
+ * Handles interacting with resources related to tweets.
+ *
+ * @public
+ */
+export declare class TweetService extends FetcherService {
+    /**
+     * @param config - The config object for configuring the Rettiwt instance.
+     *
+     * @internal
+     */
+    constructor(config: RettiwtConfig);
+    /**
+     * Bookmark a tweet.
+     *
+     * @param id - The ID of the tweet to be bookmarked.
+     *
+     * @returns Whether bookmarking was successful or not.
+     *
+     * @example
+     *
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Bookmarking the Tweet with id '1234567890'
+     * rettiwt.tweet.bookmark('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     */
+    bookmark(id: string): Promise<boolean>;
+    /**
+     * Get the details of one or more tweets.
+     *
+     * @param id - The ID/IDs of the target tweet/tweets.
+     *
+     * @returns
+     * The details of the tweet with the given ID.
+     *
+     * If more than one ID is provided, returns a list.
+     *
+     * If no tweet/tweets matches the given ID/IDs, returns `undefined`/`[]`.
+     *
+     * @example
+     *
+     * #### Fetching the details of a single tweet
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // 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 '1234567890'
+     * rettiwt.tweet.details('1234567890')
+     * .then(res => {
+     * 	console.log(res);	# 'res' is a single tweet
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     *
+     * @example
+     *
+     * #### Fetching the details of multiple tweets
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Fetching the details of the tweets with IDs '123', '456', '789'
+     * rettiwt.tweet.details(['123', '456', '789'])
+     * .then(res => {
+     * 	console.log(res);	# 'res' is an array of tweets
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     */
+    details<T extends string | string[]>(id: T): Promise<T extends string ? Tweet | undefined : Tweet[]>;
+    /**
+     * Like a tweet.
+     *
+     * @param id - The ID of the tweet to be liked.
+     *
+     * @returns Whether liking was successful or not.
+     *
+     * @example
+     *
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Liking the Tweet with id '1234567890'
+     * rettiwt.tweet.like('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     */
+    like(id: string): Promise<boolean>;
+    /**
+     * Get the list of users who liked a tweet. Only works for your own tweets.
+     *
+     * @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
+     *
+     * ```ts
+     * 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 '1234567890'
+     * rettiwt.tweet.likers('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     */
+    likers(id: string, count?: number, cursor?: string): Promise<CursoredData<User>>;
+    /**
+     * Post a tweet.
+     *
+     * @param options - The options describing the tweet to be posted. Check {@link TweetArgs} for available options.
+     *
+     * @returns The ID of the posted tweet.
+     *
+     * @example
+     *
+     * #### Posting a simple text
+     * ```ts
+     * 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
+     * ```ts
+     * 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 with ID '1234567890', 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
+     * ```ts
+     * 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
+     * ```ts
+     * 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 tweet, quoting a tweet with id "1234567890"
+     * rettiwt.tweet.post({ text: 'Hello!', quote: "1234567890" })
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     */
+    post(options: INewTweet): Promise<string | undefined>;
+    /**
+     * Get the list of replies to a tweet.
+     *
+     * If the target tweet is a thread,
+     * the first batch always contains all the tweets in the thread,
+     * if `sortBy` is set to {@link TweetRepliesSortType.RELEVANCE}.
+     *
+     * @param id - The ID of the target tweet.
+     * @param cursor - The cursor to the batch of replies to fetch.
+     * @param sortBy - The sorting order of the replies to fetch. Default is {@link TweetRepliesSortType.RECENT}.
+     *
+     * @returns The list of replies to the given tweet.
+     *
+     * @example
+     *
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Fetching the first 100 replies to the Tweet with id '1234567890'
+     * rettiwt.tweet.replies('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     *
+     * @remarks
+     *
+     * If the given tweet is the start of/part of a thread, the first batch always contains all the tweets in the thread.
+     */
+    replies(id: string, cursor?: string, sortBy?: TweetRepliesSortType): Promise<CursoredData<Tweet>>;
+    /**
+     * Retweet a tweet.
+     *
+     * @param id - The ID of the target tweet.
+     *
+     * @returns Whether retweeting was successful or not.
+     *
+     * @example
+     *
+     * ```ts
+     * 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);
+     * });
+     * ```
+     */
+    retweet(id: string): Promise<boolean>;
+    /**
+     * Get the list of users who retweeted a 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
+     *
+     * ```ts
+     * 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 retweeters of the Tweet with id '1234567890'
+     * rettiwt.tweet.retweeters('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     */
+    retweeters(id: string, count?: number, cursor?: string): Promise<CursoredData<User>>;
+    /**
+     * Schedule a tweet.
+     *
+     * @param options - The options describing the tweet to be posted. Check {@link TweetArgs} for available options.
+     *
+     * @returns The ID of the schedule.
+     *
+     * @example
+     *
+     * #### Scheduling a simple text
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Scheduling a tweet to posted at 19th of August, 2024, at 11:59:00 AM, in local time
+     * rettiwt.tweet.schedule({ text: 'Hello World!', scheduleFor: new Date('2024-08-19 23:59:00') })
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     *
+     * @remarks
+     *
+     * Scheduling a tweet is similar to {@link post}ing, except that an extra parameter called `scheduleFor` is used.
+     */
+    schedule(options: INewTweet): Promise<string | undefined>;
+    /**
+     * Search for tweets using a filter.
+     *
+     * @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.
+     * @param results - The type of search results to fetch. Default is {@link ESearchResultType.LATEST}.
+     *
+     * @returns The list of tweets that match the given filter.
+     *
+     * @example
+     *
+     * ```ts
+     * 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 5 tweets from user 'user1'
+     * rettiwt.tweet.search({ fromUsers: ['user1'] }, 5)
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     *
+     * @remarks
+     *
+     * For details about available filters, refer to {@link TweetFilter}
+     */
+    search(filter: ITweetFilter, 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
+     *
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Creating a function that streams all new tweets from the user 'user1'
+     * async function streamTweets() {
+     * 	try {
+     * 		// Awaiting for the tweets returned by the AsyncGenerator returned by the method
+     * 		for await (const tweet of rettiwt.tweet.stream({ fromUsers: ['user1'] }, 5000)) {
+     * 			console.log(tweet.fullText);
+     * 		}
+     * 	}
+     * 	catch (err) {
+     * 		console.log(err);
+     * 	}
+     * }
+     *
+     * // Calling the function
+     * streamTweets();
+     * ```
+     */
+    stream(filter: ITweetFilter, pollingInterval?: number): AsyncGenerator<Tweet>;
+    /**
+     * Unbookmark a tweet.
+     *
+     * @param id - The ID of the target tweet.
+     *
+     * @returns Whether unbookmarking was successful or not.
+     *
+     * @example
+     *
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Unbookmarking the tweet with id '1234567890'
+     * rettiwt.tweet.unbookmark('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     */
+    unbookmark(id: string): Promise<boolean>;
+    /**
+     * Unlike a tweet.
+     *
+     * @param id - The ID of the target tweet.
+     *
+     * @returns Whether unliking was successful or not.
+     *
+     * @example
+     *
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Unliking the Tweet with id '1234567890'
+     * rettiwt.tweet.unlike('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     */
+    unlike(id: string): Promise<boolean>;
+    /**
+     * Unpost a tweet.
+     *
+     * @param id - The ID of the target tweet.
+     *
+     * @returns Whether unposting was successful or not.
+     *
+     * @example
+     *
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Unposting the Tweet with id '1234567890'
+     * rettiwt.tweet.unpost('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     */
+    unpost(id: string): Promise<boolean>;
+    /**
+     * Unretweet a tweet.
+     *
+     * @param id - The ID of the target tweet.
+     *
+     * @returns Whether unretweeting was successful or not.
+     *
+     * @example
+     *
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Unretweeting the Tweet with id '1234567890'
+     * rettiwt.tweet.unretweet('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     */
+    unretweet(id: string): Promise<boolean>;
+    /**
+     * Unschedule a tweet.
+     *
+     * @param id - The ID of the scheduled tweet.
+     *
+     * @returns Whether unscheduling was successful or not.
+     *
+     * @example
+     *
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Unscheduling the Tweet with id '1234567890'
+     * rettiwt.tweet.unschedule('1234567890')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     */
+    unschedule(id: string): Promise<boolean>;
+    /**
+     * Upload a media file to Twitter.
+     *
+     * @param media - The path or ArrayBuffer to the media file to upload.
+     *
+     * @returns The ID of the uploaded media.
+     *
+     * @example
+     *
+     * ```ts
+     * import { Rettiwt } from 'rettiwt-api';
+     *
+     * // Creating a new Rettiwt instance using the given 'API_KEY'
+     * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+     *
+     * // Uploading a file called mountains.jpg
+     * rettiwt.tweet.upload('mountains.jpg')
+     * .then(res => {
+     * 	console.log(res);
+     * })
+     * .catch(err => {
+     * 	console.log(err);
+     * });
+     * ```
+     *
+     * @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 or Blob containing the media can also be uploaded.
+     */
+    upload(media: string | ArrayBuffer | Blob): Promise<string>;
+}