x-twitter-scraper 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.5.2 (2026-07-23)
+
+Full Changelog: [v0.5.1...v0.5.2](https://github.com/Xquik-dev/x-twitter-scraper-typescript/compare/v0.5.1...v0.5.2)
+
+### Documentation
+
+* map common X data tasks ([#11](https://github.com/Xquik-dev/x-twitter-scraper-typescript/issues/11)) ([f4fa511](https://github.com/Xquik-dev/x-twitter-scraper-typescript/commit/f4fa5119c650a2ce80681af2a5a8555f1879e897))
+
+## 0.5.1 (2026-07-22)
+
+Full Changelog: [v0.5.0...v0.5.1](https://github.com/Xquik-dev/x-twitter-scraper-typescript/compare/v0.5.0...v0.5.1)
+
+### Chores
+
+* sync generated SDK contracts ([ff8612e](https://github.com/Xquik-dev/x-twitter-scraper-typescript/commit/ff8612e3b474a71aabae2f709ae93a487d5ad69d))
+* verify final public contract ([bcd7c6a](https://github.com/Xquik-dev/x-twitter-scraper-typescript/commit/bcd7c6adecf0e4f1dd42025a3c9615c3abcd4223))
+
 ## 0.5.0 (2026-07-22)
 
 Full Changelog: [v0.4.1...v0.5.0](https://github.com/Xquik-dev/x-twitter-scraper-typescript/compare/v0.4.1...v0.5.0)

package/README.md

@@ -16,6 +16,20 @@ Use it to get tweets from profiles, search tweets by keyword or operator query,
 
 It is generated with [Stainless](https://www.stainless.com/).
 
+## Common X Data Tasks
+
+Use the linked TypeScript API map for typed method names.
+
+| Customer Question | REST Route | Workflow Note |
+| --- | --- | --- |
+| How do I search tweets? | `GET /x/tweets/search` | Use keyword or advanced operator queries. |
+| How do I read a profile timeline? | `GET /x/users/{id}/tweets` | Paginate bounded results. |
+| How do I scrape followers? | `GET /x/users/{id}/followers` | Use an extraction for complete datasets. |
+| How do I scrape following accounts? | `GET /x/users/{id}/following` | Use an extraction for complete datasets. |
+| How do I read my home timeline? | `GET /x/timeline` | Approve this private read. |
+| How do I monitor an account? | `POST /monitors` | Deliver events through HMAC webhooks. |
+| How do I post or reply? | `POST /x/tweets` | Confirm the account and payload. |
+
 ## Tweet Search, Profile Tweets & User Lookup
 
 Build TypeScript services that search tweets, get tweets from profiles, fetch user profiles, check follower relationships, export followers, download media, and inspect timeline data through one typed REST client.
@@ -476,3 +490,5 @@ If you are interested in other runtime environments, please open or upvote an is
 ## Contributing
 
 See [the contributing documentation](./CONTRIBUTING.md).
+
+Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.

package/client.d.mts

@@ -223,7 +223,7 @@ export declare class XTwitterScraper {
      */
     radar: API.Radar;
     /**
-     * Real-time X account monitoring
+     * X account monitoring with 1-second checks
      */
     monitors: API.Monitors;
     /**

package/client.d.ts

@@ -223,7 +223,7 @@ export declare class XTwitterScraper {
      */
     radar: API.Radar;
     /**
-     * Real-time X account monitoring
+     * X account monitoring with 1-second checks
      */
     monitors: API.Monitors;
     /**

package/client.js

@@ -82,7 +82,7 @@ class XTwitterScraper {
          */
         this.radar = new API.Radar(this);
         /**
-         * Real-time X account monitoring
+         * X account monitoring with 1-second checks
          */
         this.monitors = new API.Monitors(this);
         /**

package/client.mjs

@@ -79,7 +79,7 @@ export class XTwitterScraper {
          */
         this.radar = new API.Radar(this);
         /**
-         * Real-time X account monitoring
+         * X account monitoring with 1-second checks
          */
         this.monitors = new API.Monitors(this);
         /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x-twitter-scraper",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "TypeScript SDK for Xquik API workflows. Xquik is an independent third-party service. Not affiliated with X Corp. \"Twitter\" and \"X\" are trademarks of X Corp.",
   "author": "Xquik <support@xquik.com>",
   "types": "./index.d.ts",

package/resources/account.d.mts

@@ -63,11 +63,11 @@ export declare namespace AccountRetrieveResponse {
          */
         activeHourlyBurn: string;
         /**
-         * Estimated daily usage for 1 active instant monitor.
+         * Rounded daily estimate for 1 active monitor.
          */
         creditsPerActiveMonitorDay: string;
         /**
-         * Hourly usage charged for 1 active instant monitor.
+         * Hourly credits charged for 1 active monitor.
          */
         creditsPerActiveMonitorHour: string;
         /**

package/resources/account.d.ts

@@ -63,11 +63,11 @@ export declare namespace AccountRetrieveResponse {
          */
         activeHourlyBurn: string;
         /**
-         * Estimated daily usage for 1 active instant monitor.
+         * Rounded daily estimate for 1 active monitor.
          */
         creditsPerActiveMonitorDay: string;
         /**
-         * Hourly usage charged for 1 active instant monitor.
+         * Hourly credits charged for 1 active monitor.
          */
         creditsPerActiveMonitorHour: string;
         /**

package/resources/compose.d.mts

@@ -6,83 +6,204 @@ import { RequestOptions } from "../internal/request-options.mjs";
  */
 export declare class Compose extends APIResource {
     /**
-     * Compose, refine, or score a tweet
+     * Run one step of Xquik's three-step writing workflow. Compose returns questions
+     * and editorial rules. Refine returns goal-specific guidance. Score applies
+     * deterministic text checks. It does not predict reach or expose X ranking
+     * weights.
      *
      * @example
      * ```ts
      * const compose = await client.compose.create({
      *   step: 'compose',
+     *   topic: 'PostgreSQL query planning',
      *   goal: 'engagement',
-     *   topic: 'AI trends in 2025',
      * });
      * ```
      */
     create(body: ComposeCreateParams, options?: RequestOptions): APIPromise<ComposeCreateResponse>;
 }
-export interface ComposeCreateResponse {
-    /**
-     * AI feedback on the draft
-     */
-    feedback?: string;
-    /**
-     * Engagement score (0-100)
-     */
-    score?: number;
-    /**
-     * Improvement suggestions
-     */
-    suggestions?: Array<string>;
-    /**
-     * Generated or refined tweet text
-     */
-    text?: string;
-    [k: string]: unknown;
+export type ComposeCreateResponse = ComposeCreateResponse.ComposePrepareResult | ComposeCreateResponse.ComposeRefineResult | ComposeCreateResponse.ComposeScoreResult;
+export declare namespace ComposeCreateResponse {
+    interface ComposePrepareResult {
+        /**
+         * Xquik editorial heuristics, ordered for the goal.
+         */
+        contentRules: Array<ComposePrepareResult.ContentRule>;
+        /**
+         * Published engagement signal names. Production multipliers are not published.
+         */
+        engagementMultipliers: Array<ComposePrepareResult.EngagementMultiplier>;
+        /**
+         * Publication limit for timing and decay claims.
+         */
+        engagementVelocity: string;
+        followUpQuestions: Array<string>;
+        /**
+         * X post intent seeded with the topic.
+         */
+        intentUrl: string;
+        nextStep: string;
+        /**
+         * Published signal names with unpublished weights as null.
+         */
+        scorerWeights: Array<ComposePrepareResult.ScorerWeight>;
+        /**
+         * Signal source and evidence limits.
+         */
+        source: string;
+        /**
+         * Negative engagement predictions in the public model.
+         */
+        topPenalties: Array<string>;
+        /**
+         * Style analyses saved to the account.
+         */
+        savedStyles?: Array<ComposePrepareResult.SavedStyle>;
+        /**
+         * Next action when no cached style is available.
+         */
+        styleNote?: string;
+        /**
+         * Cached examples for the requested style username.
+         */
+        styleTweets?: Array<string>;
+    }
+    namespace ComposePrepareResult {
+        interface ContentRule {
+            rule: string;
+        }
+        interface EngagementMultiplier {
+            /**
+             * Human-readable published signal name.
+             */
+            action: string;
+            multiplier: 'Production weight not published by X';
+        }
+        interface ScorerWeight {
+            /**
+             * Signal direction and publication limit.
+             */
+            context: string;
+            /**
+             * Signal name from X's public ranking repository.
+             */
+            signal: string;
+            /**
+             * X does not publish the production weight.
+             */
+            weight: null;
+        }
+        interface SavedStyle {
+            tweetCount: number;
+            username: string;
+        }
+    }
+    interface ComposeRefineResult {
+        /**
+         * Goal, tone, media, and editorial guidance.
+         */
+        compositionGuidance: Array<string>;
+        examplePatterns: Array<ComposeRefineResult.ExamplePattern>;
+        /**
+         * X post intent seeded with the topic.
+         */
+        intentUrl: string;
+        nextStep: string;
+    }
+    namespace ComposeRefineResult {
+        interface ExamplePattern {
+            description: string;
+            pattern: string;
+        }
+    }
+    interface ComposeScoreResult {
+        /**
+         * Deterministic editorial checks. Not a reach prediction.
+         */
+        checklist: Array<ComposeScoreResult.Checklist>;
+        nextStep: string;
+        passed: boolean;
+        passedCount: number;
+        topSuggestion: string;
+        totalChecks: 9;
+        /**
+         * Present only when every check passes.
+         */
+        intentUrl?: string;
+    }
+    namespace ComposeScoreResult {
+        interface Checklist {
+            factor: string;
+            passed: boolean;
+            /**
+             * Present only when the check fails.
+             */
+            suggestion?: string;
+        }
+    }
 }
-export interface ComposeCreateParams {
-    /**
-     * Workflow step
-     */
-    step: 'compose' | 'refine' | 'score';
-    /**
-     * Extra context or URLs (refine)
-     */
-    additionalContext?: string;
-    /**
-     * Desired call to action (refine)
-     */
-    callToAction?: string;
-    /**
-     * Tweet draft text to evaluate (score)
-     */
-    draft?: string;
-    /**
-     * Optimization goal
-     */
-    goal?: 'engagement' | 'followers' | 'authority' | 'conversation';
-    /**
-     * Whether a link is attached (score)
-     */
-    hasLink?: boolean;
-    /**
-     * Whether media is attached (score)
-     */
-    hasMedia?: boolean;
-    /**
-     * Media type (refine)
-     */
-    mediaType?: 'photo' | 'video' | 'none';
-    /**
-     * Cached style username for voice matching (compose)
-     */
-    styleUsername?: string;
-    /**
-     * Desired tone (refine)
-     */
-    tone?: string;
-    /**
-     * Tweet topic (compose, refine)
-     */
-    topic?: string;
+export type ComposeCreateParams = ComposeCreateParams.ComposePrepareRequest | ComposeCreateParams.ComposeRefineRequest | ComposeCreateParams.ComposeScoreRequest;
+export declare namespace ComposeCreateParams {
+    interface ComposePrepareRequest {
+        step: 'compose';
+        /**
+         * Subject for the post.
+         */
+        topic: string;
+        /**
+         * Editorial goal used to order the rules and questions.
+         */
+        goal?: 'engagement' | 'followers' | 'authority' | 'conversation';
+        /**
+         * Username from a style analysis saved to this account.
+         */
+        styleUsername?: string;
+        [k: string]: unknown;
+    }
+    interface ComposeRefineRequest {
+        /**
+         * Editorial goal for the guidance.
+         */
+        goal: 'engagement' | 'followers' | 'authority' | 'conversation';
+        step: 'refine';
+        /**
+         * Requested writing tone.
+         */
+        tone: string;
+        /**
+         * Subject for the post.
+         */
+        topic: string;
+        /**
+         * Audience, constraints, sources, or other writing context.
+         */
+        additionalContext?: string;
+        /**
+         * Specific action the draft should request.
+         */
+        callToAction?: string;
+        /**
+         * Planned media type.
+         */
+        mediaType?: 'photo' | 'video' | 'none';
+        [k: string]: unknown;
+    }
+    interface ComposeScoreRequest {
+        /**
+         * Full post text for deterministic editorial checks.
+         */
+        draft: string;
+        step: 'score';
+        /**
+         * True when a separate link card is attached.
+         */
+        hasLink?: boolean;
+        /**
+         * @deprecated Ignored. Remove this field. Use hasLink for a separate link card.
+         */
+        hasMedia?: boolean;
+        [k: string]: unknown;
+    }
 }
 export declare namespace Compose {
     export { type ComposeCreateResponse as ComposeCreateResponse, type ComposeCreateParams as ComposeCreateParams, };

package/resources/compose.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"compose.d.mts","sourceRoot":"","sources":["../src/resources/compose.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,6BAAyB;AAC/C,OAAO,EAAE,UAAU,EAAE,gCAA4B;AACjD,OAAO,EAAE,cAAc,EAAE,wCAAoC;AAE7D;;GAEG;AACH,qBAAa,OAAQ,SAAQ,WAAW;IACtC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,IAAI,EAAE,mBAAmB,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,qBAAqB,CAAC;CAG/F;AAED,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAE5B;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAErC;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,IAAI,CAAC,EAAE,YAAY,GAAG,WAAW,GAAG,WAAW,GAAG,cAAc,CAAC;IAEjE;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;IAEvC;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,CAAC,OAAO,WAAW,OAAO,CAAC;IAC/B,OAAO,EACL,KAAK,qBAAqB,IAAI,qBAAqB,EACnD,KAAK,mBAAmB,IAAI,mBAAmB,GAChD,CAAC;CACH"}
+{"version":3,"file":"compose.d.mts","sourceRoot":"","sources":["../src/resources/compose.ts"],"names":[],"mappings":"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"}