{"id":20251573,"url":"https://github.com/owen3h/twittxr","last_synced_at":"2025-08-03T00:08:16.977Z","repository":{"id":184029185,"uuid":"671211886","full_name":"Owen3H/twittxr","owner":"Owen3H","description":"Twitter/X Syndication API wrapper.","archived":false,"fork":false,"pushed_at":"2025-03-03T23:18:47.000Z","size":670,"stargazers_count":29,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-21T20:03:40.128Z","etag":null,"topics":["api-wrapper","syndication","tweet-embed","tweets","twitter","xdotcom"],"latest_commit_sha":null,"homepage":"https://npmjs.com/package/twittxr","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Owen3H.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"Owen3H","ko_fi":"Owen3H","custom":"https://paypal.me/Owen3H"}},"created_at":"2023-07-26T19:55:15.000Z","updated_at":"2025-05-13T13:41:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"db5ae73f-ad22-4598-8bb5-9957907e4818","html_url":"https://github.com/Owen3H/twittxr","commit_stats":null,"previous_names":["owen3h/twittxr"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/Owen3H/twittxr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Owen3H%2Ftwittxr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Owen3H%2Ftwittxr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Owen3H%2Ftwittxr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Owen3H%2Ftwittxr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Owen3H","download_url":"https://codeload.github.com/Owen3H/twittxr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Owen3H%2Ftwittxr/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261186368,"owners_count":23121938,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-wrapper","syndication","tweet-embed","tweets","twitter","xdotcom"],"created_at":"2024-11-14T10:10:58.697Z","updated_at":"2025-06-21T20:03:57.465Z","avatar_url":"https://github.com/Owen3H.png","language":"TypeScript","funding_links":["https://github.com/sponsors/Owen3H","https://ko-fi.com/Owen3H","https://paypal.me/Owen3H"],"categories":[],"sub_categories":[],"readme":"# Twittxr \u003cimg align=\"left\" width=\"132\" height=\"132\" src=\"./icon.png\"\u003e\n\nA simple wrapper library around the Twitter/X Syndication API.\u003cbr\u003e\nInspired by: https://github.com/zedeus/nitter/issues/919#issuecomment-1616703690\n\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/3295160336cf41108ab4b409f6baf6c5)](https://app.codacy.com/gh/Owen3H/twittxr/dashboard?utm_source=gh\u0026utm_medium=referral\u0026utm_content=\u0026utm_campaign=Badge_grade)\n[![Build Status Badge](https://img.shields.io/github/actions/workflow/status/Owen3H/twittxr/main.yml)](https://github.com/Owen3H/twittxr/actions)\n[![Discord](https://img.shields.io/discord/1215213004824645674?logo=discord\u0026logoColor=white\u0026color=blue)](https://discord.gg/64Vq7cpdGV)\n\n## Overview\nAs you may know, Twitter/X ended free access to its API, making [IFTTT](https://ifttt.com) and other services obsolete for many users.\nInstead, this wrapper aims to use the public facing [Syndication API](https://syndication.twitter.com/srv/timeline-profile/screen-name/elonmusk)\nwhich is used by embedded widgets, though there are some notable limitations by using it as an \"alternative\".\n\n**Twittxr** is best suited for setting up a user feed or getting a single tweet, it will not replace a fully fledged scraper/client.\n\n#### ✅ Features\n- Can include retweets and/or replies by the user.\n- Option to pass cookie object or string to get **Sensitive/NSFW** Tweets.\n- Ability to pass a [Puppeteer](https://pptr.dev) page, bypassing potential API auth issues.\n- Falls back to native `fetch` in the browser, allowing use outside of **Node**.\n- Intuitive syntax and included type definitions.\n\n#### ❌ Limitations\n- When getting a Timeline, only up to `100` Tweets can be returned. (May be `20` in some cases)\n\n## Installation\n```console\nbun add twittxr\n```\n\nOptionally, you can install `puppeteer` \u003e=16 to use as a fallback on failed requests.\u003cbr\u003e\nThis can potentially avoid issues with Cloudflare. Ex: \"403 Forbidden\".\n\n```console\nbun add twittxr puppeteer\n```\n\n## Authentication\nTwitter is now known to require a cookie to return timeline data!\u003cbr\u003e\nI strongly advise you pass the `cookie` parameter in all of your requests.\n\n***How do I get my session cookie?***\n1. Login to Twitter -\u003e Right click -\u003e **Inspect Element**\n2. Select the **Application** tab -\u003e Refresh the page -\u003e Find the **Cookies** section.\n3. Note down the cookies labelled `guest_id`, `auth_token`, `ct0` and `kdt`.\n\nNow you have two options to store and use these cookies.\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eOption A\u003c/b\u003e - Building the string manually\u003c/summary\u003e\n\n  Once you have your cookies, build a string in your `.env` file that follows the following format:\n\n  ```bash\n  TWITTER_COOKIE=\"guest_id=someValue; auth_token=someValue; ct0=someValue; kdt=someValue; dnt=1;\"\n  ```\n\n  This way we only store one single line in the file and the `dnt` (Do-Not-Track) cookie can be customised if desired.\\\n  Once complete, simply reference the cookie like so when passing it to methods requiring auth.\n  ```ts\n  const cookie = process.env.TWITTER_COOKIE\n  ```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cb\u003eOption B\u003c/b\u003e - Using \u003ccode\u003ebuildCookieString\u003c/code\u003e\u003c/summary\u003e\n\n  This way is slightly more verbose and always includes a `dnt=1` cookie for you but requires you to use multiple lines in your `.env` file.\n\n  ```bash\n  GUEST_ID=\"someValue\"\n  AUTH_TOKEN=\"someValue\"\n  CT0=\"someValue\"\n  KDT=\"someValue\"\n  ```\n\n  We can then make use of the provided `buildCookieString` helper method before passing to methods requiring auth.\n  ```ts\n  import { buildCookieString } from \"twittxr\"\n\n  const cookie = buildCookieString({\n      guest_id: process.env.GUEST_ID,\n      auth_token: process.env.AUTH_TOKEN,\n      ct0: process.env.CT0,\n      kdt: process.env.KDT\n  })\n  ```\n\u003c/details\u003e\n\n## Usage\n```ts\nimport { Timeline, Tweet } from 'twittxr' // ESM\nconst { Timeline, Tweet } = require('twittxr') // CommonJS\n```\n\n### Get a single Tweet\nNo auth required.\n```ts\n// Does not return the same type as Timeline.get()\nconst tweet = await Tweet.get(1674865731136020505) // Or string\n```\n\n### Get a user Timeline\nSee the **Authentication** section to obtain a cookie string.\n\n```ts\n// The retweets and replies default to false.\nconst timelineWithRts = await Timeline.get('elonmusk', { cookie }, { \n  retweets: true,\n  replies: false, // This is the user's replies, not replies to their Tweets.\n})\n```\n\n### Using Puppeteer\n\u003e **Note**\n\u003e By default, Puppeteer will be used as a fallback for failed requests - if installed.\u003cbr\u003e\n\u003e However, it is possible to solely use Puppeteer by calling `await usePuppeteer()`.\n\n```ts\nimport { Timeline } from 'twittxr'\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eNo config\u003c/summary\u003e\n\n```ts\n// Launches a basic headless browser \u0026 automatically closes the page.\nawait Timeline.usePuppeteer()\nconst tweets = await Timeline.get('elonmusk', { cookie })\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWith custom browser\u003c/summary\u003e\n\n```ts\nconst puppeteer = require('puppeteer-extra')\n\n// Use plugins if desired\npuppeteer.use(ExamplePlugin())\n\nconst browser = await puppeteer.launch({ headless: true })\n\n// Creates a new page and closes it automatically after every .get() call\nawait Timeline.usePuppeteer({ browser, autoClose: true })\nconst tweets = await Timeline.get('elonmusk', { cookie })\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003eWith page\u003c/summary\u003e\n\n```js\nconst puppeteer = require('puppeteer')\nconst browser = await puppeteer.launch({ headless: true })\nconst page = await browser.newPage()\n\n// Pass the page, but do not automatically close it.\nawait Timeline.usePuppeteer({ page, autoClose: false })\nconst tweets = await Timeline.get('elonmusk', { cookie })\n\nawait page.goto('https://google.com') // Continue to manipulate the page.\nawait page.close() // Close the page manually.\n```\n\u003c/details\u003e\n\nTo stop using Puppeteer at any point, you can simply call:\n```js\nTimeline.disablePuppeteer()\n```\n\n## Disclaimer\nYou **must** use this library at your own discretion!\\\nI will not be held accountable for any outcomes that may result from its usage, including and not limited to:\n- Banning/Suspension of your Twitter/X account.\n- Lawsuits, fines and other Twitter/X related legal disputes.\n- Hacking of network and/or account when providing a proxy or exposing cookies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowen3h%2Ftwittxr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fowen3h%2Ftwittxr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fowen3h%2Ftwittxr/lists"}