scrapebadger 0.1.9 → 0.3.0

package/dist/twitter/index.mjs

@@ -1,3 +1,7 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+import { EventEmitter } from 'events';
+import WebSocket from 'ws';
+
 // src/internal/pagination.ts
 function createPaginatedResponse(data, cursor) {
   return {
@@ -251,6 +255,7 @@ var TweetsClient = class {
         params: {
           query,
           query_type: options.queryType ?? "Top",
+          count: options.count,
           cursor: options.cursor
         }
       }
@@ -1138,6 +1143,688 @@ var GeoClient = class {
   }
 };
 
+// src/internal/exceptions.ts
+var ScrapeBadgerError = class _ScrapeBadgerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ScrapeBadgerError";
+    Object.setPrototypeOf(this, _ScrapeBadgerError.prototype);
+  }
+};
+var WebSocketStreamError = class _WebSocketStreamError extends ScrapeBadgerError {
+  /** WebSocket close code or server error code */
+  code;
+  constructor(message = "WebSocket stream error", code) {
+    super(message);
+    this.name = "WebSocketStreamError";
+    this.code = code;
+    Object.setPrototypeOf(this, _WebSocketStreamError.prototype);
+  }
+};
+
+// src/twitter/stream.ts
+var MIN_RECONNECT_DELAY_SECONDS = 5;
+function wsUrlFromBase(baseUrl) {
+  if (baseUrl.startsWith("https://")) {
+    return baseUrl.replace("https://", "wss://") + "/v1/twitter/stream";
+  }
+  if (baseUrl.startsWith("http://")) {
+    return baseUrl.replace("http://", "ws://") + "/v1/twitter/stream";
+  }
+  return baseUrl + "/v1/twitter/stream";
+}
+function parseEvent(raw) {
+  const type = raw["type"];
+  switch (type) {
+    case "connected":
+      return {
+        type: "connected",
+        connectionId: raw["connection_id"],
+        apiKeyId: raw["api_key_id"]
+      };
+    case "ping":
+      return {
+        type: "ping",
+        timestamp: raw["timestamp"]
+      };
+    case "tweet":
+      return {
+        type: "tweet",
+        monitorId: raw["monitor_id"],
+        tweetId: raw["tweet_id"],
+        authorUsername: raw["author_username"],
+        tweetPublishedAt: raw["tweet_published_at"],
+        detectedAt: raw["detected_at"],
+        latencyMs: raw["latency_ms"],
+        tweet: raw["tweet"]
+      };
+    case "error":
+      return {
+        type: "error",
+        code: raw["code"],
+        message: raw["message"]
+      };
+    default:
+      return {
+        type: "error",
+        code: 0,
+        message: `Unknown event type: ${String(type)}`
+      };
+  }
+}
+var StreamClient = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  // ===========================================================================
+  // Monitor CRUD
+  // ===========================================================================
+  /**
+   * Create a new stream monitor.
+   *
+   * @param params - Monitor configuration.
+   * @returns The created StreamMonitor.
+   * @throws InsufficientCreditsError - Credit balance below tier threshold (402).
+   * @throws ValidationError - Invalid username or interval (422).
+   * @throws ScrapeBadgerError - Name conflict (409).
+   * @throws AuthenticationError - Invalid API key (401).
+   *
+   * @example
+   * ```typescript
+   * const monitor = await client.twitter.stream.createMonitor({
+   *   name: "Breaking News",
+   *   usernames: ["cnnbrk", "bbcbreaking"],
+   *   pollIntervalSeconds: 5,
+   * });
+   * ```
+   */
+  async createMonitor(params) {
+    const body = {
+      name: params.name,
+      usernames: params.usernames,
+      poll_interval_seconds: params.pollIntervalSeconds
+    };
+    if (params.webhookUrl !== void 0) body["webhook_url"] = params.webhookUrl;
+    if (params.webhookSecret !== void 0) body["webhook_secret"] = params.webhookSecret;
+    return this.client.request("/v1/twitter/stream/monitors", {
+      method: "POST",
+      body
+    });
+  }
+  /**
+   * List stream monitors for the authenticated API key.
+   *
+   * @param options - Filter and pagination options.
+   * @returns StreamMonitorList with pagination metadata.
+   *
+   * @example
+   * ```typescript
+   * const { monitors, total } = await client.twitter.stream.listMonitors({
+   *   status: "active",
+   * });
+   * console.log(`${total} active monitors`);
+   * ```
+   */
+  async listMonitors(options) {
+    const params = {
+      page: options?.page ?? 1,
+      page_size: options?.pageSize ?? 20,
+      status: options?.status
+    };
+    return this.client.request("/v1/twitter/stream/monitors", {
+      params
+    });
+  }
+  /**
+   * Get a single stream monitor by ID.
+   *
+   * @param monitorId - UUID of the monitor.
+   * @returns The StreamMonitor.
+   * @throws NotFoundError - No monitor with that ID for this API key.
+   *
+   * @example
+   * ```typescript
+   * const monitor = await client.twitter.stream.getMonitor("550e8400-...");
+   * console.log(`${monitor.name}: ${monitor.status}`);
+   * ```
+   */
+  async getMonitor(monitorId) {
+    return this.client.request(`/v1/twitter/stream/monitors/${monitorId}`);
+  }
+  /**
+   * Partially update a stream monitor.
+   *
+   * Only fields that are explicitly set in params are sent to the server.
+   *
+   * @param monitorId - UUID of the monitor.
+   * @param params - Fields to update (all optional).
+   * @returns The updated StreamMonitor.
+   * @throws NotFoundError - Monitor not found for this API key.
+   * @throws InsufficientCreditsError - When resuming with insufficient credits.
+   *
+   * @example
+   * ```typescript
+   * const monitor = await client.twitter.stream.updateMonitor("550e8400-...", {
+   *   pollIntervalSeconds: 60,
+   * });
+   * ```
+   */
+  async updateMonitor(monitorId, params) {
+    const body = {};
+    if (params.name !== void 0) body["name"] = params.name;
+    if (params.usernames !== void 0) body["usernames"] = params.usernames;
+    if (params.pollIntervalSeconds !== void 0)
+      body["poll_interval_seconds"] = params.pollIntervalSeconds;
+    if (params.status !== void 0) body["status"] = params.status;
+    if (params.webhookUrl !== void 0) body["webhook_url"] = params.webhookUrl;
+    if (params.webhookSecret !== void 0) body["webhook_secret"] = params.webhookSecret;
+    return this.client.request(`/v1/twitter/stream/monitors/${monitorId}`, {
+      method: "PATCH",
+      body
+    });
+  }
+  /**
+   * Pause an active stream monitor.
+   *
+   * Convenience wrapper around updateMonitor({ status: "paused" }).
+   *
+   * @param monitorId - UUID of the monitor.
+   * @returns The updated StreamMonitor with status="paused".
+   */
+  async pauseMonitor(monitorId) {
+    return this.updateMonitor(monitorId, { status: "paused" });
+  }
+  /**
+   * Resume a paused stream monitor.
+   *
+   * Convenience wrapper around updateMonitor({ status: "active" }).
+   *
+   * @param monitorId - UUID of the monitor.
+   * @returns The updated StreamMonitor with status="active".
+   * @throws InsufficientCreditsError - If credits are below the tier threshold.
+   */
+  async resumeMonitor(monitorId) {
+    return this.updateMonitor(monitorId, { status: "active" });
+  }
+  /**
+   * Delete a stream monitor and all its associated logs. Irreversible.
+   *
+   * @param monitorId - UUID of the monitor.
+   * @throws NotFoundError - Monitor not found for this API key.
+   *
+   * @example
+   * ```typescript
+   * await client.twitter.stream.deleteMonitor("550e8400-...");
+   * ```
+   */
+  async deleteMonitor(monitorId) {
+    await this.client.request(`/v1/twitter/stream/monitors/${monitorId}`, {
+      method: "DELETE"
+    });
+  }
+  // ===========================================================================
+  // Delivery and Billing Logs
+  // ===========================================================================
+  /**
+   * List tweet delivery logs.
+   *
+   * @param options - Filter and pagination options.
+   * @returns DeliveryLogList with pagination metadata.
+   */
+  async listDeliveryLogs(options) {
+    const params = {
+      page: options?.page ?? 1,
+      page_size: options?.pageSize ?? 20,
+      sort: options?.sort ?? "desc",
+      monitor_id: options?.monitorId,
+      author_username: options?.authorUsername,
+      delivery_status: options?.deliveryStatus
+    };
+    return this.client.request("/v1/twitter/stream/logs", { params });
+  }
+  /**
+   * List billing activity logs.
+   *
+   * @param options - Filter and pagination options.
+   * @returns BillingLogList with pagination metadata.
+   */
+  async listBillingLogs(options) {
+    const params = {
+      page: options?.page ?? 1,
+      page_size: options?.pageSize ?? 20,
+      monitor_id: options?.monitorId
+    };
+    return this.client.request("/v1/twitter/stream/billing-logs", { params });
+  }
+  // ===========================================================================
+  // Filter Rules CRUD
+  // ===========================================================================
+  /**
+   * Create a new tweet filter rule.
+   *
+   * @param params - Filter rule configuration.
+   * @returns The created FilterRuleResponse.
+   * @throws ValidationError - Invalid query or interval (422).
+   * @throws InsufficientCreditsError - Credit balance below tier threshold (402).
+   * @throws AuthenticationError - Invalid API key (401).
+   *
+   * @example
+   * ```typescript
+   * const rule = await client.twitter.stream.createFilterRule({
+   *   tag: "python news",
+   *   query: "#python lang:en -is:retweet",
+   *   interval_seconds: 60,
+   * });
+   * console.log(`Created: ${rule.id}, tier: ${rule.pricing_tier}`);
+   * ```
+   */
+  async createFilterRule(params) {
+    const body = {
+      tag: params.tag,
+      query: params.query,
+      interval_seconds: params.interval_seconds
+    };
+    if (params.webhook_url !== void 0) body["webhook_url"] = params.webhook_url;
+    if (params.webhook_secret !== void 0) body["webhook_secret"] = params.webhook_secret;
+    if (params.max_results_per_poll !== void 0)
+      body["max_results_per_poll"] = params.max_results_per_poll;
+    return this.client.request("/v1/twitter/stream/filter-rules", {
+      method: "POST",
+      body
+    });
+  }
+  /**
+   * List filter rules for the authenticated API key.
+   *
+   * @param options - Filter and pagination options.
+   * @returns FilterRuleListResponse with pagination metadata.
+   *
+   * @example
+   * ```typescript
+   * const { rules, total } = await client.twitter.stream.listFilterRules({
+   *   status: "active",
+   * });
+   * console.log(`${total} active rules`);
+   * ```
+   */
+  async listFilterRules(options) {
+    const params = {
+      limit: options?.limit ?? 20,
+      offset: options?.offset ?? 0,
+      status: options?.status
+    };
+    return this.client.request("/v1/twitter/stream/filter-rules", {
+      params
+    });
+  }
+  /**
+   * Get a single filter rule by ID.
+   *
+   * @param ruleId - UUID of the filter rule.
+   * @returns The FilterRuleResponse.
+   * @throws NotFoundError - No rule with that ID for this API key.
+   *
+   * @example
+   * ```typescript
+   * const rule = await client.twitter.stream.getFilterRule("550e8400-...");
+   * console.log(`${rule.tag}: ${rule.status}`);
+   * ```
+   */
+  async getFilterRule(ruleId) {
+    return this.client.request(`/v1/twitter/stream/filter-rules/${ruleId}`);
+  }
+  /**
+   * Partially update a filter rule.
+   *
+   * Only fields that are explicitly set in params are sent to the server.
+   *
+   * @param ruleId - UUID of the filter rule.
+   * @param params - Fields to update (all optional).
+   * @returns The updated FilterRuleResponse.
+   * @throws NotFoundError - Rule not found for this API key.
+   * @throws ValidationError - Invalid field values (422).
+   *
+   * @example
+   * ```typescript
+   * const rule = await client.twitter.stream.updateFilterRule("550e8400-...", {
+   *   interval_seconds: 120,
+   * });
+   * ```
+   */
+  async updateFilterRule(ruleId, params) {
+    const body = {};
+    if (params.tag !== void 0) body["tag"] = params.tag;
+    if (params.query !== void 0) body["query"] = params.query;
+    if (params.interval_seconds !== void 0) body["interval_seconds"] = params.interval_seconds;
+    if (params.status !== void 0) body["status"] = params.status;
+    if (params.webhook_url !== void 0) body["webhook_url"] = params.webhook_url;
+    if (params.webhook_secret !== void 0) body["webhook_secret"] = params.webhook_secret;
+    if (params.max_results_per_poll !== void 0)
+      body["max_results_per_poll"] = params.max_results_per_poll;
+    return this.client.request(`/v1/twitter/stream/filter-rules/${ruleId}`, {
+      method: "PATCH",
+      body
+    });
+  }
+  /**
+   * Delete a filter rule and all its associated logs. Irreversible.
+   *
+   * @param ruleId - UUID of the filter rule.
+   * @throws NotFoundError - Rule not found for this API key.
+   *
+   * @example
+   * ```typescript
+   * await client.twitter.stream.deleteFilterRule("550e8400-...");
+   * ```
+   */
+  async deleteFilterRule(ruleId) {
+    await this.client.request(`/v1/twitter/stream/filter-rules/${ruleId}`, {
+      method: "DELETE"
+    });
+  }
+  // ===========================================================================
+  // Filter Rules Utility
+  // ===========================================================================
+  /**
+   * Validate a Twitter search query before creating a rule.
+   *
+   * @param query - The Twitter search query to validate.
+   * @returns FilterRuleValidateResponse with validity and sample result count.
+   *
+   * @example
+   * ```typescript
+   * const result = await client.twitter.stream.validateFilterRuleQuery(
+   *   "#python lang:en -is:retweet"
+   * );
+   * if (!result.valid) {
+   *   console.error("Invalid query:", result.error);
+   * }
+   * ```
+   */
+  async validateFilterRuleQuery(query) {
+    return this.client.request(
+      "/v1/twitter/stream/filter-rules/validate",
+      { method: "POST", body: { query } }
+    );
+  }
+  /**
+   * List tweet delivery logs for a specific filter rule.
+   *
+   * @param ruleId - UUID of the filter rule.
+   * @param options - Filter and pagination options.
+   * @returns FilterRuleDeliveryLogListResponse with pagination metadata.
+   *
+   * @example
+   * ```typescript
+   * const { logs, total } = await client.twitter.stream.listFilterRuleLogs(
+   *   "550e8400-...",
+   *   { limit: 50, deliveryStatus: "webhook_delivered" }
+   * );
+   * ```
+   */
+  async listFilterRuleLogs(ruleId, options) {
+    const params = {
+      limit: options?.limit ?? 20,
+      offset: options?.offset ?? 0,
+      sort: options?.sort ?? "desc",
+      delivery_status: options?.deliveryStatus
+    };
+    return this.client.request(
+      `/v1/twitter/stream/filter-rules/${ruleId}/logs`,
+      { params }
+    );
+  }
+  /**
+   * Get all available filter rule pricing tiers.
+   *
+   * @returns FilterRulePricingTiersResponse listing all tiers.
+   *
+   * @example
+   * ```typescript
+   * const { tiers } = await client.twitter.stream.getFilterRulePricingTiers();
+   * tiers.forEach((t) => console.log(t.tier_label, t.credits_per_rule_per_day));
+   * ```
+   */
+  async getFilterRulePricingTiers() {
+    return this.client.request(
+      "/v1/twitter/stream/filter-rules-pricing"
+    );
+  }
+  // ===========================================================================
+  // WebSocket Streaming -- EventEmitter style
+  // ===========================================================================
+  /**
+   * Connect to the WebSocket stream and return an EventEmitter.
+   *
+   * The caller subscribes to events via `.on("tweet", handler)`.
+   * The SDK handles pong replies to server pings automatically.
+   * Call `.close()` on the emitter to disconnect cleanly.
+   *
+   * If reconnect is true, the emitter automatically reconnects after
+   * disconnects (other than auth failures). A new "connected" event is
+   * emitted on each reconnect.
+   *
+   * @param options - Connection options (reconnect, delay, maxReconnects).
+   * @returns StreamEmitter -- an EventEmitter subclass.
+   *
+   * @example
+   * ```typescript
+   * const stream = client.twitter.stream.connect();
+   * stream.on("connected", (e) => console.log("Connected:", e.connectionId));
+   * stream.on("tweet", (event) => {
+   *   console.log(`@${event.authorUsername}: ${event.tweet.text}`);
+   *   console.log(`  latency: ${event.latencyMs}ms`);
+   * });
+   * stream.on("error", (err) => console.error("Stream error:", err));
+   * stream.on("close", () => console.log("Stream closed"));
+   *
+   * // Later:
+   * stream.close();
+   * ```
+   */
+  connect(options = {}) {
+    const { reconnect = false, reconnectDelaySeconds = 90, maxReconnects } = options;
+    const delay = Math.max(MIN_RECONNECT_DELAY_SECONDS, reconnectDelaySeconds) * 1e3;
+    const wsUrl = wsUrlFromBase(this.client.config.baseUrl);
+    const apiKey = this.client.config.apiKey;
+    const emitter = new EventEmitter();
+    let ws = null;
+    let closed = false;
+    let reconnectCount = 0;
+    const connectOnce = () => {
+      ws = new WebSocket(wsUrl, { headers: { "x-api-key": apiKey } });
+      ws.on("message", (data) => {
+        let raw;
+        try {
+          raw = JSON.parse(String(data));
+        } catch {
+          return;
+        }
+        const event = parseEvent(raw);
+        if (event.type === "ping") {
+          ws?.send(JSON.stringify({ type: "pong" }));
+          emitter.emit("ping", event);
+          return;
+        }
+        if (event.type === "error") {
+          const code = event.code;
+          const err = new WebSocketStreamError(event.message, code);
+          emitter.emit("error", err);
+          if (code === 4001 || code === 4003) {
+            closed = true;
+            ws?.close();
+          }
+          return;
+        }
+        emitter.emit(event.type, event);
+      });
+      ws.on("open", () => {
+      });
+      ws.on("close", (code, reason) => {
+        if (closed) {
+          emitter.emit("close");
+          return;
+        }
+        if (!reconnect) {
+          const reasonStr = reason instanceof Buffer ? reason.toString() : String(reason ?? "");
+          emitter.emit(
+            "error",
+            new WebSocketStreamError(`WebSocket closed: ${reasonStr || String(code)}`)
+          );
+          emitter.emit("close");
+          return;
+        }
+        if (maxReconnects !== void 0 && reconnectCount >= maxReconnects) {
+          emitter.emit(
+            "error",
+            new WebSocketStreamError(`Max reconnects (${maxReconnects}) exhausted`)
+          );
+          emitter.emit("close");
+          return;
+        }
+        reconnectCount++;
+        setTimeout(connectOnce, delay);
+      });
+      ws.on("error", (err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        emitter.emit("error", new WebSocketStreamError(message));
+      });
+    };
+    emitter.close = () => {
+      closed = true;
+      ws?.close(1e3, "Client closed");
+    };
+    connectOnce();
+    return emitter;
+  }
+  // ===========================================================================
+  // WebSocket Streaming -- AsyncIterator style
+  // ===========================================================================
+  /**
+   * Connect to the WebSocket stream and return an AsyncIterator.
+   *
+   * Iterates over StreamEvent objects. The SDK handles pong replies
+   * automatically but still yields PingEvent to the caller (the caller
+   * may ignore ping events).
+   *
+   * @param options - Connection options (reconnect, delay, maxReconnects).
+   * @yields StreamEvent
+   *
+   * @example
+   * ```typescript
+   * for await (const event of client.twitter.stream.connectIter()) {
+   *   if (event.type === "tweet") {
+   *     console.log(`@${event.authorUsername}: ${event.latencyMs}ms`);
+   *   }
+   * }
+   * ```
+   *
+   * @example With auto-reconnect
+   * ```typescript
+   * for await (const event of client.twitter.stream.connectIter({
+   *   reconnect: true,
+   *   reconnectDelaySeconds: 90,
+   * })) {
+   *   if (event.type === "tweet") {
+   *     // process(event);
+   *   }
+   * }
+   * ```
+   */
+  async *connectIter(options = {}) {
+    const { reconnect = false, reconnectDelaySeconds = 90, maxReconnects } = options;
+    const delay = Math.max(MIN_RECONNECT_DELAY_SECONDS, reconnectDelaySeconds) * 1e3;
+    const wsUrl = wsUrlFromBase(this.client.config.baseUrl);
+    const apiKey = this.client.config.apiKey;
+    let reconnectCount = 0;
+    while (true) {
+      const events = [];
+      let resolveWait = null;
+      let rejectWait = null;
+      let done = false;
+      const ws = new WebSocket(wsUrl, { headers: { "x-api-key": apiKey } });
+      const waitForEvent = () => new Promise((res, rej) => {
+        resolveWait = res;
+        rejectWait = rej;
+      });
+      ws.on("message", (data) => {
+        let raw;
+        try {
+          raw = JSON.parse(String(data));
+        } catch {
+          return;
+        }
+        const event = parseEvent(raw);
+        if (event.type === "ping") {
+          ws.send(JSON.stringify({ type: "pong" }));
+        }
+        if (event.type === "error") {
+          const code = event.code;
+          if (code === 4001 || code === 4003) {
+            rejectWait?.(new WebSocketStreamError(event.message, code));
+            rejectWait = null;
+            resolveWait = null;
+            return;
+          }
+        }
+        events.push(event);
+        resolveWait?.();
+        resolveWait = null;
+        rejectWait = null;
+      });
+      ws.on("close", () => {
+        done = true;
+        resolveWait?.();
+        resolveWait = null;
+        rejectWait = null;
+      });
+      ws.on("error", (err) => {
+        const message = err instanceof Error ? err.message : String(err);
+        rejectWait?.(new WebSocketStreamError(message));
+        rejectWait = null;
+        resolveWait = null;
+      });
+      try {
+        while (!done || events.length > 0) {
+          if (events.length === 0) {
+            await waitForEvent();
+          }
+          while (events.length > 0) {
+            yield events.shift();
+          }
+        }
+      } catch (err) {
+        ws.close();
+        throw err;
+      } finally {
+        ws.close();
+      }
+      if (!reconnect) {
+        return;
+      }
+      if (maxReconnects !== void 0 && reconnectCount >= maxReconnects) {
+        throw new WebSocketStreamError(`Max reconnects (${maxReconnects}) exhausted`);
+      }
+      reconnectCount++;
+      await new Promise((res) => setTimeout(res, delay));
+    }
+  }
+};
+function verifyWebhookSignature(secret, body, signatureHeader) {
+  if (!signatureHeader.startsWith("sha256=")) {
+    return false;
+  }
+  const expectedHex = signatureHeader.slice("sha256=".length);
+  const bodyBuffer = typeof body === "string" ? Buffer.from(body, "utf-8") : body;
+  const actualHex = createHmac("sha256", secret).update(bodyBuffer).digest("hex");
+  try {
+    return timingSafeEqual(Buffer.from(expectedHex, "hex"), Buffer.from(actualHex, "hex"));
+  } catch {
+    return false;
+  }
+}
+
 // src/twitter/client.ts
 var TwitterClient = class {
   /** Client for tweet operations */
@@ -1152,6 +1839,8 @@ var TwitterClient = class {
   trends;
   /** Client for geo/places operations */
   geo;
+  /** Client for real-time stream monitor management and WebSocket streaming */
+  stream;
   /**
    * Create a new Twitter client.
    *
@@ -1164,9 +1853,10 @@ var TwitterClient = class {
     this.communities = new CommunitiesClient(client);
     this.trends = new TrendsClient(client);
     this.geo = new GeoClient(client);
+    this.stream = new StreamClient(client);
   }
 };
 
-export { CommunitiesClient, GeoClient, ListsClient, TrendsClient, TweetsClient, TwitterClient, UsersClient };
+export { CommunitiesClient, GeoClient, ListsClient, StreamClient, TrendsClient, TweetsClient, TwitterClient, UsersClient, verifyWebhookSignature };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map