chore: add cycletls example and use separate export

Author: karashiiro

README.md

@@ -168,6 +168,41 @@ const scraper = new Scraper({
 });
 ```
 
+### Bypassing Cloudflare bot detection
+
+In some cases, Twitter's authentication endpoints may be protected by Cloudflare's advanced bot detection, resulting in `403 Forbidden` errors during login. This typically happens because standard Node.js TLS fingerprints are detected as non-browser clients.
+
+To bypass this protection, you can use the optional CycleTLS integration, which uses golang to mimic Chrome browser TLS fingerprints:
+
+**Installation:**
+
+```sh
+npm install cycletls
+# or
+yarn add cycletls
+```
+
+**Usage:**
+
+```ts
+import { Scraper } from '@the-convocation/twitter-scraper';
+import { cycleTLSFetch, cycleTLSExit } from '@the-convocation/twitter-scraper/cycletls';
+
+const scraper = new Scraper({
+  fetch: cycleTLSFetch,
+});
+
+// Use the scraper normally
+await scraper.login(username, password, email);
+
+// Important: cleanup CycleTLS resources when done
+cycleTLSExit();
+```
+
+**Note:** The `/cycletls` entrypoint is Node.js only and will not work in browser environments. It's provided as a separate optional entrypoint to avoid bundling golang dependencies in environments where they cannot run.
+
+See the [cycletls-cloudflare example](./examples/cycletls-cloudflare/) for a complete working example.
+
 ### Rate limiting
 The Twitter API heavily rate-limits clients, requiring that the scraper has its own
 rate-limit handling to behave predictably when rate-limiting occurs. By default, the

examples/cycletls/README.md

@@ -0,0 +1,54 @@
+# CycleTLS Cloudflare Bypass Example
+
+This example demonstrates how to use the `@the-convocation/twitter-scraper/cycletls` entrypoint to bypass Cloudflare bot detection when authenticating with Twitter.
+
+## Problem
+
+Twitter's authentication endpoints may be protected by Cloudflare's advanced bot detection, which analyzes TLS fingerprints to detect non-browser clients. Standard Node.js TLS handshakes can trigger `403 Forbidden` errors during login.
+
+## Solution
+
+This example uses [CycleTLS](https://github.com/Danny-Dasilva/CycleTLS), which leverages golang to mimic Chrome browser TLS fingerprints, allowing requests to pass through Cloudflare's protection.
+
+## Installation
+
+```sh
+yarn install
+```
+
+## Configuration
+
+Create a `.env` file in the root of the repository (two levels up) with your Twitter credentials:
+
+```
+TWITTER_USERNAME=your_username
+TWITTER_PASSWORD=your_password
+TWITTER_EMAIL=your_email
+```
+
+## Usage
+
+```sh
+yarn start
+```
+
+## How it works
+
+The example imports the `cycleTLSFetch` function from the `/cycletls` subpath:
+
+```ts
+import { Scraper } from '@the-convocation/twitter-scraper';
+import { cycleTLSFetch, cycleTLSExit } from '@the-convocation/twitter-scraper/cycletls';
+
+const scraper = new Scraper({
+  fetch: cycleTLSFetch as any,
+});
+```
+
+This replaces the default fetch implementation with one that uses Chrome-like TLS fingerprints, bypassing Cloudflare's detection.
+
+## Important Notes
+
+- **Node.js only**: The `/cycletls` entrypoint requires Node.js and will not work in browsers
+- **Cleanup required**: Always call `cycleTLSExit()` when done to cleanup golang resources
+- **Optional dependency**: `cycletls` must be explicitly installed alongside the main package

examples/cycletls/package.json

@@ -0,0 +1,12 @@
+{
+  "private": true,
+  "packageManager": "[email protected]",
+  "scripts": {
+    "start": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@the-convocation/twitter-scraper": "file:../../",
+    "cycletls": "^2.0.4",
+    "tsx": "^4.15.5"
+  }
+}

examples/cycletls/src/index.ts

@@ -0,0 +1,53 @@
+import assert from 'node:assert';
+import { Scraper } from '@the-convocation/twitter-scraper';
+import {
+  cycleTLSFetch,
+  cycleTLSExit,
+} from '@the-convocation/twitter-scraper/cycletls';
+
+/**
+ * Example: Using CycleTLS to bypass Cloudflare bot detection
+ *
+ * CycleTLS uses golang to mimic Chrome browser TLS fingerprints, which helps
+ * bypass Cloudflare's advanced bot detection. This is particularly useful
+ * when you encounter 403 errors during authentication.
+ *
+ * Usage:
+ * 1. Install cycletls: yarn add cycletls
+ * 2. Pass cycleTLSFetch as the fetch option when creating a Scraper
+ * 3. Make sure to call cycleTLSExit() when done to cleanup resources
+ */
+
+// Load credentials from the environment
+const username = process.env['TWITTER_USERNAME'];
+const password = process.env['TWITTER_PASSWORD'];
+const email = process.env['TWITTER_EMAIL'];
+
+assert(username && password && email, 'Missing required environment variables');
+
+// Create scraper with CycleTLS fetch
+const scraper = new Scraper({
+  fetch: cycleTLSFetch as any,
+});
+
+const main = async () => {
+  try {
+    console.log('Logging in with CycleTLS-powered requests...');
+    await scraper.login(username, password, email);
+
+    console.log('Login successful! Fetching a tweet...');
+    const tweet = await scraper.getTweet('1585338303800578049');
+
+    console.log('Tweet details:');
+    console.log(`- Text: ${tweet?.text}`);
+    console.log(`- Likes: ${tweet?.likes}`);
+    console.log(`- Retweets: ${tweet?.retweets}`);
+  } catch (error) {
+    console.error('Error:', error);
+  } finally {
+    // Important: cleanup CycleTLS resources
+    cycleTLSExit();
+  }
+};
+
+main();

examples/cycletls/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist"
+  },
+  "include": ["src"]
+}