scrapebadger 0.1.9 → 0.3.0

package/dist/{index-9Mu-b1MB.d.ts → index-DQ_jDTcQ.d.ts}

@@ -1,3 +1,5 @@
+import { EventEmitter } from 'node:events';
+
 /**
  * Configuration management for the ScrapeBadger SDK.
  */
@@ -35,7 +37,7 @@ interface RequestOptions {
  * Base HTTP client for making API requests.
  */
 declare class BaseClient {
-    private readonly config;
+    readonly config: ResolvedConfig;
     constructor(config: ResolvedConfig);
     /**
      * Make an HTTP request to the API.
@@ -254,6 +256,26 @@ interface Tweet {
     username?: string;
     /** Author's display name */
     user_name?: string;
+    /** Author's profile image URL */
+    user_profile_image_url?: string;
+    /** Author's bio */
+    user_description?: string;
+    /** Author's location */
+    user_location?: string;
+    /** Author's website URL */
+    user_url?: string;
+    /** Author's follower count */
+    user_followers_count?: number;
+    /** Author's following count */
+    user_following_count?: number;
+    /** Author's tweet count */
+    user_tweet_count?: number;
+    /** Author's legacy verification status */
+    user_verified?: boolean;
+    /** Author's Twitter Blue verification status */
+    user_is_blue_verified?: boolean;
+    /** Author's account creation date */
+    user_created_at?: string;
     /** Number of likes */
     favorite_count: number;
     /** Number of retweets */
@@ -928,6 +950,7 @@ declare class TweetsClient {
      */
     search(query: string, options?: PaginationOptions & {
         queryType?: QueryType;
+        count?: number;
     }): Promise<PaginatedResponse<Tweet>>;
     /**
      * Iterate through all search results with automatic pagination.
@@ -957,6 +980,7 @@ declare class TweetsClient {
      */
     searchAll(query: string, options?: IteratorOptions & {
         queryType?: QueryType;
+        count?: number;
     }): AsyncGenerator<Tweet, void, undefined>;
     /**
      * Get tweets from a user's timeline.
@@ -1741,6 +1765,948 @@ declare class GeoClient {
     search(options?: GeoSearchOptions): Promise<PaginatedResponse<Place>>;
 }
 
+/**
+ * Custom exceptions for the ScrapeBadger SDK.
+ */
+/**
+ * Base error class for all ScrapeBadger errors.
+ */
+declare class ScrapeBadgerError extends Error {
+    constructor(message: string);
+}
+/**
+ * Raised when authentication fails (invalid or missing API key).
+ */
+declare class AuthenticationError extends ScrapeBadgerError {
+    constructor(message?: string);
+}
+/**
+ * Raised when rate limit is exceeded.
+ */
+declare class RateLimitError extends ScrapeBadgerError {
+    /** Unix timestamp when the rate limit resets */
+    readonly retryAfter: number | undefined;
+    /** Maximum requests per minute for this tier */
+    readonly limit: number | undefined;
+    /** Remaining requests in the current window */
+    readonly remaining: number | undefined;
+    constructor(message?: string, options?: {
+        retryAfter?: number;
+        limit?: number;
+        remaining?: number;
+    });
+}
+/**
+ * Raised when the requested resource is not found.
+ */
+declare class NotFoundError extends ScrapeBadgerError {
+    /** The resource type that was not found */
+    readonly resourceType: string | undefined;
+    /** The resource ID that was not found */
+    readonly resourceId: string | undefined;
+    constructor(message?: string, resourceType?: string, resourceId?: string);
+}
+/**
+ * Raised when the request is invalid.
+ */
+declare class ValidationError extends ScrapeBadgerError {
+    /** Validation errors by field */
+    readonly errors: Record<string, string[]> | undefined;
+    constructor(message?: string, errors?: Record<string, string[]>);
+}
+/**
+ * Raised when an internal server error occurs.
+ */
+declare class ServerError extends ScrapeBadgerError {
+    /** HTTP status code */
+    readonly statusCode: number;
+    constructor(message?: string, statusCode?: number);
+}
+/**
+ * Raised when the request times out.
+ */
+declare class TimeoutError extends ScrapeBadgerError {
+    /** Timeout duration in milliseconds */
+    readonly timeout: number;
+    constructor(message: string | undefined, timeout: number);
+}
+/**
+ * Raised when the account has insufficient credits.
+ */
+declare class InsufficientCreditsError extends ScrapeBadgerError {
+    /** Current credit balance */
+    readonly creditsBalance: number | undefined;
+    constructor(message?: string, creditsBalance?: number);
+}
+/**
+ * Raised when the account is restricted.
+ */
+declare class AccountRestrictedError extends ScrapeBadgerError {
+    /** Reason for the restriction */
+    readonly reason: string | undefined;
+    constructor(message?: string, reason?: string);
+}
+/**
+ * Raised when a resource conflict occurs (e.g. duplicate monitor name).
+ *
+ * Maps to HTTP 409 Conflict.
+ *
+ * @example
+ * ```typescript
+ * import { ConflictError } from "scrapebadger";
+ *
+ * try {
+ *   await client.twitter.stream.createMonitor({
+ *     name: "Existing Monitor",
+ *     usernames: ["elonmusk"],
+ *     pollIntervalSeconds: 10,
+ *   });
+ * } catch (err) {
+ *   if (err instanceof ConflictError) {
+ *     console.error("Monitor name already exists:", err.message);
+ *   }
+ * }
+ * ```
+ */
+declare class ConflictError extends ScrapeBadgerError {
+    constructor(message?: string);
+}
+/**
+ * Raised when the WebSocket stream connection fails or is terminated.
+ *
+ * Common codes:
+ * - 4001 -- Invalid or missing API key (auth failure)
+ * - 4003 -- Connection limit exceeded (max 5 per API key)
+ * - 1001 -- Server closed due to pong timeout
+ * - 0    -- Unknown/parse error
+ *
+ * @example
+ * ```typescript
+ * import { WebSocketStreamError } from "scrapebadger";
+ *
+ * try {
+ *   for await (const event of client.twitter.stream.connectIter()) {
+ *     // ...
+ *   }
+ * } catch (err) {
+ *   if (err instanceof WebSocketStreamError && err.code === 4001) {
+ *     console.error("API key rejected -- check your key");
+ *   }
+ * }
+ * ```
+ */
+declare class WebSocketStreamError extends ScrapeBadgerError {
+    /** WebSocket close code or server error code */
+    readonly code: number | undefined;
+    constructor(message?: string, code?: number);
+}
+
+/**
+ * TypeScript types for Twitter Streams API.
+ */
+/**
+ * Lifecycle status of a stream monitor.
+ */
+type MonitorStatus = "active" | "paused" | "error";
+/**
+ * A stream monitor watching a set of Twitter accounts.
+ */
+interface StreamMonitor {
+    /** UUID of the monitor */
+    id: string;
+    /** Human-readable label */
+    name: string;
+    /** Lowercased Twitter handles being monitored */
+    usernames: string[];
+    /** How often the monitor polls in seconds */
+    poll_interval_seconds: number;
+    /** Current lifecycle state */
+    status: MonitorStatus;
+    /** Human-readable reason for non-active status */
+    status_reason: string | null;
+    /** HTTPS delivery URL, or null */
+    webhook_url: string | null;
+    /** Whether a signing secret is configured */
+    webhook_secret_set: boolean;
+    /** Projected credit burn rate */
+    estimated_credits_per_hour: number;
+    /** Tier label (Ultra, High, Standard, Low, Minimal) */
+    pricing_tier: string;
+    /** ISO timestamp of creation */
+    created_at: string;
+    /** ISO timestamp of last modification */
+    updated_at: string;
+}
+/**
+ * Paginated list of stream monitors.
+ */
+interface StreamMonitorList {
+    /** The monitors on this page */
+    monitors: StreamMonitor[];
+    /** Total count across all pages */
+    total: number;
+    /** Current page number (1-indexed) */
+    page: number;
+    /** Number of items per page */
+    page_size: number;
+}
+/**
+ * Create monitor request parameters.
+ */
+interface CreateMonitorParams {
+    /** Display name (1-100 chars) */
+    name: string;
+    /** Twitter handles to monitor (1-100 items) */
+    usernames: string[];
+    /** Polling interval in seconds (>= 0.1) */
+    pollIntervalSeconds: number;
+    /** Optional HTTPS webhook URL */
+    webhookUrl?: string;
+    /** Optional signing secret */
+    webhookSecret?: string;
+}
+/**
+ * Update monitor request parameters (all fields optional).
+ */
+interface UpdateMonitorParams {
+    /** New display name */
+    name?: string;
+    /** Replacement list of Twitter handles */
+    usernames?: string[];
+    /** New polling interval */
+    pollIntervalSeconds?: number;
+    /** New status ("active" or "paused") */
+    status?: "active" | "paused";
+    /** New webhook URL (empty string clears it) */
+    webhookUrl?: string;
+    /** New signing secret */
+    webhookSecret?: string;
+}
+/**
+ * Type discriminator for WebSocket events.
+ */
+type StreamEventType = "connected" | "ping" | "tweet" | "error";
+/**
+ * A tweet payload embedded in a TweetEvent.
+ */
+interface StreamTweet {
+    /** Snowflake tweet ID */
+    id: string;
+    /** Tweet text content */
+    text: string;
+    /** Raw created_at string from Twikit */
+    created_at?: string;
+    /** Author numeric ID as string */
+    user_id?: string;
+    /** Author handle (without @) */
+    username?: string;
+    /** Author display name */
+    user_name?: string;
+    /** Like count at detection time */
+    favorite_count: number;
+    /** Retweet count at detection time */
+    retweet_count: number;
+    /** Reply count at detection time */
+    reply_count: number;
+    /** Attached media */
+    media: Record<string, unknown>[];
+    /** URL entities */
+    urls: Record<string, unknown>[];
+    /** Hashtag entities */
+    hashtags: Record<string, unknown>[];
+}
+/**
+ * Emitted immediately after a successful WebSocket upgrade.
+ */
+interface ConnectedEvent {
+    type: "connected";
+    /** Server-assigned UUID for this connection */
+    connectionId: string;
+    /** The API key identifier used */
+    apiKeyId: string;
+}
+/**
+ * Server keepalive ping. SDK responds with pong automatically.
+ */
+interface PingEvent {
+    type: "ping";
+    /** Server timestamp in ISO format */
+    timestamp: string;
+}
+/**
+ * A new tweet detected by one of the caller's monitors.
+ */
+interface TweetEvent {
+    type: "tweet";
+    /** UUID of the monitor that detected this tweet */
+    monitorId: string;
+    /** Snowflake tweet ID as string */
+    tweetId: string;
+    /** Lowercased Twitter handle of the author */
+    authorUsername: string;
+    /** ISO timestamp decoded from Snowflake */
+    tweetPublishedAt: string;
+    /** ISO timestamp of server-side detection */
+    detectedAt: string;
+    /** Milliseconds between tweet publish and detection */
+    latencyMs: number;
+    /** Full tweet data snapshot */
+    tweet: StreamTweet;
+}
+/**
+ * Server-side error event (sent before connection close on auth failure).
+ */
+interface ErrorEvent {
+    type: "error";
+    /** Numeric error code (4001 = auth, 4003 = connection limit) */
+    code: number;
+    /** Human-readable description */
+    message: string;
+}
+/**
+ * Union of all possible WebSocket event types.
+ */
+type StreamEvent = ConnectedEvent | PingEvent | TweetEvent | ErrorEvent;
+/**
+ * A tweet delivery log entry.
+ *
+ * Field names match the JSON wire format (snake_case) from the server.
+ */
+interface DeliveryLog {
+    id: string;
+    monitor_id: string;
+    monitor_name: string;
+    tweet_id: string;
+    author_username: string;
+    tweet_text_preview: string | null;
+    tweet_url: string;
+    tweet_published_at: string;
+    detected_at: string;
+    /** Detection latency in milliseconds */
+    latency_ms: number;
+    /** "green" | "yellow" | "red" */
+    latency_badge: string;
+    /** "websocket_delivered" | "webhook_delivered" | "webhook_failed" */
+    delivery_status: string;
+    webhook_status_code: number | null;
+    webhook_attempts: number;
+}
+/**
+ * Paginated tweet delivery logs.
+ */
+interface DeliveryLogList {
+    logs: DeliveryLog[];
+    total: number;
+    page: number;
+    page_size: number;
+}
+/**
+ * A billing activity log entry.
+ */
+interface BillingLog {
+    id: string;
+    monitor_id: string;
+    monitor_name: string;
+    billed_at: string;
+    num_accounts: number;
+    credits_deducted: number;
+    tier_label: string;
+    rate_applied: number;
+}
+/**
+ * Paginated billing activity logs.
+ */
+interface BillingLogList {
+    logs: BillingLog[];
+    total: number;
+    page: number;
+    page_size: number;
+}
+/**
+ * Lifecycle status of a filter rule.
+ */
+type FilterRuleStatus = "active" | "paused" | "error" | "inactive";
+/**
+ * A filter rule that watches Twitter for tweets matching a search query.
+ */
+interface FilterRuleResponse {
+    /** UUID of the filter rule */
+    id: string;
+    /** Short human-readable tag for the rule */
+    tag: string;
+    /** Twitter search query string */
+    query: string;
+    /** How often the rule polls in seconds */
+    interval_seconds: number;
+    /** Current lifecycle state */
+    status: FilterRuleStatus;
+    /** Human-readable reason for non-active status */
+    status_reason: string | null;
+    /** HTTPS delivery URL, or null */
+    webhook_url: string | null;
+    /** Whether a signing secret is configured */
+    webhook_secret_set: boolean;
+    /** Maximum tweet results fetched per poll */
+    max_results_per_poll: number;
+    /** Credits burned per rule per day */
+    credits_per_rule_per_day: number;
+    /** Tier label (e.g. Ultra, High, Standard) */
+    pricing_tier: string;
+    /** ISO timestamp of creation */
+    created_at: string;
+    /** ISO timestamp of last modification */
+    updated_at: string;
+}
+/**
+ * Request body for creating a filter rule.
+ */
+interface FilterRuleCreate {
+    /** Short tag identifying this rule */
+    tag: string;
+    /** Twitter search query string */
+    query: string;
+    /** Polling interval in seconds */
+    interval_seconds: number;
+    /** Optional HTTPS webhook URL */
+    webhook_url?: string | null;
+    /** Optional webhook signing secret */
+    webhook_secret?: string | null;
+    /** Maximum results per poll (server default applies if omitted) */
+    max_results_per_poll?: number;
+}
+/**
+ * Request body for updating a filter rule (all fields optional).
+ */
+interface FilterRuleUpdate {
+    /** New tag */
+    tag?: string;
+    /** New search query */
+    query?: string;
+    /** New polling interval in seconds */
+    interval_seconds?: number;
+    /** New lifecycle status */
+    status?: "active" | "paused" | "inactive";
+    /** New webhook URL (null clears it) */
+    webhook_url?: string | null;
+    /** New webhook signing secret */
+    webhook_secret?: string | null;
+    /** New max results per poll */
+    max_results_per_poll?: number;
+}
+/**
+ * A pricing tier for filter rules.
+ */
+interface FilterRulePricingTier {
+    /** UUID of the pricing tier */
+    id: string;
+    /** Human-readable tier label */
+    tier_label: string;
+    /** Maximum polling interval in seconds for this tier */
+    max_interval_seconds: number;
+    /** Credits deducted per rule per day at this tier */
+    credits_per_rule_per_day: number;
+    /** Ordering value for display */
+    display_order: number;
+}
+/**
+ * Paginated list of filter rules.
+ */
+interface FilterRuleListResponse {
+    /** The rules on this page */
+    rules: FilterRuleResponse[];
+    /** Total count across all pages */
+    total: number;
+    /** Requested limit */
+    limit: number;
+    /** Requested offset */
+    offset: number;
+}
+/**
+ * Response from the filter rule query validation endpoint.
+ */
+interface FilterRuleValidateResponse {
+    /** Whether the query is valid */
+    valid: boolean;
+    /** Human-readable error if query is invalid */
+    error?: string;
+    /** Number of sample results found */
+    sample_results: number;
+}
+/**
+ * A single tweet delivery log entry for a filter rule.
+ *
+ * Field names match the JSON wire format (snake_case) from the server.
+ */
+interface FilterRuleDeliveryLog {
+    id: string;
+    rule_id: string;
+    tweet_id: string;
+    author_username: string;
+    tweet_text: string | null;
+    tweet_published_at: string;
+    detected_at: string;
+    /** Detection latency in milliseconds */
+    latency_ms: number;
+    delivery_status: string;
+    webhook_status_code: number | null;
+    webhook_attempts: number;
+    tweet_type: string | null;
+}
+/**
+ * Paginated filter rule delivery logs.
+ */
+interface FilterRuleDeliveryLogListResponse {
+    logs: FilterRuleDeliveryLog[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * Response from the filter rule pricing tiers endpoint.
+ */
+interface FilterRulePricingTiersResponse {
+    tiers: FilterRulePricingTier[];
+}
+/**
+ * Options for StreamClient.connect() and StreamClient.connectIter().
+ */
+interface ConnectOptions {
+    /**
+     * Automatically reconnect on unexpected disconnect.
+     * Default: false.
+     */
+    reconnect?: boolean;
+    /**
+     * Minimum seconds between reconnect attempts.
+     * Enforced floor of 5 seconds. Default: 90.
+     */
+    reconnectDelaySeconds?: number;
+    /**
+     * Maximum reconnect attempts. undefined means unlimited.
+     */
+    maxReconnects?: number;
+}
+
+/**
+ * StreamClient -- stream monitor management and live WebSocket streaming.
+ */
+
+/**
+ * Typed EventEmitter for stream events.
+ *
+ * @example
+ * ```typescript
+ * const stream = client.twitter.stream.connect();
+ * stream.on("tweet", (event) => console.log(event.authorUsername));
+ * stream.on("error", (err) => console.error(err));
+ * ```
+ */
+interface StreamEmitter extends EventEmitter {
+    on(event: "connected", listener: (event: ConnectedEvent) => void): this;
+    on(event: "ping", listener: (event: PingEvent) => void): this;
+    on(event: "tweet", listener: (event: TweetEvent) => void): this;
+    on(event: "error", listener: (error: WebSocketStreamError) => void): this;
+    on(event: "close", listener: () => void): this;
+    once(event: "connected", listener: (event: ConnectedEvent) => void): this;
+    once(event: "tweet", listener: (event: TweetEvent) => void): this;
+    once(event: "close", listener: () => void): this;
+    /** Gracefully close the WebSocket connection. */
+    close(): void;
+}
+/**
+ * Client for Twitter Streams -- monitor CRUD and live WebSocket streaming.
+ *
+ * Accessed as `client.twitter.stream`.
+ *
+ * @example Monitor CRUD
+ * ```typescript
+ * const monitor = await client.twitter.stream.createMonitor({
+ *   name: "Tech Leaders",
+ *   usernames: ["elonmusk", "naval"],
+ *   pollIntervalSeconds: 10,
+ * });
+ * console.log(`Created: ${monitor.id}, tier: ${monitor.pricing_tier}`);
+ * ```
+ *
+ * @example EventEmitter streaming
+ * ```typescript
+ * const stream = client.twitter.stream.connect();
+ * 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));
+ * // Later:
+ * stream.close();
+ * ```
+ *
+ * @example AsyncIterator streaming
+ * ```typescript
+ * for await (const event of client.twitter.stream.connectIter()) {
+ *   if (event.type === "tweet") {
+ *     console.log(event.authorUsername, event.latencyMs);
+ *   }
+ * }
+ * ```
+ */
+declare class StreamClient {
+    private readonly client;
+    constructor(client: BaseClient);
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    createMonitor(params: CreateMonitorParams): Promise<StreamMonitor>;
+    /**
+     * 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`);
+     * ```
+     */
+    listMonitors(options?: {
+        status?: "active" | "paused" | "error";
+        page?: number;
+        pageSize?: number;
+    }): Promise<StreamMonitorList>;
+    /**
+     * 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}`);
+     * ```
+     */
+    getMonitor(monitorId: string): Promise<StreamMonitor>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    updateMonitor(monitorId: string, params: UpdateMonitorParams): Promise<StreamMonitor>;
+    /**
+     * Pause an active stream monitor.
+     *
+     * Convenience wrapper around updateMonitor({ status: "paused" }).
+     *
+     * @param monitorId - UUID of the monitor.
+     * @returns The updated StreamMonitor with status="paused".
+     */
+    pauseMonitor(monitorId: string): Promise<StreamMonitor>;
+    /**
+     * 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.
+     */
+    resumeMonitor(monitorId: string): Promise<StreamMonitor>;
+    /**
+     * 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-...");
+     * ```
+     */
+    deleteMonitor(monitorId: string): Promise<void>;
+    /**
+     * List tweet delivery logs.
+     *
+     * @param options - Filter and pagination options.
+     * @returns DeliveryLogList with pagination metadata.
+     */
+    listDeliveryLogs(options?: {
+        monitorId?: string;
+        authorUsername?: string;
+        deliveryStatus?: string;
+        page?: number;
+        pageSize?: number;
+        sort?: "asc" | "desc";
+    }): Promise<DeliveryLogList>;
+    /**
+     * List billing activity logs.
+     *
+     * @param options - Filter and pagination options.
+     * @returns BillingLogList with pagination metadata.
+     */
+    listBillingLogs(options?: {
+        monitorId?: string;
+        page?: number;
+        pageSize?: number;
+    }): Promise<BillingLogList>;
+    /**
+     * 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}`);
+     * ```
+     */
+    createFilterRule(params: FilterRuleCreate): Promise<FilterRuleResponse>;
+    /**
+     * 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`);
+     * ```
+     */
+    listFilterRules(options?: {
+        status?: FilterRuleResponse["status"];
+        limit?: number;
+        offset?: number;
+    }): Promise<FilterRuleListResponse>;
+    /**
+     * 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}`);
+     * ```
+     */
+    getFilterRule(ruleId: string): Promise<FilterRuleResponse>;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    updateFilterRule(ruleId: string, params: FilterRuleUpdate): Promise<FilterRuleResponse>;
+    /**
+     * 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-...");
+     * ```
+     */
+    deleteFilterRule(ruleId: string): Promise<void>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    validateFilterRuleQuery(query: string): Promise<FilterRuleValidateResponse>;
+    /**
+     * 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" }
+     * );
+     * ```
+     */
+    listFilterRuleLogs(ruleId: string, options?: {
+        limit?: number;
+        offset?: number;
+        deliveryStatus?: string;
+        sort?: "asc" | "desc";
+    }): Promise<FilterRuleDeliveryLogListResponse>;
+    /**
+     * 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));
+     * ```
+     */
+    getFilterRulePricingTiers(): Promise<FilterRulePricingTiersResponse>;
+    /**
+     * 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?: ConnectOptions): StreamEmitter;
+    /**
+     * 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);
+     *   }
+     * }
+     * ```
+     */
+    connectIter(options?: ConnectOptions): AsyncIterableIterator<StreamEvent>;
+}
+/**
+ * Verify the HMAC-SHA256 signature of an incoming webhook request.
+ *
+ * The server sets the header:
+ *   X-ScrapeBadger-Signature: sha256=<hex-digest>
+ *
+ * @param secret - The webhook secret configured on the monitor.
+ * @param body - The raw request body string or Buffer.
+ * @param signatureHeader - The full X-ScrapeBadger-Signature header value.
+ * @returns true if the signature is valid.
+ *
+ * @example
+ * ```typescript
+ * // In an Express webhook receiver:
+ * import { verifyWebhookSignature } from "scrapebadger/twitter";
+ * import express from "express";
+ *
+ * app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
+ *   const sig = req.headers["x-scrapebadger-signature"] as string;
+ *   if (!verifyWebhookSignature("my-secret", req.body, sig)) {
+ *     return res.status(401).json({ error: "Invalid signature" });
+ *   }
+ *   const event = JSON.parse(req.body.toString());
+ *   // process event...
+ *   res.sendStatus(200);
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(secret: string, body: string | Buffer, signatureHeader: string): boolean;
+
 /**
  * Twitter API client.
  *
@@ -1757,6 +2723,7 @@ declare class GeoClient {
  * - `communities` - Community operations (details, members, tweets, search, etc.)
  * - `trends` - Trending topics and locations
  * - `geo` - Geographic place information
+ * - `stream` - Real-time stream monitor management and WebSocket streaming
  *
  * @example
  * ```typescript
@@ -1775,6 +2742,10 @@ declare class GeoClient {
  * for await (const tweet of client.twitter.tweets.searchAll("python")) {
  *   console.log(tweet.text);
  * }
+ *
+ * // Stream live tweets
+ * const stream = client.twitter.stream.connect();
+ * stream.on("tweet", (event) => console.log(event.authorUsername));
  * ```
  */
 declare class TwitterClient {
@@ -1790,6 +2761,8 @@ declare class TwitterClient {
     readonly trends: TrendsClient;
     /** Client for geo/places operations */
     readonly geo: GeoClient;
+    /** Client for real-time stream monitor management and WebSocket streaming */
+    readonly stream: StreamClient;
     /**
      * Create a new Twitter client.
      *
@@ -1798,4 +2771,4 @@ declare class TwitterClient {
     constructor(client: BaseClient);
 }
 
-export { type ApiResponse as A, BaseClient as B, CommunitiesClient as C, GeoClient as G, type Hashtag as H, type IteratorOptions as I, ListsClient as L, type Media as M, type PaginatedResponse as P, type QueryType as Q, type ResolvedConfig as R, type ScrapeBadgerConfig as S, TwitterClient as T, UsersClient as U, type PaginationOptions as a, TweetsClient as b, collectAll as c, TrendsClient as d, type GeoSearchOptions as e, type TrendCategory as f, type CommunityTweetType as g, type PollOption as h, type Poll as i, type Url as j, type UserMention as k, type TweetPlace as l, type Tweet as m, type User as n, type UserAbout as o, type UserIds as p, type List as q, type CommunityBanner as r, type CommunityRule as s, type Community as t, type CommunityMember as u, type Trend as v, type Location as w, type PlaceTrends as x, type Place as y, type ListResponse as z };
+export { type ListResponse as $, AuthenticationError as A, BaseClient as B, ConflictError as C, type List as D, type CommunityBanner as E, type CommunityRule as F, GeoClient as G, type Hashtag as H, InsufficientCreditsError as I, type Community as J, type CommunityMember as K, ListsClient as L, type Media as M, NotFoundError as N, type Trend as O, type PaginatedResponse as P, type QueryType as Q, type ResolvedConfig as R, type ScrapeBadgerConfig as S, TwitterClient as T, UsersClient as U, ValidationError as V, WebSocketStreamError as W, type Location as X, type PlaceTrends as Y, type Place as Z, type ApiResponse as _, ScrapeBadgerError as a, type MonitorStatus as a0, type StreamMonitor as a1, type StreamMonitorList as a2, type CreateMonitorParams as a3, type UpdateMonitorParams as a4, type StreamTweet as a5, type ConnectedEvent as a6, type PingEvent as a7, type TweetEvent as a8, type ErrorEvent as a9, type StreamEvent as aa, type StreamEventType as ab, type DeliveryLog as ac, type DeliveryLogList as ad, type BillingLog as ae, type BillingLogList as af, type ConnectOptions as ag, type FilterRuleStatus as ah, type FilterRuleResponse as ai, type FilterRuleCreate as aj, type FilterRuleUpdate as ak, type FilterRulePricingTier as al, type FilterRuleListResponse as am, type FilterRuleValidateResponse as an, type FilterRuleDeliveryLog as ao, type FilterRuleDeliveryLogListResponse as ap, type FilterRulePricingTiersResponse as aq, RateLimitError as b, ServerError as c, TimeoutError as d, AccountRestrictedError as e, type PaginationOptions as f, type IteratorOptions as g, collectAll as h, TweetsClient as i, CommunitiesClient as j, TrendsClient as k, type GeoSearchOptions as l, StreamClient as m, type StreamEmitter as n, type TrendCategory as o, type CommunityTweetType as p, type PollOption as q, type Poll as r, type Url as s, type UserMention as t, type TweetPlace as u, verifyWebhookSignature as v, type Tweet as w, type User as x, type UserAbout as y, type UserIds as z };