rettiwt-api 5.0.0-alpha.1 → 5.0.0-alpha.2

package/src/enums/Authentication.ts

@@ -1,19 +1,10 @@
 /**
  * The different types of authentication for authenticating against Twitter.
+ *
+ * @public
  */
 export enum EAuthenticationType {
 	GUEST = 'GUEST',
 	USER = 'USER',
 	LOGIN = 'LOGIN',
 }
-
-/**
- * Different types of error messages related to authentication returned by services.
- */
-export enum EAuthenticationErrors {
-	NOT_AUTHENTICATED = 'Cannot fetch this data without authentication',
-	INVALID_EMAIL = 'No Twitter account found for the given email address',
-	INVALID_USERNAME = 'Incorrect username given for the given Twitter account',
-	INVALID_PASSWORD = 'Incorrect password given for the given Twitter account',
-	AUTHENTICATION_FAILED = 'Failed to authenticate using the given account Credentials',
-}

package/src/enums/Data.ts

@@ -4,20 +4,7 @@
  * @internal
  */
 export enum EBaseType {
-	NOTIFICATION = 'Notification',
-	TWEET = 'Tweet',
-	USER = 'User',
-}
-
-/**
- * The different types of notifications.
- *
- * @public
- */
-export enum ENotificationType {
-	RECOMMENDATION = 'RECOMMENDATION',
-	INFORMATION = 'INFORMATION',
-	LIVE = 'LIVE',
-	ALERT = 'ALERT',
-	UNDEFINED = 'UNDEFINED',
+	NOTIFICATION = 'NOTIFICATION',
+	TWEET = 'TWEET',
+	USER = 'USER',
 }

package/src/enums/Media.ts

@@ -0,0 +1,10 @@
+/**
+ * The different types of media items.
+ *
+ * @public
+ */
+export enum EMediaType {
+	PHOTO = 'PHOTO',
+	VIDEO = 'VIDEO',
+	GIF = 'GIF',
+}

package/src/enums/Notification.ts

@@ -0,0 +1,12 @@
+/**
+ * The different types of notifications.
+ *
+ * @public
+ */
+export enum ENotificationType {
+	RECOMMENDATION = 'RECOMMENDATION',
+	INFORMATION = 'INFORMATION',
+	LIVE = 'LIVE',
+	ALERT = 'ALERT',
+	UNDEFINED = 'UNDEFINED',
+}

package/src/enums/Resource.ts

