@youmind-openlab/rettiwt-api 1.0.0

package/src/browser/RettiwtBrowser.ts

@@ -0,0 +1,204 @@
+import { User } from '../models/data/User';
+import { IAuthCookie } from '../types/auth/AuthCookie';
+
+import { BrowserCookieProvider, ICookieProvider } from './adapters/CookieProvider';
+import { BrowserRettiwtConfig, IBrowserRettiwtConfig } from './config/BrowserRettiwtConfig';
+import { BrowserDirectMessageService } from './services/BrowserDirectMessageService';
+import { BrowserListService } from './services/BrowserListService';
+import { BrowserTweetService } from './services/BrowserTweetService';
+import { BrowserUserService } from './services/BrowserUserService';
+
+/**
+ * Configuration options for RettiwtBrowser.
+ *
+ * @public
+ */
+export interface IRettiwtBrowserConfig extends IBrowserRettiwtConfig {
+	/**
+	 * Custom cookie provider. If not provided, uses BrowserCookieProvider
+	 * which gets cookies from chrome.cookies API.
+	 */
+	cookieProvider?: ICookieProvider;
+}
+
+/**
+ * Browser extension-specific Rettiwt class.
+ * Automatically retrieves cookies from browser context - no need to pass authentication parameters.
+ *
+ * @example
+ * ```ts
+ * import { RettiwtBrowser } from 'rettiwt-api/browser';
+ *
+ * const rettiwt = new RettiwtBrowser();
+ *
+ * // Check if logged in
+ * if (await rettiwt.isLoggedIn()) {
+ *   // Initialize and verify
+ *   const user = await rettiwt.initialize();
+ *   console.log(`Logged in as: ${user.userName}`);
+ *
+ *   // Use the API
+ *   const tweet = await rettiwt.tweet.details('1234567890');
+ * }
+ * ```
+ *
+ * @public
+ */
+export class RettiwtBrowser {
+	/** The configuration for Rettiwt. */
+	private _config: BrowserRettiwtConfig;
+
+	/** The cookie provider for getting Twitter cookies. */
+	private _cookieProvider: ICookieProvider;
+
+	/** Whether the instance has been initialized. */
+	private _initialized: boolean = false;
+
+	/** The cached cookies. */
+	private _cookies?: IAuthCookie;
+
+	/** The instance used to fetch data related to direct messages. */
+	public dm!: BrowserDirectMessageService;
+
+	/** The instance used to fetch data related to lists. */
+	public list!: BrowserListService;
+
+	/** The instance used to fetch data related to tweets. */
+	public tweet!: BrowserTweetService;
+
+	/** The instance used to fetch data related to users. */
+	public user!: BrowserUserService;
+
+	/**
+	 * Creates a new RettiwtBrowser instance.
+	 *
+	 * @param config - Optional configuration options.
+	 */
+	public constructor(config?: IRettiwtBrowserConfig) {
+		this._cookieProvider = config?.cookieProvider ?? new BrowserCookieProvider();
+		this._config = new BrowserRettiwtConfig(config);
+	}
+
+	/**
+	 * Checks if the user is logged in to Twitter.
+	 * This method only checks for the presence of required cookies - it does NOT make any API calls.
+	 *
+	 * @returns true if the required Twitter authentication cookies are present.
+	 *
+	 * @example
+	 * ```ts
+	 * const rettiwt = new RettiwtBrowser();
+	 *
+	 * if (await rettiwt.isLoggedIn()) {
+	 *   console.log('User is logged in to Twitter');
+	 * } else {
+	 *   console.log('User is not logged in');
+	 * }
+	 * ```
+	 */
+	public async isLoggedIn(): Promise<boolean> {
+		return this._cookieProvider.hasRequiredCookies();
+	}
+
+	/**
+	 * Initializes the library by getting cookies from the browser and verifying authentication.
+	 * This method must be called before using other methods.
+	 *
+	 * The method:
+	 * 1. Gets Twitter authentication cookies from the browser
+	 * 2. Initializes the configuration with these cookies
+	 * 3. Creates the service instances (dm, list, tweet, user)
+	 * 4. Verifies authentication by fetching the current user's profile
+	 *
+	 * @returns The authenticated user's profile.
+	 * @throws Error if not logged in to Twitter or if authentication verification fails.
+	 *
+	 * @example
+	 * ```ts
+	 * const rettiwt = new RettiwtBrowser();
+	 *
+	 * try {
+	 *   const user = await rettiwt.initialize();
+	 *   console.log(`Logged in as: ${user.userName}`);
+	 * } catch (error) {
+	 *   console.error('Failed to initialize:', error.message);
+	 * }
+	 * ```
+	 */
+	public async initialize(): Promise<User> {
+		// Get cookies from browser
+		const cookies = await this._cookieProvider.getCookies();
+
+		if (!cookies.auth_token || !cookies.ct0) {
+			throw new Error('Not logged in to Twitter. Please log in to Twitter first.');
+		}
+
+		// Store cookies
+		this._cookies = cookies;
+
+		// Initialize config with cookies
+		this._config.initializeWithCookies(cookies);
+
+		// Create service instances
+		this.dm = new BrowserDirectMessageService(this._config);
+		this.list = new BrowserListService(this._config);
+		this.tweet = new BrowserTweetService(this._config);
+		this.user = new BrowserUserService(this._config);
+
+		// Set cookies for each service
+		this.dm.setCookies(cookies);
+		this.list.setCookies(cookies);
+		this.tweet.setCookies(cookies);
+		this.user.setCookies(cookies);
+
+		// Verify by fetching user profile
+		const user = await this.user.details();
+
+		if (!user) {
+			throw new Error('Failed to verify authentication. Please try logging in to Twitter again.');
+		}
+
+		this._initialized = true;
+		return user;
+	}
+
+	/**
+	 * Alias for initialize() - verifies authentication and returns user profile.
+	 *
+	 * @returns The authenticated user's profile.
+	 * @throws Error if not logged in or verification fails.
+	 */
+	public async verify(): Promise<User> {
+		return this.initialize();
+	}
+
+	/**
+	 * Whether the instance has been initialized.
+	 */
+	public get isInitialized(): boolean {
+		return this._initialized;
+	}
+
+	/**
+	 * Gets the authenticated user's ID (extracted from twid cookie).
+	 * Returns undefined if not initialized.
+	 */
+	public get userId(): string | undefined {
+		return this._config.userId;
+	}
+
+	/**
+	 * Gets the current authentication cookies.
+	 * Returns undefined if not initialized.
+	 */
+	public get cookies(): IAuthCookie | undefined {
+		return this._cookies;
+	}
+
+	/**
+	 * Sets custom headers for all API requests.
+	 */
+	public set headers(headers: { [key: string]: string }) {
+		this._config.headers = headers;
+	}
+}

