@glagan/rettiwt-api 7.0.0

package/src/services/internal/AuthService.ts

@@ -0,0 +1,115 @@
+import { ofetch } from 'ofetch';
+
+import { ApiErrors } from '../../enums/Api';
+import { AuthCredential } from '../../models/auth/AuthCredential';
+import { RettiwtConfig } from '../../models/RettiwtConfig';
+
+/**
+ * The services that handles authentication.
+ *
+ * @internal
+ */
+export class AuthService {
+	/** The config object. */
+	private readonly _config: RettiwtConfig;
+
+	/**
+	 * @param config - The config for Rettiwt.
+	 */
+	public constructor(config: RettiwtConfig) {
+		this._config = config;
+	}
+
+	/**
+	 * Decodes the encoded cookie string.
+	 *
+	 * @param encodedCookies - The encoded cookie string to decode.
+	 * @returns The decoded cookie string.
+	 */
+	public static decodeCookie(encodedCookies: string): string {
+		// Decoding the encoded cookie string
+		const decodedCookies: string = Buffer.from(encodedCookies, 'base64').toString('ascii');
+
+		return decodedCookies;
+	}
+
+	/**
+	 * Encodes the given cookie string.
+	 *
+	 * @param cookieString - The cookie string to encode.
+	 * @returns The encoded cookie string.
+	 */
+	public static encodeCookie(cookieString: string): string {
+		// Encoding the cookie string to base64
+		const encodedCookies: string = Buffer.from(cookieString).toString('base64');
+
+		return encodedCookies;
+	}
+
+	/**
+	 * Gets the user's id from the given API key.
+	 *
+	 * @param apiKey - The API key.
+	 * @returns The user id associated with the API key.
+	 */
+	public static getUserId(apiKey: string): string {
+		// Getting the cookie string from the API key
+		const cookieString: string = AuthService.decodeCookie(apiKey);
+
+		// Searching for the user id in the cookie string
+		const searchResults: string[] | null = cookieString.match(
+			/((?<=twid="u=)(\d+)(?="))|((?<=twid=u%3D)(\d+)(?=;))/,
+		);
+
+		// If user id was found
+		if (searchResults) {
+			return searchResults[0];
+		}
+		// If user id was not found
+		else {
+			throw new Error(ApiErrors.BAD_AUTHENTICATION);
+		}
+	}
+
+	/**
+	 * Login to twitter as guest.
+	 *
+	 * @returns A new guest key.
+	 *
+	 * @example
+	 * ```
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance
+	 * const rettiwt = new Rettiwt();
+	 *
+	 * // Logging in an getting a new guest key
+	 * rettiwt.auth.guest()
+	 * .then(guestKey => {
+	 * 	// Use the guest key
+	 * 	...
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async guest(): Promise<AuthCredential> {
+		// Creating a new blank credential
+		const cred: AuthCredential = new AuthCredential();
+
+		// Getting the guest token
+		const data = await ofetch<{
+			/* eslint-disable @typescript-eslint/naming-convention */
+			guest_token: string;
+			/* eslint-enable @typescript-eslint/naming-convention */
+		}>('https://api.twitter.com/1.1/guest/activate.json', {
+			method: 'post',
+			headers: cred.toHeader(),
+			agent: this._config.httpsAgent,
+		});
+		cred.guestToken = data.guest_token;
+
+		return cred;
+	}
+}

package/src/services/internal/ErrorService.ts

@@ -0,0 +1,41 @@
+import { FetchError } from 'ofetch';
+
+import { TwitterError } from '../../models/errors/TwitterError';
+import { IErrorHandler } from '../../types/ErrorHandler';
+import { IErrorData as IRawErrorData, IErrorDetails as IRawErrorDetails } from '../../types/raw/base/Error';
+
+/**
+ * The base service that handles any errors.
+ *
+ * @public
+ */
+export class ErrorService implements IErrorHandler {
+	/**
+	 * Handles errors thrown by Twitter.
+	 *
+	 * @param error - The error response received from Twitter.
+	 */
+	private _handleFetchError(error: FetchError<IRawErrorData | IRawErrorDetails>): void {
+		throw new TwitterError(error);
+	}
+
+	/**
+	 * Handle unknown error.
+	 */
+	private _handleUnknownError(error: unknown): void {
+		throw error;
+	}
+
+	/**
+	 * The method called when an error response is received from Twitter API.
+	 *
+	 * @param error - The error caught while making HTTP request to Twitter API.
+	 */
+	public handle(error: unknown): void {
+		if (error instanceof FetchError) {
+			this._handleFetchError(error as FetchError<IRawErrorData | IRawErrorDetails>);
+		} else {
+			this._handleUnknownError(error);
+		}
+	}
+}

package/src/services/internal/LogService.ts

@@ -0,0 +1,34 @@
+import { LogActions } from '../../enums/Logging';
+
+/**
+ * Handles logging of data for debug purpose.
+ *
+ * @internal
+ */
+export class LogService {
+	/** Whether logging is enabled or not. */
+	public static enabled = false;
+
+	/**
+	 * Logs the given data.
+	 *
+	 * @param action - The action to be logged.
+	 *
+	 * @param data - The data to be logged.
+	 */
+	public static log(action: LogActions, data: NonNullable<unknown>): void {
+		// Proceed to log only if logging is enabled
+		if (this.enabled) {
+			// Preparing the log message
+			const logPrefix = 'Rettiwt-API';
+			const logTime: string = new Date().toISOString();
+			const logAction: string = action;
+			const logData: string = JSON.stringify(data);
+
+			const logMessage = `[${logPrefix}] [${logTime}] [${logAction}] ${logData}`;
+
+			// Logging
+			console.log(logMessage);
+		}
+	}
+}

