twitter-api-v2
Version:
Strongly typed, full-featured, light, versatile yet powerful Twitter API v1.1 and v2 client for Node.js.
371 lines (370 loc) • 16.5 kB
JavaScript
"use strict";
var __importDefault = (this && this.__importDefault) || function (mod) {
return (mod && mod.__esModule) ? mod : { "default": mod };
};
Object.defineProperty(exports, "__esModule", { value: true });
const client_subclient_1 = __importDefault(require("../client.subclient"));
const globals_1 = require("../globals");
const paginators_1 = require("../paginators");
const client_v2_labs_read_1 = __importDefault(require("../v2-labs/client.v2.labs.read"));
const user_paginator_v2_1 = require("../paginators/user.paginator.v2");
const helpers_1 = require("../helpers");
/**
* Base Twitter v2 client with only read right.
*/
class TwitterApiv2ReadOnly extends client_subclient_1.default {
constructor() {
super(...arguments);
this._prefix = globals_1.API_V2_PREFIX;
}
/* Sub-clients */
/**
* Get a client for v2 labs endpoints.
*/
get labs() {
if (this._labs)
return this._labs;
return this._labs = new client_v2_labs_read_1.default(this);
}
/* Tweets */
/**
* The recent search endpoint returns Tweets from the last seven days that match a search query.
* https://developer.twitter.com/en/docs/twitter-api/tweets/search/api-reference/get-tweets-search-recent
*/
async search(query, options = {}) {
const queryParams = { ...options, query };
const initialRq = await this.get('tweets/search/recent', queryParams, { fullResponse: true });
return new paginators_1.TweetSearchRecentV2Paginator({
realData: initialRq.data,
rateLimit: initialRq.rateLimit,
instance: this,
queryParams,
});
}
/**
* The full-archive search endpoint returns the complete history of public Tweets matching a search query;
* since the first Tweet was created March 26, 2006.
*
* This endpoint is only available to those users who have been approved for the Academic Research product track.
* https://developer.twitter.com/en/docs/twitter-api/tweets/search/api-reference/get-tweets-search-all
*/
async searchAll(query, options = {}) {
const queryParams = { ...options, query };
const initialRq = await this.get('tweets/search/all', queryParams, { fullResponse: true });
return new paginators_1.TweetSearchAllV2Paginator({
realData: initialRq.data,
rateLimit: initialRq.rateLimit,
instance: this,
queryParams,
});
}
/**
* Returns a variety of information about a single Tweet specified by the requested ID.
* https://developer.twitter.com/en/docs/twitter-api/tweets/lookup/api-reference/get-tweets-id
*
* OAuth2 scope: `users.read`, `tweet.read`
*/
singleTweet(tweetId, options = {}) {
return this.get('tweets/:id', options, { params: { id: tweetId } });
}
/**
* Returns a variety of information about tweets specified by list of IDs.
* https://developer.twitter.com/en/docs/twitter-api/tweets/lookup/api-reference/get-tweets
*
* OAuth2 scope: `users.read`, `tweet.read`
*/
tweets(tweetIds, options = {}) {
return this.get('tweets', { ids: tweetIds, ...options });
}
/**
* The recent Tweet counts endpoint returns count of Tweets from the last seven days that match a search query.
* OAuth2 Bearer auth only.
* https://developer.twitter.com/en/docs/twitter-api/tweets/counts/api-reference/get-tweets-counts-recent
*/
tweetCountRecent(query, options = {}) {
return this.get('tweets/counts/recent', { query, ...options });
}
/**
* This endpoint is only available to those users who have been approved for the Academic Research product track.
* The full-archive search endpoint returns the complete history of public Tweets matching a search query;
* since the first Tweet was created March 26, 2006.
* OAuth2 Bearer auth only.
* **This endpoint has pagination, yet it is not supported by bundled paginators. Use `next_token` to fetch next page.**
* https://developer.twitter.com/en/docs/twitter-api/tweets/counts/api-reference/get-tweets-counts-all
*/
tweetCountAll(query, options = {}) {
return this.get('tweets/counts/all', { query, ...options });
}
/**
* Allows you to get information about who has Retweeted a Tweet.
* https://developer.twitter.com/en/docs/twitter-api/tweets/retweets/api-reference/get-tweets-id-retweeted_by
*/
tweetRetweetedBy(tweetId, options = {}) {
return this.get('tweets/:id/retweeted_by', options, { params: { id: tweetId } });
}
/**
* Allows you to get information about who has Liked a Tweet.
* https://developer.twitter.com/en/docs/twitter-api/tweets/likes/api-reference/get-tweets-id-liking_users
*/
tweetLikedBy(tweetId, options = {}) {
return this.get('tweets/:id/liking_users', options, { params: { id: tweetId } });
}
/**
* Returns Tweets composed by a single user, specified by the requested user ID.
* By default, the most recent ten Tweets are returned per request.
* Using pagination, the most recent 3,200 Tweets can be retrieved.
* https://developer.twitter.com/en/docs/twitter-api/tweets/timelines/api-reference/get-users-id-tweets
*/
async userTimeline(userId, options = {}) {
const initialRq = await this.get('users/:id/tweets', options, {
fullResponse: true,
params: { id: userId },
});
return new paginators_1.TweetUserTimelineV2Paginator({
realData: initialRq.data,
rateLimit: initialRq.rateLimit,
instance: this,
queryParams: options,
sharedParams: { id: userId },
});
}
/**
* Returns Tweets mentioning a single user specified by the requested user ID.
* By default, the most recent ten Tweets are returned per request.
* Using pagination, up to the most recent 800 Tweets can be retrieved.
* https://developer.twitter.com/en/docs/twitter-api/tweets/timelines/api-reference/get-users-id-mentions
*/
async userMentionTimeline(userId, options = {}) {
const initialRq = await this.get('users/:id/mentions', options, {
fullResponse: true,
params: { id: userId },
});
return new paginators_1.TweetUserMentionTimelineV2Paginator({
realData: initialRq.data,
rateLimit: initialRq.rateLimit,
instance: this,
queryParams: options,
sharedParams: { id: userId },
});
}
/* Users */
/**
* Returns a variety of information about a single user specified by the requested ID.
* https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-id
*/
user(userId, options = {}) {
return this.get('users/:id', options, { params: { id: userId } });
}
/**
* Returns a variety of information about one or more users specified by the requested IDs.
* https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users
*/
users(userIds, options = {}) {
const ids = Array.isArray(userIds) ? userIds.join(',') : userIds;
return this.get('users', { ...options, ids });
}
/**
* Returns a variety of information about a single user specified by their username.
* https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-by-username-username
*/
userByUsername(username, options = {}) {
return this.get('users/by/username/:username', options, { params: { username } });
}
/**
* Returns a variety of information about one or more users specified by their usernames.
* https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-by
*
* OAuth2 scope: `users.read`, `tweet.read`
*/
usersByUsernames(usernames, options = {}) {
usernames = Array.isArray(usernames) ? usernames.join(',') : usernames;
return this.get('users/by', { ...options, usernames });
}
async followers(userId, options = {}) {
const { asPaginator, ...parameters } = options;
const params = { id: userId };
if (!asPaginator) {
return this.get('users/:id/followers', parameters, { params });
}
const initialRq = await this.get('users/:id/followers', parameters, { fullResponse: true, params });
return new user_paginator_v2_1.UserFollowersV2Paginator({
realData: initialRq.data,
rateLimit: initialRq.rateLimit,
instance: this,
queryParams: parameters,
sharedParams: params,
});
}
async following(userId, options = {}) {
const { asPaginator, ...parameters } = options;
const params = { id: userId };
if (!asPaginator) {
return this.get('users/:id/following', parameters, { params });
}
const initialRq = await this.get('users/:id/following', parameters, { fullResponse: true, params });
return new user_paginator_v2_1.UserFollowingV2Paginator({
realData: initialRq.data,
rateLimit: initialRq.rateLimit,
instance: this,
queryParams: parameters,
sharedParams: params,
});
}
/**
* Allows you to get information about a user’s liked Tweets.
* https://developer.twitter.com/en/docs/twitter-api/tweets/likes/api-reference/get-users-id-liked_tweets
*/
async userLikedTweets(userId, options = {}) {
const params = { id: userId };
const initialRq = await this.get('users/:id/liked_tweets', options, { fullResponse: true, params });
return new paginators_1.TweetV2UserLikedTweetsPaginator({
realData: initialRq.data,
rateLimit: initialRq.rateLimit,
instance: this,
queryParams: { ...options },
sharedParams: params,
});
}
/**
* Returns a list of users who are blocked by the authenticating user.
* https://developer.twitter.com/en/docs/twitter-api/users/blocks/api-reference/get-users-blocking
*/
async userBlockingUsers(userId, options = {}) {
const params = { id: userId };
const initialRq = await this.get('users/:id/blocking', options, { fullResponse: true, params });
return new user_paginator_v2_1.UserBlockingUsersV2Paginator({
realData: initialRq.data,
rateLimit: initialRq.rateLimit,
instance: this,
queryParams: { ...options },
sharedParams: params,
});
}
/**
* Returns a list of users who are muted by the authenticating user.
* https://developer.twitter.com/en/docs/twitter-api/users/mutes/api-reference/get-users-muting
*/
async userMutingUsers(userId, options = {}) {
const params = { id: userId };
const initialRq = await this.get('users/:id/muting', options, { fullResponse: true, params });
return new user_paginator_v2_1.UserMutingUsersV2Paginator({
realData: initialRq.data,
rateLimit: initialRq.rateLimit,
instance: this,
queryParams: { ...options },
sharedParams: params,
});
}
/* Spaces */
/**
* Get a single space by ID.
* https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-id
*
* OAuth2 scopes: `tweet.read`, `users.read`, `space.read`.
*/
space(spaceId, options = {}) {
return this.get('spaces/:id', options, { params: { id: spaceId } });
}
/**
* Get spaces using their IDs.
* https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces
*
* OAuth2 scopes: `tweet.read`, `users.read`, `space.read`.
*/
spaces(spaceIds, options = {}) {
return this.get('spaces', { ids: spaceIds, ...options });
}
/**
* Get spaces using their creator user ID(s). (no pagination available)
* https://developer.twitter.com/en/docs/twitter-api/spaces/lookup/api-reference/get-spaces-by-creator-ids
*
* OAuth2 scopes: `tweet.read`, `users.read`, `space.read`.
*/
spacesByCreators(creatorIds, options = {}) {
return this.get('spaces/by/creator_ids', { user_ids: creatorIds, ...options });
}
/**
* Search through spaces using multiple params. (no pagination available)
* https://developer.twitter.com/en/docs/twitter-api/spaces/search/api-reference/get-spaces-search
*/
searchSpaces(options) {
return this.get('spaces/search', options);
}
searchStream({ autoConnect, ...options } = {}) {
return this.getStream('tweets/search/stream', options, { payloadIsError: helpers_1.isTweetStreamV2ErrorPayload, autoConnect });
}
/**
* Return a list of rules currently active on the streaming endpoint, either as a list or individually.
* https://developer.twitter.com/en/docs/twitter-api/tweets/filtered-stream/api-reference/get-tweets-search-stream-rules
*/
streamRules(options = {}) {
return this.get('tweets/search/stream/rules', options);
}
updateStreamRules(options, query = {}) {
return this.post('tweets/search/stream/rules', options, { query });
}
sampleStream({ autoConnect, ...options } = {}) {
return this.getStream('tweets/sample/stream', options, { payloadIsError: helpers_1.isTweetStreamV2ErrorPayload, autoConnect });
}
/* Batch compliance */
/**
* Returns a list of recent compliance jobs.
* https://developer.twitter.com/en/docs/twitter-api/compliance/batch-compliance/api-reference/get-compliance-jobs
*/
complianceJobs(options) {
return this.get('compliance/jobs', options);
}
/**
* Get a single compliance job with the specified ID.
* https://developer.twitter.com/en/docs/twitter-api/compliance/batch-compliance/api-reference/get-compliance-jobs-id
*/
complianceJob(jobId) {
return this.get('compliance/jobs/:id', undefined, { params: { id: jobId } });
}
/**
* Creates a new compliance job for Tweet IDs or user IDs, send your file, await result and parse it into an array.
* You can run one batch job at a time. Returns the created job, but **not the job result!**.
*
* You can obtain the result (**after job is completed**) with `.complianceJobResult`.
* https://developer.twitter.com/en/docs/twitter-api/compliance/batch-compliance/api-reference/post-compliance-jobs
*/
async sendComplianceJob(jobParams) {
const job = await this.post('compliance/jobs', { type: jobParams.type, name: jobParams.name });
// Send the IDs
const rawIdsBody = jobParams.ids instanceof Buffer ? jobParams.ids : Buffer.from(jobParams.ids.join('\n'));
// Upload the IDs
await this.put(job.data.upload_url, rawIdsBody, {
forceBodyMode: 'raw',
enableAuth: false,
headers: { 'Content-Type': 'text/plain' },
prefix: '',
});
return job;
}
/**
* Get the result of a running or completed job, obtained through `.complianceJob`, `.complianceJobs` or `.sendComplianceJob`.
* If job is still running (`in_progress`), it will await until job is completed. **This could be quite long!**
* https://developer.twitter.com/en/docs/twitter-api/compliance/batch-compliance/api-reference/post-compliance-jobs
*/
async complianceJobResult(job) {
let runningJob = job;
while (runningJob.status !== 'complete') {
if (runningJob.status === 'expired' || runningJob.status === 'failed') {
throw new Error('Job failed to be completed.');
}
await new Promise(resolve => setTimeout(resolve, 3500));
runningJob = (await this.complianceJob(job.id)).data;
}
// Download and parse result
const result = await this.get(job.download_url, undefined, {
enableAuth: false,
prefix: '',
});
return result
.trim()
.split('\n')
.filter(line => line)
.map(line => JSON.parse(line));
}
}
exports.default = TwitterApiv2ReadOnly;