package/src/browser/adapters/Base64Adapter.ts

@@ -0,0 +1,29 @@
+/**
+ * Browser-compatible base64 encoding/decoding.
+ * Replaces Node.js Buffer for base64 operations.
+ *
+ * @internal
+ */
+export class Base64Adapter {
+	/**
+	 * Decodes a base64 string to ASCII.
+	 * Equivalent to: Buffer.from(encoded, 'base64').toString('ascii')
+	 *
+	 * @param encoded - The base64 encoded string
+	 * @returns The decoded ASCII string
+	 */
+	static decode(encoded: string): string {
+		return atob(encoded);
+	}
+
+	/**
+	 * Encodes a string to base64.
+	 * Equivalent to: Buffer.from(data).toString('base64')
+	 *
+	 * @param data - The string to encode
+	 * @returns The base64 encoded string
+	 */
+	static encode(data: string): string {
+		return btoa(data);
+	}
+}

package/src/browser/adapters/CookieProvider.ts

@@ -0,0 +1,73 @@
+import { IAuthCookie } from '../../types/auth/AuthCookie';
+
+/**
+ * Interface for cookie retrieval, allowing different implementations
+ * for browser extension vs other environments.
+ *
+ * @public
+ */
+export interface ICookieProvider {
+	/**
+	 * Retrieves Twitter authentication cookies.
+	 * @returns Promise resolving to cookies in the format expected by AuthCookie
+	 */
+	getCookies(): Promise<IAuthCookie>;
+
+	/**
+	 * Checks if required cookies exist for authentication.
+	 * @returns Promise resolving to true if all required cookies are present
+	 */
+	hasRequiredCookies(): Promise<boolean>;
+}
+
+/**
+ * Browser extension implementation using chrome.cookies API.
+ * Automatically retrieves Twitter cookies from the browser.
+ *
+ * @public
+ */
+export class BrowserCookieProvider implements ICookieProvider {
+	private readonly domain = '.x.com';
+	private readonly requiredCookieNames = ['auth_token', 'ct0', 'twid'];
+
+	/**
+	 * Retrieves Twitter authentication cookies from the browser.
+	 * Requires the "cookies" permission in manifest.json.
+	 *
+	 * @returns The authentication cookies
+	 */
+	async getCookies(): Promise<IAuthCookie> {
+		const cookies = await chrome.cookies.getAll({ domain: this.domain });
+
+		const result: IAuthCookie = {
+			auth_token: '',
+			ct0: '',
+			kdt: '',
+			twid: '',
+		};
+
+		for (const cookie of cookies) {
+			if (cookie.name === 'auth_token') {
+				result.auth_token = cookie.value;
+			} else if (cookie.name === 'ct0') {
+				result.ct0 = cookie.value;
+			} else if (cookie.name === 'kdt') {
+				result.kdt = cookie.value;
+			} else if (cookie.name === 'twid') {
+				result.twid = cookie.value;
+			}
+		}
+
+		return result;
+	}
+
+	/**
+	 * Checks if the user is logged in by verifying required cookies exist.
+	 *
+	 * @returns true if all required cookies are present
+	 */
+	async hasRequiredCookies(): Promise<boolean> {
+		const cookies = await this.getCookies();
+		return !!(cookies.auth_token && cookies.ct0 && cookies.twid);
+	}
+}

