xnotif 0.1.1-beta.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuta Kobayashi
+
+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

@@ -2,6 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/xnotif)](https://www.npmjs.com/package/xnotif)
 [![CI](https://github.com/yutakobayashidev/xnotif/actions/workflows/ci.yml/badge.svg)](https://github.com/yutakobayashidev/xnotif/actions/workflows/ci.yml)
+[![DeepWiki](https://img.shields.io/badge/DeepWiki-yutakobayashidev%2Fxnotif-blue.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK/AIi+QuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06/uv1saEDv4O3n3dV60RfP947Mm9/SQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH//PB8mnKqScAhsD0kYP3j/Yt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY/56ebRWeraTjMt/00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ+fXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB/imwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE+gO0SsWmPiXB+jikdf6SizrT5qKasx5j8ABbHpFTx+vFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa+Ax283gghmj+vj7feE2KBBRMW3FzOpLOADl0Isb5587h/U4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5/XFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb/vA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU+3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26/HfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr/FGaKiG+T+v+TQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r/cKaoqr+27/XcrS5UwSMbQAAAABJRU5ErkJggg==)](https://deepwiki.com/yutakobayashidev/xnotif)
 
 Receive Twitter/X notifications in real-time. No API key, no scraping — just Web Push.
 
@@ -19,21 +20,55 @@ client.on("notification", (n) => {
 await client.start();
 ```
 
-## How It Works
-
-```
-Twitter ──▶ Mozilla Autopush (WebSocket) ──▶ AESGCM decrypt ──▶ EventEmitter
-```
-
-xnotif generates an ECDH key pair, registers it with Twitter's push endpoint using your session cookies, then listens on Mozilla's Autopush WebSocket. Incoming notifications are decrypted and emitted as typed events.
-
 ## Install
 
 ```bash
-bun add xnotif
+npm install xnotif
 ```
 
-> Requires Bun >= 1.0.0
+> Requires Node.js >= 22.0.0
+
+## Why xnotif
+
+- **Cookie exposure can be minimized** - Cookies are mainly used for one registration call to `POST /1.1/notifications/settings/login.json`. After registration, notifications are received through Mozilla Autopush WebSocket, so you are not continuously calling internal Twitter endpoints with cookies.
+- **Lower ban-risk profile than polling/scraping** - xnotif avoids headless-browser automation and high-frequency private API polling. The runtime traffic pattern is mostly one registration plus push-stream consumption.
+- **Avoid unnecessary re-registration** - If you persist `ClientState` from the `connected` event, restart with `state`, and the endpoint is unchanged, xnotif skips the registration call.
+- **Simple operations** - No API key provisioning, no webhook server, and no request-signing stack. A single Node.js process can receive and process notifications.
+
+## Notification Payload
+
+Each `notification` event delivers a `TwitterNotification` object:
+
+```jsonc
+{
+  "title": "@jack",
+  "body": "just setting up my twttr",
+  "icon": "https://pbs.twimg.com/profile_images/...",
+  "timestamp": 1142974214000,
+  "tag": "mention_12345",
+  "data": {
+    "type": "mention",
+    "uri": "https://x.com/i/web/status/20",
+    "title": "@jack",
+    "body": "just setting up my twttr",
+    "tag": "mention_12345",
+    "lang": "en",
+    "scribe_target": "mention",
+    "impression_id": "abc123",
+  },
+}
+```
+
+Top-level fields:
+
+| Field       | Type      | Description                                       |
+| ----------- | --------- | ------------------------------------------------- |
+| `title`     | `string`  | Who triggered the notification                    |
+| `body`      | `string`  | Human-readable description                        |
+| `icon`      | `string?` | Profile image URL                                 |
+| `timestamp` | `number?` | Unix epoch in milliseconds                        |
+| `tag`       | `string?` | Deduplication tag                                 |
+| `data`      | `object?` | Structured metadata (see `data.type` for routing) |
 
 ## Getting Cookies
 
@@ -61,10 +96,24 @@ await client.start();
 
 ### `createClient(options)`
 
-| Option    | Type                                  | Required | Description            |
-| --------- | ------------------------------------- | -------- | ---------------------- |
-| `cookies` | `{ auth_token: string; ct0: string }` | Yes      | Session cookies        |
-| `state`   | `ClientState`                         | No       | Restore previous state |
+| Option    | Type                                             | Required | Description                       |
+| --------- | ------------------------------------------------ | -------- | --------------------------------- |
+| `cookies` | `{ auth_token: string; ct0: string }`            | Yes      | Session cookies                   |
+| `state`   | `ClientState`                                    | No       | Restore previous state            |
+| `filter`  | `(notification: TwitterNotification) => boolean` | No       | Predicate to filter notifications |
+
+#### Filtering Notifications
+
+Pass a `filter` function to receive only the notifications you care about:
+
+```typescript
+const client = createClient({
+  cookies: { auth_token: "...", ct0: "..." },
+  filter: (n) => n.data?.type === "tweet",
+});
+```
+
+The predicate receives the decrypted `TwitterNotification` object. Return `true` to emit the notification, `false` to discard it silently. If the filter throws an exception, the notification is discarded and an `error` event is emitted.
 
 ### Events
 
@@ -86,6 +135,37 @@ await client.start();
 - `Decryptor` — AESGCM Web Push decryption (ECDH + HKDF + AES-128-GCM)
 - `AutopushClient` — Mozilla Autopush WebSocket client
 
+## How It Works
+
+```mermaid
+sequenceDiagram
+    participant App as xnotif
+    participant Autopush as Mozilla Autopush<br/>wss://push.services.mozilla.com
+    participant Twitter as Twitter/X
+
+    App->>App: Generate ECDH P-256 key pair + 16-byte auth secret
+    App->>Autopush: WebSocket connect (subprotocol: push-notification)
+    Autopush-->>App: hello ACK (uaid assigned)
+    App->>Autopush: Register channel with VAPID key
+    Autopush-->>App: Push Endpoint URL
+
+    App->>Twitter: POST /1.1/notifications/settings/login.json<br/>{ token: endpoint, encryption_key1: p256dh, encryption_key2: auth }
+    Twitter-->>App: 200 OK
+
+    loop Real-time notifications
+        Twitter->>Autopush: Web Push (AESGCM encrypted payload)
+        Autopush->>App: WebSocket message
+        App->>App: ECDH shared secret (256-bit)<br/>→ HKDF-SHA256 (IKM, CEK, nonce)<br/>→ AES-128-GCM decrypt<br/>→ Strip 2-byte padding
+        App-->>App: Emit "notification" event
+    end
+```
+
+1. **Key generation** — Generate an ECDH P-256 key pair and a 16-byte auth secret via `crypto.subtle` (skipped when restoring from saved `state`)
+2. **Autopush connection** — Open a WebSocket to `wss://push.services.mozilla.com` with the `push-notification` subprotocol, send a `hello` handshake, then register a channel to obtain a Push Endpoint URL
+3. **Twitter registration** — POST the Push Endpoint, base64url-encoded public key, and auth secret to Twitter's `/1.1/notifications/settings/login.json`, authenticated with your session cookies (`auth_token` / `ct0`)
+4. **Receive & decrypt** — When Twitter pushes an AESGCM-encrypted payload through Autopush, derive a shared secret via ECDH, expand it with HKDF-SHA256 into a 16-byte CEK and 12-byte nonce, then decrypt with AES-128-GCM
+5. **Emit** — Parse the decrypted JSON into a `TwitterNotification` and fire it as a `notification` event
+
 ## License
 
 MIT

package/dist/index.d.mts

@@ -0,0 +1,115 @@
+import { EventEmitter } from "events";
+
+//#region src/types.d.ts
+interface AutopushNotification {
+  messageType: "notification";
+  channelID: string;
+  version: string;
+  data: string;
+  headers: {
+    crypto_key: string;
+    encryption: string;
+  };
+}
+interface TwitterNotification {
+  title: string;
+  body: string;
+  icon?: string;
+  timestamp?: number;
+  tag?: string;
+  data?: {
+    type?: string;
+    uri?: string;
+    title?: string;
+    body?: string;
+    tag?: string;
+    lang?: string;
+    bundle_text?: string;
+    scribe_target?: string;
+    impression_id?: string;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+interface ClientState {
+  uaid: string;
+  channelId: string;
+  endpoint: string;
+  remoteBroadcasts: Record<string, string>;
+  decryptor: {
+    jwk: JsonWebKey;
+    auth: string;
+  };
+}
+interface NotificationClientOptions {
+  cookies: {
+    auth_token: string;
+    ct0: string;
+    [key: string]: string;
+  };
+  state?: ClientState;
+  filter?: (notification: TwitterNotification) => boolean;
+}
+//#endregion
+//#region src/client.d.ts
+interface NotificationClientEvents {
+  notification: [notification: TwitterNotification];
+  connected: [state: ClientState];
+  error: [error: Error];
+  disconnected: [];
+  reconnecting: [delay: number];
+}
+declare class NotificationClient extends EventEmitter<NotificationClientEvents> {
+  private autopush;
+  private running;
+  private options;
+  constructor(options: NotificationClientOptions);
+  start(): Promise<void>;
+  stop(): void;
+}
+declare function createClient(options: NotificationClientOptions): NotificationClient;
+//#endregion
+//#region src/decrypt.d.ts
+declare class Decryptor {
+  private keyPair;
+  private publicKeyRaw;
+  private authSecret;
+  private jwk;
+  private constructor();
+  static create(jwk?: JsonWebKey, authBase64url?: string): Promise<Decryptor>;
+  getJwk(): JsonWebKey;
+  getAuthBase64url(): string;
+  getPublicKeyBase64url(): string;
+  decrypt(cryptoKeyHeader: string, encryptionHeader: string, payload: ArrayBuffer): Promise<string>;
+}
+//#endregion
+//#region src/autopush.d.ts
+interface AutopushOptions {
+  uaid?: string;
+  channelId: string;
+  vapidKey: string;
+  remoteBroadcasts?: Record<string, string>;
+  onNotification: (notification: AutopushNotification) => void;
+  onError?: (error: unknown) => void;
+  onDisconnected?: () => void;
+  onReconnecting?: (delay: number) => void;
+}
+declare class AutopushClient {
+  private options;
+  private ws;
+  private uaid;
+  private endpoint;
+  private reconnectDelay;
+  private closed;
+  private remoteBroadcasts;
+  constructor(options: AutopushOptions);
+  getUaid(): string;
+  getEndpoint(): string;
+  getRemoteBroadcasts(): Record<string, string>;
+  connect(): Promise<string>;
+  close(): void;
+  private send;
+  private reconnect;
+}
+//#endregion
+export { AutopushClient, type AutopushNotification, type AutopushOptions, type ClientState, Decryptor, NotificationClient, type NotificationClientOptions, type TwitterNotification, createClient };