@lazyneoaz/metachat 4.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 @lazyneoaz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,152 @@
+# MetaChat
+
+<p align="center">
+  <img src="./assets/banner.svg" alt="MetaChat — real-time Messenger automation" />
+</p>
+
+MetaChat is a TypeScript client for automating Facebook Messenger conversations.
+It provides authenticated HTTP and MQTT APIs for messaging, thread management,
+user lookup, attachments, reactions, music search, and theme operations.
+
+## Requirements
+
+- Node.js 18 or newer
+- A Facebook session supplied as an app state cookie array or cookie string
+- An account authorized to use the requested Facebook features
+
+## Installation
+
+```bash
+npm install @lazyneoaz/metachat
+```
+
+## Quick start
+
+```ts
+import { login } from "@lazyneoaz/metachat";
+
+const api = await login({ appState: process.env.FACEBOOK_APP_STATE });
+
+api.listenMqtt((error, event) => {
+  if (error) {
+    console.error(error);
+    return;
+  }
+
+  if (event.type === "message" && event.body === "ping") {
+    void api.sendMessage("pong", event.threadID);
+  }
+});
+```
+
+The login callback form is also supported:
+
+```ts
+login({ appState: cookies }, (error, api) => {
+  if (error) throw error;
+  api.sendMessage("Connected", threadID);
+});
+```
+
+## Authentication and options
+
+```ts
+const api = await login(
+  { appState: cookies },
+  {
+    listenEvents: true,
+    selfListen: false,
+    autoReconnect: true,
+    autoMarkRead: false,
+    updatePresence: false,
+    proxy: "http://host:port",
+  },
+);
+```
+
+`appState` may be an array of cookie objects or a semicolon-separated cookie
+string. Email and password credentials are also accepted, but app state is the
+preferred authentication method.
+
+Each login creates an independent session with its own cookie jar and options.
+The MQTT listener reconnects automatically after transient connection failures.
+Call `api.logout()` when the session should stop reconnecting.
+
+## Common operations
+
+```ts
+await api.sendMessage("Hello", threadID);
+await api.sendMessage(
+  { body: "Here is a file", attachment: fileStream },
+  threadID,
+);
+
+await api.getThreadInfo(threadID);
+await api.getThreadHistory(threadID, 20, null);
+await api.getUserInfo(userID);
+await api.setMessageReaction("👍", messageID);
+await api.markAsRead(threadID);
+```
+
+Methods that support callbacks also return promises. The callback uses the
+Node.js convention `(error, result)`.
+
+## Music search
+
+```ts
+const result = await api.searchMusic("lofi beats", { count: 10 });
+
+for (const track of result.tracks) {
+  console.log(track.title, track.artist, track.audioUrl);
+}
+```
+
+The result preserves Facebook's ordering and includes pagination metadata:
+
+```ts
+{
+  tracks: MusicTrack[],
+  endCursor: string | null,
+  hasNextPage: boolean,
+  query: string
+}
+```
+
+## MQTT listeners
+
+`listenMqtt` delivers messages and enabled event types in real time. The
+connection uses automatic reconnect with bounded backoff and continues trying
+until the listener is stopped, the session is logged out, or
+`autoReconnect` is disabled.
+
+```ts
+const listener = api.listenMqtt((error, event) => {
+  if (error) {
+    console.error(error);
+    return;
+  }
+  console.log(event);
+});
+
+listener.stop();
+```
+
+`listenSpeed` is available as a lightweight alternative for applications that
+do not require a persistent MQTT connection.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm test
+```
+
+## License
+
+MIT
+
+Facebook and Messenger are trademarks of Meta Platforms, Inc. This project is
+not affiliated with or endorsed by Meta Platforms, Inc. Facebook may change
+internal APIs without notice.

package/assets/banner.svg

@@ -0,0 +1,69 @@
+<svg width="1200" height="420" viewBox="0 0 1200 420" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="title desc">
+  <title id="title">MetaChat</title>
+  <desc id="desc">Animated gradient banner for MetaChat Messenger automation.</desc>
+  <defs>
+    <linearGradient id="background" x1="0" y1="0" x2="1200" y2="420" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#090B18"/>
+      <stop offset="0.52" stop-color="#17133A"/>
+      <stop offset="1" stop-color="#071D2A"/>
+    </linearGradient>
+    <linearGradient id="accent" x1="220" y1="92" x2="924" y2="322" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#A78BFA"/>
+      <stop offset="0.5" stop-color="#38BDF8"/>
+      <stop offset="1" stop-color="#2DD4BF"/>
+    </linearGradient>
+    <radialGradient id="glow">
+      <stop stop-color="#8B5CF6" stop-opacity="0.55"/>
+      <stop offset="1" stop-color="#8B5CF6" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="blur" x="-100%" y="-100%" width="300%" height="300%">
+      <feGaussianBlur stdDeviation="28"/>
+    </filter>
+    <filter id="shadow" x="-30%" y="-30%" width="160%" height="180%">
+      <feDropShadow dx="0" dy="18" stdDeviation="20" flood-color="#000000" flood-opacity="0.35"/>
+    </filter>
+    <pattern id="grid" width="48" height="48" patternUnits="userSpaceOnUse">
+      <path d="M48 0H0V48" stroke="#FFFFFF" stroke-opacity="0.06"/>
+    </pattern>
+  </defs>
+
+  <rect width="1200" height="420" rx="32" fill="url(#background)"/>
+  <rect width="1200" height="420" rx="32" fill="url(#grid)"/>
+  <circle cx="152" cy="72" r="190" fill="url(#glow)" filter="url(#blur)">
+    <animate attributeName="cx" values="152;240;152" dur="9s" repeatCount="indefinite"/>
+    <animate attributeName="cy" values="72;130;72" dur="9s" repeatCount="indefinite"/>
+  </circle>
+  <circle cx="1050" cy="360" r="220" fill="url(#glow)" filter="url(#blur)" opacity="0.7">
+    <animate attributeName="cx" values="1050;940;1050" dur="11s" repeatCount="indefinite"/>
+    <animate attributeName="cy" values="360;300;360" dur="11s" repeatCount="indefinite"/>
+  </circle>
+
+  <g opacity="0.85">
+    <path d="M80 318C242 248 266 366 420 296C574 226 616 332 752 270C888 208 949 304 1120 210" stroke="url(#accent)" stroke-width="2" stroke-linecap="round" stroke-dasharray="8 14">
+      <animate attributeName="stroke-dashoffset" from="0" to="-220" dur="7s" repeatCount="indefinite"/>
+    </path>
+    <circle cx="420" cy="296" r="5" fill="#38BDF8">
+      <animate attributeName="r" values="4;9;4" dur="2.5s" repeatCount="indefinite"/>
+      <animate attributeName="opacity" values="1;0.35;1" dur="2.5s" repeatCount="indefinite"/>
+    </circle>
+    <circle cx="752" cy="270" r="5" fill="#2DD4BF">
+      <animate attributeName="r" values="4;9;4" dur="2.2s" begin="0.7s" repeatCount="indefinite"/>
+      <animate attributeName="opacity" values="1;0.35;1" dur="2.2s" begin="0.7s" repeatCount="indefinite"/>
+    </circle>
+  </g>
+
+  <g filter="url(#shadow)">
+    <rect x="86" y="88" width="74" height="74" rx="22" fill="#FFFFFF" fill-opacity="0.08" stroke="#FFFFFF" stroke-opacity="0.18"/>
+    <path d="M105 111C105 104.373 110.373 99 117 99H129C135.627 99 141 104.373 141 111V123C141 129.627 135.627 135 129 135H122L114 143V135H117C110.373 135 105 129.627 105 123V111Z" stroke="url(#accent)" stroke-width="3"/>
+    <circle cx="116" cy="117" r="2.5" fill="#A78BFA"/>
+    <circle cx="123" cy="117" r="2.5" fill="#38BDF8"/>
+    <circle cx="130" cy="117" r="2.5" fill="#2DD4BF"/>
+  </g>
+
+  <text x="86" y="236" fill="white" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="74" font-weight="800" letter-spacing="8">METACHAT</text>
+  <text x="92" y="274" fill="#C4B5FD" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="18" font-weight="600" letter-spacing="4">REAL-TIME MESSENGER AUTOMATION</text>
+  <text x="92" y="304" fill="#2DD4BF" font-family="Inter,Segoe UI,Arial,sans-serif" font-size="15" font-weight="600" letter-spacing="2">by @lazyneoaz</text>
+  <rect x="92" y="324" width="128" height="4" rx="2" fill="url(#accent)">
+    <animate attributeName="width" values="64;180;64" dur="3.5s" repeatCount="indefinite"/>
+  </rect>
+</svg>