@@ -16,7 +16,9 @@ export enum EResourceType {
 	// TWEET
 	TWEET_DETAILS = 'TWEET_DETAILS',
 	TWEET_DETAILS_ALT = 'TWEET_DETAILS_ALT',
+	TWEET_DETAILS_BULK = 'TWEET_DETAILS_BULK',
 	TWEET_LIKE = 'TWEET_LIKE',
+	TWEET_LIKERS = 'TWEET_LIKERS',
 	TWEET_POST = 'TWEET_POST',
 	TWEET_REPLIES = 'TWEET_REPLIES',
 	TWEET_RETWEET = 'TWEET_RETWEET',
@@ -32,6 +34,7 @@ export enum EResourceType {
 	USER_BOOKMARKS = 'USER_BOOKMARKS',
 	USER_DETAILS_BY_USERNAME = 'USER_DETAILS_BY_USERNAME',
 	USER_DETAILS_BY_ID = 'USER_DETAILS_BY_ID',
+	USER_DETAILS_BY_IDS_BULK = 'USER_DETAILS_BY_IDS_BULK',
 	USER_FEED_FOLLOWED = 'USER_FEED_FOLLOWED',
 	USER_FEED_RECOMMENDED = 'USER_FEED_RECOMMENDED',
 	USER_FOLLOW = 'USER_FOLLOW',

package/src/enums/raw/Analytics.ts

@@ -0,0 +1,29 @@
+/**
+ * Granularity types for analytics.
+ *
+ * @public
+ */
+export enum ERawAnalyticsGranularity {
+	DAILY = 'Daily',
+	WEEKLY = 'Weekly',
+	MONTHLY = 'Monthly',
+}
+
+/**
+ * The different types of metric someone can request.
+ *
+ * @public
+ */
+export enum ERawAnalyticsMetric {
+	ENGAGEMENTS = 'Engagements',
+	IMPRESSIONS = 'Impressions',
+	PROFILE_VISITS = 'ProfileVisits',
+	FOLLOWS = 'Follows',
+	VIDEO_VIEWS = 'VideoViews',
+	REPLIES = 'Replies',
+	LIKES = 'Likes',
+	RETWEETS = 'Retweets',
+	MEDIA_VIEWS = 'MediaViews',
+	BOOKMARK = 'Bookmark',
+	SHARE = 'Share',
+}

package/src/enums/raw/Media.ts

@@ -0,0 +1,10 @@
+/**
+ * The different types of media items.
+ *
+ * @public
+ */
+export enum ERawMediaType {
+	PHOTO = 'photo',
+	VIDEO = 'video',
+	GIF = 'animated_gif',
+}

package/src/enums/raw/Notification.ts

@@ -0,0 +1,11 @@
+/**
+ * The different types of notifications.
+ *
+ * @public
+ */
+export enum ERawNotificationType {
+	RECOMMENDATION = 'recommendation_icon',
+	INFORMATION = 'bird_icon',
+	LIVE = 'live_icon',
+	ALERT = 'bell_icon',
+}

package/src/enums/raw/Tweet.ts

@@ -0,0 +1,9 @@
+/**
+ * The different types of search results when searching for Tweets.
+ *
+ * @public
+ */
+export enum ERawTweetSearchResultType {
+	LATEST = 'Latest',
+	TOP = 'Top',
+}

package/src/helper/TidUtils.ts

@@ -0,0 +1,189 @@
+import { createHash } from 'node:crypto';
+
+import { ITidParams } from '../types/auth/TidParams';
+
+export function calculateClientTransactionIdHeader(args: ITidParams): string {
+	const time = Math.floor(((args.time || Date.now()) - 1682924400 * 1000) / 1000);
+	const timeBuffer = new Uint8Array(new Uint32Array([time]).buffer);
+
+	const keyBytes = Array.from(Buffer.from(args.verificationKey, 'base64'));
+	const animationKey = args.animationKey || getAnimationKey(keyBytes, args.frames, args.indices);
+
+	const value = [args.method, args.path, time].join('!') + args.keyword + animationKey;
+	const valueEncoded = new TextEncoder().encode(value);
+
+	const hash = createHash('sha-256').update(valueEncoded).digest();
+	const hashBytes = Array.from(new Uint8Array(hash));
+
+	const xorByte = args.xorByte || Math.floor(Math.random() * 256);
+
+	const bytes = new Uint8Array(keyBytes.concat(Array.from(timeBuffer), hashBytes.slice(0, 16), [args.extraByte]));
+	return encode(xor(xorByte, bytes));
+}
+
+function getAnimationKey(keyBytes: number[], frames: number[][][], indices: number[]): string {
+	const totalTime = 4096;
+	const rowIndex = keyBytes[indices[0]] % 16;
+	const frameTime = indices
+		.slice(1)
+		.map((idx) => keyBytes[idx] % 16)
+		.reduce((a, b) => a * b, 1);
+	const targetTime = frameTime / totalTime;
+	const frameRow = frames[keyBytes[5] % 4][rowIndex];
+	return animate(frameRow, targetTime);
+}
+
+function animate(frameRow: number[], targetTime: number): string {
+	const curves = frameRow.slice(7).map((v, i) => Number(a(v, b(i), 1).toFixed(2)));
+	const cubicValue = getCubicCurveValue(curves, targetTime);
+
+	const fromColor = [...frameRow.slice(0, 3), 1];
+	const toColor = [...frameRow.slice(3, 6), 1];
+	const color = interpolate(fromColor, toColor, cubicValue);
+
+	const fromRotation = [0];
+	const toRotation = [Math.floor(a(frameRow[6], 60, 360))];
+	const rotation = interpolate(fromRotation, toRotation, cubicValue);
+	const matrix = convertRotationToMatrix(rotation[0]);
+
+	const strArray: string[] = [];
+	for (let i = 0; i < color.length - 1; i++) {
+		strArray.push(Math.round(color[i]).toString(16));
+	}
+
+	for (let i = 0; i < matrix.length; i++) {
+		let rounded = Number(matrix[i].toFixed(2));
+		if (rounded < 0) {
+			rounded = -rounded;
+		}
+		const hexValue = floatToHex(rounded);
+		if (hexValue.startsWith('.')) {
+			strArray.push('0' + hexValue);
+		} else if (hexValue) {
+			strArray.push(hexValue);
+		} else {
+			strArray.push('0');
+		}
+	}
+
+	strArray.push('0', '0');
+	return strArray.join('').replace(/[.-]/g, '').toLowerCase();
+}
+
+function a(b: number, c: number, d: number): number {
+	return (b * (d - c)) / 255 + c;
+}
+
+function b(a: number): number {
+	return a % 2 === 1 ? -1 : 0;
+}
+
+function getCubicCurveValue(curves: number[], time: number): number {
+	let startGradient = 0;
+	let endGradient = 0;
+
+	if (time <= 0) {
+		if (curves[0] > 0) {
+			startGradient = curves[1] / curves[0];
+		} else if (curves[1] === 0 && curves[2] > 0) {
+			startGradient = curves[3] / curves[2];
+		}
+		return startGradient * time;
+	}
+
+	if (time >= 1) {
+		if (curves[2] < 1) {
+			endGradient = (curves[3] - 1) / (curves[2] - 1);
+		} else if (curves[2] === 1 && curves[0] < 1) {
+			endGradient = (curves[1] - 1) / (curves[0] - 1);
+		}
+		return 1 + endGradient * (time - 1);
+	}
+
+	let start = 0;
+	let end = 1;
+	let mid = 0;
+
+	while (start < end) {
+		mid = (start + end) / 2;
+		const xEst = calculateBezier(curves[0], curves[2], mid);
+		if (Math.abs(time - xEst) < 0.00001) {
+			return calculateBezier(curves[1], curves[3], mid);
+		}
+		if (xEst < time) {
+			start = mid;
+		} else {
+			end = mid;
+		}
+	}
+
+	return calculateBezier(curves[1], curves[3], mid);
+}
+
+function calculateBezier(a: number, b: number, m: number): number {
+	return 3 * a * (1 - m) * (1 - m) * m + 3 * b * (1 - m) * m * m + m * m * m;
+}
+
+function interpolate(from: number[], to: number[], f: number): number[] {
+	const out: number[] = [];
+	for (let i = 0; i < from.length; i++) {
+		out.push(from[i] * (1 - f) + to[i] * f);
+	}
+	return out;
+}
+
+function convertRotationToMatrix(degrees: number): number[] {
+	const radians = (degrees * Math.PI) / 180;
+	const c = Math.cos(radians);
+	const s = Math.sin(radians);
+	return [c, -s, s, c];
+}
+
+function floatToHex(x: number): string {
+	const result: string[] = [];
+	let quotient = Math.floor(x);
+	let fraction = x - quotient;
+
+	while (quotient > 0) {
+		const remainder = quotient % 16;
+		quotient = Math.floor(quotient / 16);
+
+		if (remainder > 9) {
+			result.unshift(String.fromCharCode(remainder + 55));
+		} else {
+			result.unshift(remainder.toString());
+		}
+	}
+
+	if (fraction === 0) {
+		return result.join('');
+	}
+
+	result.push('.');
+
+	while (fraction > 0) {
+		fraction *= 16;
+		const integer = Math.floor(fraction);
+		fraction -= integer;
+
+		if (integer > 9) {
+			result.push(String.fromCharCode(integer + 55));
+		} else {
+			result.push(integer.toString());
+		}
+	}
+
+	return result.join('');
+}
+
+function xor(xorByte: number, data: Uint8Array): Uint8Array {
+	return new Uint8Array([xorByte, ...data.map((v) => v ^ xorByte)]);
+}
+
+function encode(data: Uint8Array): string {
+	return btoa(
+		Array.from(data)
+			.map((v) => String.fromCharCode(v))
+			.join(''),
+	).replaceAll('=', '');
+}

package/src/index.ts

@@ -2,69 +2,104 @@
 export * from './Rettiwt';
 
 // ENUMS
+export * from './enums/raw/Analytics';
+export * from './enums/raw/Media';
+export * from './enums/raw/Notification';
+export * from './enums/raw/Tweet';
 export * from './enums/Api';
+export * from './enums/Authentication';
+export * from './enums/Data';
 export * from './enums/Http';
+export * from './enums/Logging';
+export * from './enums/Media';
+export * from './enums/Notification';
 export * from './enums/Resource';
 
-// ARG MODELS
+// MODELS
 export * from './models/args/FetchArgs';
 export * from './models/args/PostArgs';
-
-// DATA MODELS
 export * from './models/data/CursoredData';
 export * from './models/data/List';
 export * from './models/data/Notification';
 export * from './models/data/Tweet';
 export * from './models/data/User';
-
-// ERROR MODELS
 export * from './models/errors/ApiError';
 export * from './models/errors/HttpError';
 export * from './models/errors/RettiwtError';
 export * from './models/errors/TimeoutError';
 
+// REQUESTS
+export * from './requests/List';
+export * from './requests/Media';
+export * from './requests/Tweet';
+export * from './requests/User';
+
 // SERVICES
-export * from './services/internal/AuthService';
 export * from './services/public/FetcherService';
+export * from './services/public/ListService';
 export * from './services/public/TweetService';
 export * from './services/public/UserService';
 
 // TYPES
-export * from './types/RettiwtConfig';
+export * from './types/args/FetchArgs';
+export * from './types/args/PostArgs';
+export * from './types/auth/TidProvider';
+export * from './types/data/CursoredData';
+export * from './types/data/List';
+export * from './types/data/Notification';
+export * from './types/data/Tweet';
+export * from './types/data/User';
+export * from './types/params/Variables';
+export { IAnalytics as IRawAnalytics } from './types/raw/base/Analytic';
+export { ICursor as IRawCursor } from './types/raw/base/Cursor';
+export { ILimitedVisibilityTweet as IRawLimitedVisibilityTweet } from './types/raw/base/LimitedVisibilityTweet';
+export { IList as IRawList } from './types/raw/base/List';
+export { IMedia as IRawMedia } from './types/raw/base/Media';
+export { INotification as IRawNotification } from './types/raw/base/Notification';
+export { ISpace as IRawSpace } from './types/raw/base/Space';
+export { ITweet as IRawTweet } from './types/raw/base/Tweet';
+export { IUser as IRawUser } from './types/raw/base/User';
+export { IDataResult as IRawDataResult } from './types/raw/composite/DataResult';
+export { ITimelineTweet as IRawTimelineTweet } from './types/raw/composite/TimelineTweet';
+export { ITimelineUser as IRawTimelineUser } from './types/raw/composite/TimelineUser';
+export { IError as IRawError } from './types/raw/generic/Error';
+export { IResponse as IRawResponse } from './types/raw/generic/Response';
+export { IListDetailsResponse as IRawListDetailsResponse } from './types/raw/list/Details';
+export { IListMembersResponse as IRawListMembersResponse } from './types/raw/list/Members';
+export { IListTweetsResponse as IRawListTweetsResponse } from './types/raw/list/Tweets';
+export { IMediaFinalizeUploadResponse as IRawMediaFinalizeUploadResponse } from './types/raw/media/FinalizeUpload';
+export { IMediaInitializeUploadResponse as IRawMediaInitializeUploadResponse } from './types/raw/media/InitalizeUpload';
+export { IMediaLiveVideoStreamResponse as IRawMediaLiveVideoStreamResponse } from './types/raw/media/LiveVideoStream';
+export { ITweetDetailsResponse as IRawTweetDetailsResponse } from './types/raw/tweet/Details';
+export { ITweetLikeResponse as IRawTweetLikeResponse } from './types/raw/tweet/Like';
+export { ITweetLikersResponse as IRawTweetLikersResponse } from './types/raw/tweet/Likers';
+export { ITweetPostResponse as IRawTweetPostResponse } from './types/raw/tweet/Post';
+export { ITweetRepliesResponse as IRawTweetRepliesResponse } from './types/raw/tweet/Replies';
+export { ITweetRetweetResponse as IRawTweetRetweetResponse } from './types/raw/tweet/Retweet';
+export { ITweetRetweetersResponse as IRawTweetRetweetersResponse } from './types/raw/tweet/Retweeters';
+export { ITweetScheduleResponse as IRawTweetScheduleResponse } from './types/raw/tweet/Schedule';
+export { ITweetSearchResponse as IRawTweetSearchResponse } from './types/raw/tweet/Search';
+export { ITweetUnlikeResponse as IRawTweetUnlikeResponse } from './types/raw/tweet/Unlike';
+export { ITweetUnpostResponse as IRawTweetUnpostResponse } from './types/raw/tweet/Unpost';
+export { ITweetUnretweetResponse as IRawTweetUnretweetResponse } from './types/raw/tweet/Unretweet';
+export { ITweetUnscheduleResponse as ITRawTweetUnscheduleResponse } from './types/raw/tweet/Unschedule';
+export { IUserAffiliatesResponse as IRawUserAffiliatesResponse } from './types/raw/user/Affiliates';
+export { IUserAnalyticsResponse as IRawUserAnalyticsResponse } from './types/raw/user/Analytics';
+export { IUserBookmarksResponse as IRawUserBookmarksResponse } from './types/raw/user/Bookmarks';
+export { IUserDetailsResponse as IRawUserDetailsResponse } from './types/raw/user/Details';
+export { IUserFollowResponse as IRawUserFollowResponse } from './types/raw/user/Follow';
+export { IUserFollowedResponse as IRawUserFollowedResponse } from './types/raw/user/Followed';
+export { IUserFollowersResponse as IRawUserFollowersResponse } from './types/raw/user/Followers';
+export { IUserFollowingResponse as IRawUserFollowingResponse } from './types/raw/user/Following';
+export { IUserHighlightsResponse as IRawUserHighlightsResponse } from './types/raw/user/Highlights';
+export { IUserLikesResponse as IRawUserLikesResponse } from './types/raw/user/Likes';
+export { IUserMediaResponse as IRawUserMediaResponse } from './types/raw/user/Media';
+export { IUserNotificationsResponse as IRawUserNotificationsResponse } from './types/raw/user/Notifications';
+export { IUserRecommendedResponse as IRawUserRecommendedResponse } from './types/raw/user/Recommended';
+export { IUserScheduledResponse as IRawUserScheduledResponse } from './types/raw/user/Scheduled';
+export { IUserSubscriptionsResponse as IRawUserSubscriptionsResponse } from './types/raw/user/Subscriptions';
+export { IUserTweetsResponse as IRawUserTweetsResponse } from './types/raw/user/Tweets';
+export { IUserTweetsAndRepliesResponse as IRawUserTweetsAndRepliesResponse } from './types/raw/user/TweetsAndReplies';
+export { IUserUnfollowResponse as IRawUserUnfollowResponse } from './types/raw/user/Unfollow';
 export * from './types/ErrorHandler';
-
-// RAW TYPES
-export {
-	IInitializeMediaUploadResponse,
-	IListMembersResponse,
-	IListTweetsResponse,
-	ITweetDetailsResponse,
-	ITweetLikeResponse,
-	ITweetPostResponse,
-	ITweetRepliesResponse,
-	ITweetRetweetersResponse,
-	ITweetRetweetResponse,
-	ITweetScheduleResponse,
-	ITweetSearchResponse,
-	ITweetUnlikeResponse,
-	ITweetUnpostResponse,
-	ITweetUnscheduleResponse,
-	ITweetUnretweetResponse,
-} from 'rettiwt-core';
-export {
-	IUserBookmarksResponse,
-	IUserDetailsResponse,
-	IUserFollowedResponse,
-	IUserFollowersResponse,
-	IUserFollowingResponse,
-	IUserFollowResponse,
-	IUserHighlightsResponse,
-	IUserLikesResponse,
-	IUserMediaResponse,
-	IUserNotificationsResponse,
-	IUserRecommendedResponse,
-	IUserSubscriptionsResponse,
-	IUserTweetsAndRepliesResponse,
-	IUserTweetsResponse,
-	IUserUnfollowResponse,
-} from 'rettiwt-core';
+export * from './types/RettiwtConfig';

package/src/models/RettiwtConfig.ts

@@ -0,0 +1,64 @@
+import { Agent } from 'https';
+
+import { HttpsProxyAgent } from 'https-proxy-agent';
+
+import { AuthService } from '../services/internal/AuthService';
+import { ITidProvider } from '../types/auth/TidProvider';
+import { IErrorHandler } from '../types/ErrorHandler';
+import { IRettiwtConfig } from '../types/RettiwtConfig';
+
+export class RettiwtConfig implements IRettiwtConfig {
+	// Parameters for internal use
+	private _apiKey?: string;
+	private _httpsAgent: Agent;
+	private _userId: string | undefined;
+
+	// Parameters that can be set once, upon initialization
+	public readonly delay?: number | (() => number | Promise<number>);
+	public readonly errorHandler?: IErrorHandler;
+	public readonly logging?: boolean;
+	public readonly tidProvider?: ITidProvider;
+	public readonly timeout?: number;
+
+	// Parameters that can be changed on the fly
+	public headers?: { [key: string]: string };
+
+	/**
+	 * @param config - The config for Rettiwt of type {@link IRettiwtConfig}.
+	 */
+	public constructor(config?: IRettiwtConfig) {
+		this._apiKey = config?.apiKey;
+		this._httpsAgent = config?.proxyUrl ? new HttpsProxyAgent(config?.proxyUrl) : new Agent();
+		this._userId = config?.apiKey ? AuthService.getUserId(config?.apiKey) : undefined;
+		this.delay = config?.delay;
+		this.errorHandler = config?.errorHandler;
+		this.logging = config?.logging;
+		this.tidProvider = config?.tidProvider;
+		this.timeout = config?.timeout;
+		this.apiKey = config?.apiKey;
+		this.headers = config?.headers;
+	}
+
+	public get apiKey(): string | undefined {
+		return this._apiKey;
+	}
+
+	/** The HTTPS agent instance to use. */
+	public get httpsAgent(): Agent {
+		return this._httpsAgent;
+	}
+
+	/** The ID of the user associated with the API key, if any. */
+	public get userId(): string | undefined {
+		return this._userId;
+	}
+
+	public set apiKey(apiKey: string | undefined) {
+		this._apiKey = apiKey;
+		this._userId = apiKey ? AuthService.getUserId(apiKey) : undefined;
+	}
+
+	public set proxyUrl(proxyUrl: URL | undefined) {
+		this._httpsAgent = proxyUrl ? new HttpsProxyAgent(proxyUrl) : new Agent();
+	}
+}