package/src/browser/adapters/DomAdapter.ts

@@ -0,0 +1,19 @@
+/**
+ * Browser-native DOM parsing.
+ * Replaces JSDOM with native DOMParser for browser environments.
+ *
+ * @internal
+ */
+export class DomAdapter {
+	/**
+	 * Parses an HTML string into a Document.
+	 * Equivalent to: new JSDOM(html).window.document
+	 *
+	 * @param html - The HTML string to parse
+	 * @returns The parsed Document
+	 */
+	static parseHTML(html: string): Document {
+		const parser = new DOMParser();
+		return parser.parseFromString(html, 'text/html');
+	}
+}

package/src/browser/config/BrowserRettiwtConfig.ts

@@ -0,0 +1,167 @@
+import { IAuthCookie } from '../../types/auth/AuthCookie';
+import { IErrorHandler } from '../../types/ErrorHandler';
+
+/**
+ * The default headers for browser requests.
+ *
+ * @internal
+ */
+const DefaultHeaders = {
+	/* eslint-disable @typescript-eslint/naming-convention */
+
+	Authority: 'x.com',
+	'Accept-Language': 'en-US,en;q=0.9',
+	'Cache-Control': 'no-cache',
+	Referer: 'https://x.com',
+	'X-Twitter-Active-User': 'yes',
+	'X-Twitter-Client-Language': 'en',
+
+	/* eslint-enable @typescript-eslint/naming-convention */
+};
+
+/**
+ * Configuration options for BrowserRettiwt.
+ *
+ * @public
+ */
+export interface IBrowserRettiwtConfig {
+	/** The max wait time (in milli-seconds) for a response. */
+	timeout?: number;
+
+	/** Whether to write logs to console or not. */
+	logging?: boolean;
+
+	/** Optional custom error handler. */
+	errorHandler?: IErrorHandler;
+
+	/** Optional custom HTTP headers. */
+	headers?: { [key: string]: string };
+
+	/** The delay (in ms) between concurrent requests. */
+	delay?: number | (() => number | Promise<number>);
+
+	/** The maximum number of retries. */
+	maxRetries?: number;
+}
+
+/**
+ * Browser-specific configuration for Rettiwt.
+ * Does not include proxy agent (not applicable in browser).
+ *
+ * @public
+ */
+export class BrowserRettiwtConfig {
+	// Internal state
+	private _userId?: string;
+	private _cookies?: string;
+	private _csrfToken?: string;
+	private _headers: { [key: string]: string };
+	private _initialized: boolean = false;
+
+	// Public readonly config
+	public readonly delay?: number | (() => number | Promise<number>);
+	public readonly errorHandler?: IErrorHandler;
+	public readonly logging?: boolean;
+	public readonly maxRetries: number;
+	public readonly timeout?: number;
+
+	/**
+	 * Creates a new BrowserRettiwtConfig instance.
+	 *
+	 * @param config - The configuration options
+	 */
+	public constructor(config?: IBrowserRettiwtConfig) {
+		this.delay = config?.delay ?? 0;
+		this.maxRetries = config?.maxRetries ?? 5;
+		this.errorHandler = config?.errorHandler;
+		this.logging = config?.logging;
+		this.timeout = config?.timeout;
+		this._headers = {
+			...DefaultHeaders,
+			...config?.headers,
+		};
+	}
+
+	/**
+	 * Initializes the config with cookies obtained from the browser.
+	 *
+	 * @param cookies - The authentication cookies
+	 */
+	public initializeWithCookies(cookies: IAuthCookie): void {
+		// Extract user ID from twid cookie
+		// twid format: "u=1234567890" or URL-encoded "u%3D1234567890"
+		const twidMatch = cookies.twid.match(/u[=%]3[dD]?(\d+)/);
+		if (twidMatch) {
+			this._userId = twidMatch[1];
+		}
+
+		// Store CSRF token
+		this._csrfToken = cookies.ct0;
+
+		// Build cookie string
+		this._cookies = `auth_token=${cookies.auth_token};ct0=${cookies.ct0};kdt=${cookies.kdt};twid=${cookies.twid}`;
+
+		this._initialized = true;
+	}
+
+	/**
+	 * Whether the config has been initialized with cookies.
+	 */
+	public get isInitialized(): boolean {
+		return this._initialized;
+	}
+
+	/**
+	 * The ID of the authenticated user.
+	 */
+	public get userId(): string | undefined {
+		return this._userId;
+	}
+
+	/**
+	 * The HTTP headers to use for requests.
+	 */
+	public get headers(): { [key: string]: string } {
+		return this._headers;
+	}
+
+	/**
+	 * The cookie string for authentication.
+	 */
+	public get cookies(): string | undefined {
+		return this._cookies;
+	}
+
+	/**
+	 * The CSRF token for the session.
+	 */
+	public get csrfToken(): string | undefined {
+		return this._csrfToken;
+	}
+
+	/**
+	 * The HTTPS agent (undefined in browser - not applicable).
+	 */
+	public get httpsAgent(): undefined {
+		return undefined;
+	}
+
+	/**
+	 * The API key (returns undefined - browser uses cookies directly).
+	 */
+	public get apiKey(): undefined {
+		return undefined;
+	}
+
+	/**
+	 * Sets custom headers.
+	 */
+	public set headers(headers: { [key: string]: string } | undefined) {
+		this._headers = {
+			...DefaultHeaders,
+			...headers,
+		};
+	}
+}
+
+export { DefaultHeaders as DefaultBrowserRettiwtHeaders };