package/src/services/public/DirectMessageService.ts

@@ -0,0 +1,159 @@
+import { Extractors } from '../../collections/Extractors';
+import { ResourceType } from '../../enums/Resource';
+import { Conversation } from '../../models/data/Conversation';
+import { Inbox } from '../../models/data/Inbox';
+import { RettiwtConfig } from '../../models/RettiwtConfig';
+import { IConversationTimelineResponse } from '../../types/raw/dm/Conversation';
+import { IInboxInitialResponse } from '../../types/raw/dm/InboxInitial';
+import { IInboxTimelineResponse } from '../../types/raw/dm/InboxTimeline';
+
+import { FetcherService } from './FetcherService';
+
+/**
+ * Handles interacting with resources related to direct messages
+ *
+ * @public
+ */
+export class DirectMessageService extends FetcherService {
+	/**
+	 * @param config - The config object for configuring the Rettiwt instance.
+	 *
+	 * @internal
+	 */
+	public constructor(config: RettiwtConfig) {
+		super(config);
+	}
+
+	/**
+	 * Get the full conversation history for a specific conversation, ordered recent to oldest.
+	 * Use this to load complete message history for a conversation identified from the inbox.
+	 *
+	 * @param conversationId - The ID of the conversation (e.g., "394028042-1712730991884689408").
+	 * @param cursor - The cursor for pagination. Is equal to the ID of the last message from previous batch.
+	 *
+	 * @returns The conversation with full message history, or undefined if not 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 });
+	 *
+	 * // Fetching a specific conversation
+	 * rettiwt.dm.conversation('394028042-1712730991884689408')
+	 * .then(conversation => {
+	 * 	if (conversation) {
+	 * 		console.log(`Conversation with ${conversation.participants.length} participants`);
+	 * 		console.log(`${conversation.messages.length} messages loaded`);
+	 * 	}
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async conversation(conversationId: string, cursor?: string): Promise<Conversation | undefined> {
+		const resource = ResourceType.DM_CONVERSATION;
+
+		// Fetching raw conversation timeline
+		const response = await this.request<IConversationTimelineResponse>(resource, {
+			conversationId,
+			maxId: cursor,
+		});
+
+		// Deserializing response
+		const data = Extractors[resource](response);
+
+		return data;
+	}
+
+	/**
+	 * Delete a conversation.
+	 * You will leave the conversation and it will be removed from your inbox.
+	 *
+	 * @param conversationId - The ID of the conversation to delete.
+	 *
+	 * @returns A promise that resolves when the conversation is deleted.
+	 *
+	 * @example
+	 * ```ts
+	 * import { Rettiwt } from 'rettiwt-api';
+	 *
+	 * // Creating a new Rettiwt instance using the given 'API_KEY'
+	 * const rettiwt = new Rettiwt({ apiKey: API_KEY });
+	 * // Deleting a conversation
+	 * rettiwt.dm.deleteConversation('394028042-1712730991884689408')
+	 * .then(() => {
+	 * 	console.log('Conversation deleted successfully');
+	 * })
+	 * .catch(err => {
+	 *  console.log('Failed to delete conversation:', err);
+	 * 	});
+	 * ```
+	 **/
+	public async deleteConversation(conversationId: string): Promise<void> {
+		const resource = ResourceType.DM_DELETE_CONVERSATION;
+
+		// Sending delete request
+		await this.request<void>(resource, {
+			conversationId,
+		});
+	}
+
+	/**
+	 * Get your inbox, ordered recent to oldest.
+	 *
+	 * @param cursor - The cursor to the inbox items to fetch. Is equal to the ID of the last inbox conversation.
+	 *
+	 * @returns The required inbox. Returns initial inbox if no cursor is provided.
+	 *
+	 * @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 initial DM inbox state
+	 * rettiwt.dm.inbox()
+	 * .then(inbox => {
+	 * 	console.log(`Found ${inbox.conversations.length} conversations`);
+	 * 	console.log('First conversation:', inbox.conversations[0]);
+	 * })
+	 * .catch(err => {
+	 * 	console.log(err);
+	 * });
+	 * ```
+	 */
+	public async inbox(cursor?: string): Promise<Inbox> {
+		// If cursor is provided, fetch initial inbox
+		if (cursor !== undefined) {
+			const resource = ResourceType.DM_INBOX_TIMELINE;
+
+			// Fetching raw inbox timeline
+			const response = await this.request<IInboxTimelineResponse>(resource, {
+				maxId: cursor,
+			});
+
+			// Deserializing response
+			const data = Extractors[resource](response);
+
+			return data;
+		}
+		// Else, fetch next inbox data
+		else {
+			const resource = ResourceType.DM_INBOX_INITIAL_STATE;
+
+			// Fetching raw inbox initial state
+			const response = await this.request<IInboxInitialResponse>(resource, {});
+
+			// Deserializing response
+			const data = Extractors[resource](response);
+
+			return data;
+		}
+	}
+}