{"_id":"1322-client","name":"1322-client","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"1322-client","version":"0.1.0","description":"Unified TypeScript/JavaScript client for the 1322 real-time social monitoring API (X/Twitter, Truth Social, Instagram, YouTube, Binance Square, News).","keywords":["1322","twitter","x-api","truth-social","instagram","youtube","binance-square","websocket","real-time","social-monitoring"],"license":"MIT","author":{"name":"SisoSol"},"homepage":"https://1322.io","repository":{"type":"git","url":"git+https://github.com/SisoSol/1322-client.git"},"bugs":{"url":"https://github.com/SisoSol/1322-client/issues"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./package.json":"./package.json"},"engines":{"node":">=18"},"sideEffects":false,"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit","prepare":"tsup","prepublishOnly":"npm run build && npm test"},"dependencies":{"ws":"^8.18.0"},"devDependencies":{"@types/node":"^22.10.2","@types/ws":"^8.5.13","tsup":"^8.3.5","typescript":"^5.7.2","vitest":"^4.1.10"},"gitHead":"063057351dc2f05a8c8262887cd654bd885d8ebe","_id":"1322-client@0.1.0","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-hCBpWxGKVpDBnlkjjsUuNP8PCfGjaPG9aiVZ+PmrsQDPkvRXnWBy+JPAtd+qusOrroR+7McdlTwzv/Xx+Lp0lw==","shasum":"7f2452eecc99b477bd235c03404995fac716344a","tarball":"https://registry.npmjs.org/1322-client/-/1322-client-0.1.0.tgz","fileCount":9,"unpackedSize":405457,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDILBGa0E1Mm4yElOyBAIq6IzL4pRQgvp9zMR05ETcW5wIhANE0HPzx7Wj+y3dNifLXvDYsUcGMHlu6qZCMA/1JZybe"}]},"_npmUser":{"name":"siso1322","email":"degeneratebots@gmail.com"},"directories":{},"maintainers":[{"name":"siso1322","email":"degeneratebots@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/1322-client_0.1.0_1785273794447_0.9741854340119609"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-28T21:23:14.403Z","0.1.0":"2026-07-28T21:23:14.591Z","modified":"2026-07-28T21:23:14.749Z"},"maintainers":[{"name":"siso1322","email":"degeneratebots@gmail.com"}],"description":"Unified TypeScript/JavaScript client for the 1322 real-time social monitoring API (X/Twitter, Truth Social, Instagram, YouTube, Binance Square, News).","homepage":"https://1322.io","keywords":["1322","twitter","x-api","truth-social","instagram","youtube","binance-square","websocket","real-time","social-monitoring"],"repository":{"type":"git","url":"git+https://github.com/SisoSol/1322-client.git"},"author":{"name":"SisoSol"},"bugs":{"url":"https://github.com/SisoSol/1322-client/issues"},"license":"MIT","readme":"# 1322-client\r\n\r\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE) [![Built for 1322.io](https://img.shields.io/badge/built%20for-1322.io-3b82f6?style=flat-square)](https://1322.io)\r\n\r\nUnified TypeScript/JavaScript client for the [1322](https://1322.io) real-time\r\nsocial monitoring API. One `createClient()` call, one consistent\r\n`connect()` / `on()` / `track()` shape, across all six platforms 1322\r\ncovers: **X (Twitter), Truth Social, Instagram, YouTube, Binance Square, and\r\nNews**.\r\n\r\n1322 already publishes six separate single-platform example repos (one\r\nWebSocket client each, in Node/Python). This package replaces \"pick the repo\r\nfor your platform and copy the script\" with an installable client: proper\r\ntypes for every event and REST payload, automatic reconnect with the\r\ndocumented backoff, and -- for X specifically -- the additive-merge/dedup\r\nlogic the docs recommend you implement yourself.\r\n\r\nFull endpoint and payload reference: **[1322.io/docs](https://1322.io/docs)**.\r\n\r\n## Install\r\n\r\nNot yet published to npm (see [Status](#status) below). Install straight from\r\nGitHub, which works today:\r\n\r\n```bash\r\nnpm install git+https://github.com/SisoSol/1322-client.git\r\n```\r\n\r\n(The shorter `npm install github:SisoSol/1322-client` form works too, but npm\r\nresolves it to an SSH git URL by default -- it'll fail with a confusing\r\n`Permission denied (publickey)` error on any machine without an SSH key\r\nregistered on GitHub. The `git+https://` form above always works.)\r\n\r\nOnce published to npm:\r\n\r\n```bash\r\nnpm install 1322-client\r\n```\r\n\r\nRequires Node.js 18+. Ships both ESM and CommonJS builds with bundled\r\n`.d.ts` types.\r\n\r\n## Quick start\r\n\r\n```ts\r\nimport { createClient } from \"1322-client\";\r\n\r\nconst client = createClient({ platform: \"x\", apiKey: \"YOUR_API_KEY_HERE\" });\r\n\r\nclient.on(\"tweet\", (tweet) => {\r\n  console.log(`@${tweet.author.handle}: ${tweet.body.text}`);\r\n});\r\n\r\nawait client.connect();\r\n```\r\n\r\n`platform` selects which of the six clients you get back, and TypeScript\r\nnarrows the config fields, event names, and payload types to match --\r\n`client.on(\"tweet\", ...)` only exists (and is only typed as a merged X tweet)\r\nwhen `platform: \"x\"`.\r\n\r\n## Platform capability matrix\r\n\r\nEvery client exposes the same shape: `connect()`, `disconnect()`,\r\n`isConnected()`, `on()` / `off()` / `once()`, and the lifecycle events `open`,\r\n`close`, `error`, `reconnecting`, `message`. What differs per platform is the\r\ndata events and the management (`track()` / `untrack()` / `list()`) methods,\r\nbecause that's what the underlying 1322 API actually looks like per platform\r\n-- see [1322.io/docs](https://1322.io/docs) for the authoritative contract\r\neach of these maps to.\r\n\r\n| Platform | `platform` value | Data events | `track()` / `untrack()` / `list()` |\r\n| --- | --- | --- | --- |\r\n| X / Twitter | `\"x\"` | `tweetMiniUpdate`, `tweetUpdate`, `tweetExpanded`, `tweetFull`, `tweetDeleted`, `profileUpdate`, `profilePinned`, `profileUnpinned`, `followingUpdate`, and merged `tweet` | Yes (`GET/POST/DELETE /v1/tracked`) |\r\n| Truth Social | `\"truth\"` | `post` | Yes (`POST /v1/track`, `/v1/untrack`, `GET /v1/list`) |\r\n| Instagram | `\"instagram\"` | `post` | Yes (`POST /v1/track`, `/v1/untrack`, `GET /v1/list`) |\r\n| News | `\"news\"` | `article` | Yes, as subscribe/unsubscribe to named feeds |\r\n| Binance Square | `\"binance\"` | `post`, `pinUpdate` | Yes (`POST /v1/track`, `/v1/untrack`) |\r\n| YouTube | `\"youtube\"` | `upload`, `upgrade`, `deletion` | **No** -- see [YouTube](#youtube) below |\r\n\r\n## Examples\r\n\r\nEvery example below uses a placeholder key. Never commit a real one -- copy\r\n[`.env.example`](.env.example) to `.env` and load your keys from environment\r\nvariables instead.\r\n\r\n### X / Twitter\r\n\r\n```ts\r\nimport { createClient } from \"1322-client\";\r\n\r\nconst client = createClient({\r\n  platform: \"x\",\r\n  apiKey: \"YOUR_API_KEY_HERE\",\r\n  tier: \"normal\", // \"normal\" | \"ultimate\" | \"hybrid\" (see below)\r\n});\r\n\r\n// The additive-merged, deduplicated view of a tweet -- recommended for most\r\n// consumers. Fires again every time a richer stage (mini -> update ->\r\n// expanded -> full) arrives for the same tweet id.\r\nclient.on(\"tweet\", (tweet) => {\r\n  console.log(tweet.id, tweet.body.text, tweet.media.images);\r\n});\r\n\r\n// Or handle each documented stage/event individually:\r\nclient.on(\"tweetDeleted\", ({ tweet, deletedAt }) => {\r\n  console.log(`deleted: ${tweet.id} at ${new Date(deletedAt).toISOString()}`);\r\n});\r\n\r\nclient.on(\"reconnecting\", ({ attempt, delayMs }) => {\r\n  console.log(`reconnecting (attempt ${attempt}) in ${delayMs}ms`);\r\n});\r\n\r\nawait client.connect();\r\n\r\n// Management API\r\nawait client.track([\"elonmusk\", \"twitter\"]); // comma-joined, resolved server-side\r\nawait client.list();\r\n```\r\n\r\n`tier: \"hybrid\"` opens both the Normal and Ultimate WebSocket streams at once\r\n(pass `ultimateApiKey`) and deduplicates tweets between them by id, per the\r\n\"Hybrid Clients\" guidance in the docs.\r\n\r\n### Truth Social\r\n\r\n```ts\r\nimport { createClient } from \"1322-client\";\r\n\r\nconst client = createClient({\r\n  platform: \"truth\",\r\n  apiKey: \"YOUR_API_KEY_HERE\",\r\n  // Path + key are issued per-account in your 1322 dashboard configuration\r\n  // -- there is no REST endpoint that discovers them, unlike News/Binance.\r\n  wsPath: \"YOUR_WS_PATH_HERE\",\r\n});\r\n\r\nclient.on(\"post\", (post) => {\r\n  console.log(`@${post.username}: ${post.text}`);\r\n});\r\n\r\nawait client.connect();\r\nawait client.track(\"realDonaldTrump\");\r\n```\r\n\r\n### Instagram\r\n\r\n```ts\r\nimport { createClient } from \"1322-client\";\r\n\r\nconst client = createClient({ platform: \"instagram\", apiKey: \"YOUR_API_KEY_HERE\" });\r\n\r\nclient.on(\"post\", (post) => {\r\n  console.log(`${post.post_type} from @${post.username}: ${post.text}`);\r\n});\r\n\r\nawait client.connect();\r\nawait client.track(\"natgeo\");\r\n```\r\n\r\n### News\r\n\r\n```ts\r\nimport { createClient } from \"1322-client\";\r\n\r\nconst client = createClient({ platform: \"news\", apiKey: \"YOUR_API_KEY_HERE\" });\r\n\r\nclient.on(\"article\", (article) => {\r\n  console.log(`[${article.feed}] ${article.title}`);\r\n});\r\n\r\n// wsPath/wsKey are optional -- if omitted, connect() fetches them from\r\n// GET /v1/dashboard automatically before opening the socket.\r\nawait client.connect();\r\nawait client.track(\"BBC News\"); // subscribes to the named feed\r\n```\r\n\r\n### Binance Square\r\n\r\n```ts\r\nimport { createClient } from \"1322-client\";\r\n\r\nconst client = createClient({ platform: \"binance\", apiKey: \"YOUR_API_KEY_HERE\" });\r\n\r\nclient.on(\"post\", (post) => {\r\n  console.log(`@${post.username}: ${post.text ?? post.title} ${post.coin_pairs?.join(\",\") ?? \"\"}`);\r\n});\r\n\r\nclient.on(\"pinUpdate\", (update) => {\r\n  console.log(`pin change for @${update.username}`);\r\n});\r\n\r\nawait client.connect(); // wsPath/wsKey auto-fetched from GET /v1/dashboard if omitted\r\nawait client.track(\"CZ_Binance\");\r\n```\r\n\r\n### YouTube\r\n\r\n```ts\r\nimport { createClient } from \"1322-client\";\r\n\r\nconst client = createClient({\r\n  platform: \"youtube\",\r\n  // https://1322.io/docs does not publish a fixed base URL, path format, or\r\n  // auth scheme for the YouTube WebSocket the way it does for the other\r\n  // five platforms -- copy the exact URL issued for your account from the\r\n  // 1322 dashboard. track()/untrack()/list() are unavailable for the same\r\n  // reason; manage tracked channels from the dashboard.\r\n  wsUrl: \"YOUR_YOUTUBE_WS_URL_HERE\",\r\n});\r\n\r\nclient.on(\"upload\", (msg) => console.log(`new ${msg.subtype}: ${msg.video.title}`));\r\nclient.on(\"upgrade\", (msg) => console.log(`thumbnail upgraded: ${msg.upgrade.video_id}`));\r\nclient.on(\"deletion\", (msg) => console.log(`removed: ${msg.video.id}`));\r\n\r\nawait client.connect();\r\n```\r\n\r\n## Reconnect behavior\r\n\r\nEvery client reconnects automatically after an unexpected disconnect, using\r\nthe exponential backoff documented at\r\n[1322.io/docs](https://1322.io/docs): **1s, 2s, 4s, 8s, 16s, capped at 30s.**\r\nNo events are queued while disconnected -- you may miss events while offline,\r\nsame as the raw WebSocket. `connect()` resolves once the socket has opened\r\nfor the first time; later drops reconnect in the background and emit\r\n`reconnecting` / `open` / `close`, without needing you to await anything\r\nagain.\r\n\r\n```ts\r\nconst client = createClient({\r\n  platform: \"x\",\r\n  apiKey: \"YOUR_API_KEY_HERE\",\r\n  reconnect: {\r\n    enabled: true, // set false to disable auto-reconnect entirely\r\n    initialDelayMs: 1000,\r\n    maxDelayMs: 30000,\r\n    factor: 2,\r\n    jitter: 0, // e.g. 0.2 for +/-20% jitter, useful when running many instances\r\n  },\r\n});\r\n```\r\n\r\nCall `client.disconnect()` to close the connection and stop reconnecting.\r\n\r\n## X additive merge and dedup\r\n\r\nThe X WebSocket sends a tweet in progressively richer stages\r\n(`tweet.mini.update` -> `tweet.update` -> `tweet.update.expanded` ->\r\n`tweet.full`), each one enriching the last, per the docs' \"Additive Merge\"\r\nguidance. This package implements that merge for you: every stage for the\r\nsame tweet id is combined into one `MergedTweet` record --\r\n\r\n- the longest `body.text` wins\r\n- media arrays are unioned\r\n- the deepest `subtweet` chain is kept\r\n- metrics take the highest value seen\r\n- a populated field is never overwritten with `null`\r\n\r\n-- and emitted as the `tweet` event. The merge is order-tolerant (useful for\r\n`tier: \"hybrid\"`, where the same tweet id can arrive on both streams) and\r\nruns against a bounded, TTL-expiring cache (`merge: { maxSize, ttlMs }` in\r\nthe config; defaults to 200 entries / 5 minutes) so long-running processes\r\ndon't leak memory. Disable it with `merge: { enabled: false }` if you'd\r\nrather handle the raw per-stage events yourself.\r\n\r\n```ts\r\nimport { TweetMergeCache, mergeIncomingTweet } from \"1322-client\";\r\n\r\n// Both are exported directly if you want the merge logic without the WebSocket client.\r\n```\r\n\r\n## Status\r\n\r\nThis package is feature-complete and tested but **not yet published to\r\nnpm** -- install with `npm install git+https://github.com/SisoSol/1322-client.git`\r\nin the meantime (see [Install](#install)). The package name is the unscoped\r\n`1322-client`; a scoped `@1322/client` alias may be published later if a\r\n`1322` npm organization is set up, but unscoped works today without any\r\nextra account setup.\r\n\r\n## Development\r\n\r\n```bash\r\nnpm install\r\nnpm run build      # tsup -> dist/ (ESM + CJS + .d.ts)\r\nnpm run typecheck   # tsc --noEmit\r\nnpm test            # vitest run\r\n```\r\n\r\nTests cover reconnect backoff math, the WebSocket reconnect engine (fake\r\nsocket + fake timers, no network), the X additive-merge/dedup logic, per-platform\r\nevent parsing against real doc-derived payload shapes, the REST helper, and\r\nconfig validation. They intentionally do not hit the live 1322 API -- there's\r\nno way to test against real X/Truth/Instagram/etc. data without a paid API\r\nkey, so live-network behavior isn't covered by this suite.\r\n\r\n## Related\r\n\r\n- [1322.io](https://1322.io) -- the product this package is a client for\r\n- [1322.io/docs](https://1322.io/docs) -- full endpoint and payload reference\r\n- [1322.io/pricing](https://1322.io/pricing) -- plans start at $150/month (YouTube) and $250/month (X)\r\n- Single-platform example scripts: [social-monitor-examples](https://github.com/SisoSol/social-monitor-examples), [binance-square-realtime](https://github.com/SisoSol/binance-square-realtime)\r\n\r\n## License\r\n\r\nMIT, see [LICENSE](LICENSE).\r\n","readmeFilename":"README.md","_rev":"1-0b75c2b2f38aa06630ca13ea45ddadce"}