package/src/browser/index.ts

@@ -0,0 +1,107 @@
+/**
+ * Browser extension entry point for Rettiwt-API.
+ *
+ * This module exports browser-compatible classes that can be used directly in browser extensions.
+ * Cookies are automatically retrieved from the browser - no need to pass authentication parameters.
+ *
+ * @example
+ * ```ts
+ * import { RettiwtBrowser } from 'rettiwt-api/browser';
+ *
+ * const rettiwt = new RettiwtBrowser();
+ *
+ * // Check if logged in
+ * if (await rettiwt.isLoggedIn()) {
+ *   // Initialize and verify
+ *   const user = await rettiwt.initialize();
+ *   console.log(`Logged in as: ${user.userName}`);
+ *
+ *   // Use the API
+ *   const tweet = await rettiwt.tweet.details('1234567890');
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Main class
+export { RettiwtBrowser, IRettiwtBrowserConfig } from './RettiwtBrowser';
+
+// Adapters
+export { BrowserCookieProvider, ICookieProvider } from './adapters/CookieProvider';
+export { Base64Adapter } from './adapters/Base64Adapter';
+export { DomAdapter } from './adapters/DomAdapter';
+
+// Config
+export { BrowserRettiwtConfig, IBrowserRettiwtConfig, DefaultBrowserRettiwtHeaders } from './config/BrowserRettiwtConfig';
+
+// Services
+export { BrowserFetcherService } from './services/BrowserFetcherService';
+export { BrowserAuthService, BrowserAuthCredential } from './services/BrowserAuthService';
+export { BrowserUserService } from './services/BrowserUserService';
+export { BrowserTweetService, BrowserMedia } from './services/BrowserTweetService';
+export { BrowserListService } from './services/BrowserListService';
+export { BrowserDirectMessageService } from './services/BrowserDirectMessageService';
+
+// Re-export enums (importing directly to avoid Node.js dependencies)
+export { RawAnalyticsGranularity, RawAnalyticsMetric } from '../enums/raw/Analytics';
+export { RawMediaType } from '../enums/raw/Media';
+export { RawNotificationType } from '../enums/raw/Notification';
+export { AuthenticationType } from '../enums/Authentication';
+export { LogActions } from '../enums/Logging';
+export { MediaType } from '../enums/Media';
+export { NotificationType } from '../enums/Notification';
+export { ResourceType } from '../enums/Resource';
+export { TweetRepliesSortType } from '../enums/Tweet';
+
+// Re-export models (importing directly to avoid Node.js dependencies)
+export { Analytics } from '../models/data/Analytics';
+export { BookmarkFolder } from '../models/data/BookmarkFolder';
+export { Conversation } from '../models/data/Conversation';
+export { CursoredData } from '../models/data/CursoredData';
+export { DirectMessage } from '../models/data/DirectMessage';
+export { Inbox } from '../models/data/Inbox';
+export { List } from '../models/data/List';
+export { Notification } from '../models/data/Notification';
+export { Tweet } from '../models/data/Tweet';
+export { User } from '../models/data/User';
+export { TwitterError } from '../models/errors/TwitterError';
+
+// Re-export types (importing directly to avoid Node.js dependencies)
+export type { IFetchArgs, ITweetFilter } from '../types/args/FetchArgs';
+export type { IPostArgs, INewTweet } from '../types/args/PostArgs';
+export type { IProfileUpdateOptions } from '../types/args/ProfileArgs';
+export type { IAuthCookie } from '../types/auth/AuthCookie';
+export type { IAuthCredential } from '../types/auth/AuthCredential';
+export type { IErrorHandler } from '../types/ErrorHandler';
+
+// Factory function for creating initialized RettiwtBrowser instance
+import { RettiwtBrowser } from './RettiwtBrowser';
+import type { IRettiwtBrowserConfig } from './RettiwtBrowser';
+import { User } from '../models/data/User';
+
+/**
+ * Creates and initializes a RettiwtBrowser instance.
+ * This is a convenience function that creates a new instance and calls initialize().
+ *
+ * @param config - Optional configuration options.
+ * @returns A promise resolving to an object containing the initialized rettiwt instance and the user.
+ * @throws Error if not logged in or initialization fails.
+ *
+ * @example
+ * ```ts
+ * import { createRettiwtBrowser } from 'rettiwt-api/browser';
+ *
+ * const { rettiwt, user } = await createRettiwtBrowser();
+ * console.log(`Logged in as: ${user.userName}`);
+ *
+ * const tweet = await rettiwt.tweet.details('1234567890');
+ * ```
+ */
+export async function createRettiwtBrowser(
+	config?: IRettiwtBrowserConfig,
+): Promise<{ rettiwt: RettiwtBrowser; user: User }> {
+	const rettiwt = new RettiwtBrowser(config);
+	const user = await rettiwt.initialize();
+	return { rettiwt, user };
+}