x-developer 2.5.6 → 2.6.2

package/skills/x-twitter-scraper/references/extractions.md

@@ -2,6 +2,23 @@
 
 23 bulk data extraction tools. Each requires a specific target parameter.
 
+## Privacy and Acceptable Use
+
+Bulk extraction and export can collect large amounts of public identity,
+activity, and relationship data. Before creating a job, confirm the lawful
+purpose, target, `resultsLimit`, intended recipients, and retention period.
+Follow X rules and applicable privacy law. Do not use these tools for
+credential collection, private data, surveillance, discrimination, harassment,
+doxxing, or unrelated secondary use. Delete exported data when the approved
+purpose ends.
+
+Every extraction requires an estimate and explicit approval for the exact
+bounded job. Never infer approval from a general request or increase a bound
+without renewed approval.
+
+The API accepts an omitted `resultsLimit`. This Skill must always send an
+explicit finite positive bound. Use the same bound for estimate and create.
+
 **Endpoint:** `POST /extractions`
 
 **Always estimate first:** `POST /extractions/estimate` with the same body to preview `creditsRequired`, `creditsAvailable`, and whether the job is allowed.
@@ -55,7 +72,7 @@
 
 The `@` prefix is automatically stripped if included.
 
-### User-Based by ID (require `targetUserId`)
+### User Timeline Tools (require `targetUsername`)
 
 | Tool Type | Description |
 |-----------|-------------|
@@ -66,7 +83,7 @@ The `@` prefix is automatically stripped if included.
 ```json
 {
   "toolType": "user_likes",
-  "targetUserId": "44196397"
+  "targetUsername": "elonmusk"
 }
 ```
 
@@ -122,7 +139,7 @@ The `@` prefix is automatically stripped if included.
 | Tool Type | Description |
 |-----------|-------------|
 | `people_search` | Search for users by keyword |
-| `tweet_search_extractor` | Search and extract tweets by keyword or hashtag (bulk, up to 1,000) |
+| `tweet_search_extractor` | Search and extract tweets by keyword or hashtag |
 
 **Example (people search):**
 ```json
@@ -143,7 +160,8 @@ The `@` prefix is automatically stripped if included.
 
 ### Tweet Search Filters
 
-The `tweet_search_extractor` tool type supports 16 additional filter fields that are converted to X search operators and combined with `searchQuery`:
+`tweet_search_extractor` accepts structured filters. It combines them with
+`searchQuery` before collection.
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -153,15 +171,49 @@ The `tweet_search_extractor` tool type supports 16 additional filter fields that
 | `language` | string | Language code (e.g., `en`) |
 | `sinceDate` | string | Start date (YYYY-MM-DD) |
 | `untilDate` | string | End date (YYYY-MM-DD) |
-| `mediaType` | string | `images`, `videos`, `gifs`, or `media` |
+| `mediaType` | string | `images`, `videos`, `gifs`, `media`, `links`, or `none` |
 | `minFaves` | number | Minimum likes |
 | `minRetweets` | number | Minimum retweets |
 | `minReplies` | number | Minimum replies |
+| `minQuotes` | number | Minimum quote count |
+| `minViews` | number | Minimum view count |
+| `minBookmarks` | number | Minimum bookmark count |
+| `maxLikes` | number | Maximum likes |
+| `maxRetweets` | number | Maximum reposts |
+| `maxReplies` | number | Maximum replies |
+| `maxQuotes` | number | Maximum quotes |
+| `blueVerifiedOnly` | boolean | Blue-verified authors only |
+| `cardName` | string | Match the Tweet card name |
+| `source` | string | Match the source application |
+| `excludeSource` | string | Exclude a source application |
+| `geocode` | string | Match latitude, longitude, and radius |
+| `sinceId` | string | Tweets newer than this ID |
+| `maxId` | string | Tweets older than this ID |
+| `near` | string | Match a place name |
+| `within` | string | Radius for the `near` filter |
+| `withinTime` | string | Recent time window |
+| `nativeRetweets` | boolean | Native reposts only |
+| `safe` | boolean | Enable safe search |
+| `news` | boolean | News results only |
 | `verifiedOnly` | boolean | Verified authors only |
 | `replies` | string | `include`, `exclude`, or `only` |
 | `retweets` | string | `include`, `exclude`, or `only` |
+| `quotes` | string | `include`, `exclude`, or `only` |
 | `exactPhrase` | string | Exact match text |
 | `excludeWords` | string | Comma-separated words to exclude |
+| `anyWords` | string | Terms where any one can match |
+| `hashtags` | string | Hashtags separated by spaces, commas, or lines |
+| `cashtags` | string | Cashtags separated by spaces, commas, or lines |
+| `url` | string | URL substring or domain |
+| `conversationId` | string | Conversation ID |
+| `inReplyToTweetId` | string | Replies to one Tweet ID |
+| `quotesOfTweetId` | string | Quotes of one Tweet ID |
+| `retweetsOfTweetId` | string | Reposts of one Tweet ID |
+| `listId` | string | Search within a list |
+| `place` | string | Search within a place ID |
+| `placeCountry` | string | Search within a country code |
+| `pointRadius` | string | Geographic point and radius |
+| `boundingBox` | string | Geographic bounding box |
 | `advancedQuery` | string | Raw X search operators appended to query |
 
 **Example with filters:**
@@ -179,6 +231,13 @@ The `tweet_search_extractor` tool type supports 16 additional filter fields that
 
 `resultsLimit` (optional): Maximum results to extract. Stops early instead of fetching all. Pass this on both `POST /extractions/estimate` and `POST /extractions` when you only need a specific count.
 
+### Profile Filters
+
+Profile-producing extractions also accept `minFollowers`, `maxFollowers`,
+`minFollowing`, `maxFollowing`, `minPosts`, `maxPosts`,
+`minAccountAgeDays`, `verifiedType`, `hasWebsite`, `hasLocation`,
+`bioContains`, `locationContains`, and `usernameContains`.
+
 ## Response
 
 ```json
@@ -214,6 +273,14 @@ Formats: `csv`, `json`, `md`, `md-document`, `pdf`, `txt`, `xlsx`. 100,000 row l
 
 Exports include enrichment columns not present in the API response.
 
+The endpoint supports follower, following, post, engagement, profile, media,
+language, search, and date filters. It does not project individual fields.
+
+**Approval required:** Set the smallest approved `resultsLimit` when creating
+the job. Before export, show the job, filters, format, row count, schema,
+recipients, storage, and retention. Materialize or transmit the dataset only
+after explicit approval. Delete it when the approved purpose ends.
+
 ## Estimating Usage
 
 ```
@@ -232,6 +299,7 @@ Same body as create. Response:
 }
 ```
 
-If `allowed` is `false`, the extraction requires more credits than are currently available.
+If `allowed` is `false`, do not create the extraction. It requires more credits
+than are currently available.
 
 For common mistakes and tool selection rules, see [mcp-tools.md](mcp-tools.md#common-mistakes).

package/skills/x-twitter-scraper/references/mcp-setup.md

@@ -10,7 +10,15 @@ API keys.
 | Protocol | Streamable HTTP |
 | Endpoint | `https://xquik.com/mcp` |
 | Authentication | OAuth 2.1 discovery; API key fallback |
-| Version | `2.5.6` |
+| Hosted MCP version | `2.6.0` |
+| Skill bundle version | `2.6.2` |
+
+Current clients negotiate MCP `2026-07-28` through `server/discover`.
+Use a current MCP SDK. It adds request `_meta` and protocol headers.
+Modern calls need no `initialize` request or session ID.
+Discovery and tool catalogs include private 5-minute cache hints.
+Reuse cached metadata only with the same authorization context.
+Stateless 2025-era clients remain compatible at the same endpoint.
 
 Xquik publishes these discovery documents:
 
@@ -275,12 +283,13 @@ this fallback. Codex uses the `bearer_token_env_var` configuration above.
 Client schemas and environment syntax differ, so do not copy a generic header
 object between clients or place a literal key in a configuration file.
 
-Full account keys expose 119 catalog routes. Of these, 118 support JSON or text.
+Full account keys expose 120 catalog routes. Of these, 119 support JSON or text.
 Active guest `paid_reads` keys expose 33 eligible GET routes.
 
 ## MCP Server Architecture
 
-The MCP server (v2.5.6) exposes 119 catalog routes through 2 structured API tools. Of these, 118 support JSON or text. Binary support downloads use REST.
+Hosted MCP v2.6.0 exposes 120 catalog routes through 2 structured API tools.
+Of these, 119 support JSON or text. Binary support downloads use REST.
 
 | Tool | Description | Usage |
 |------|-------------|------|
@@ -291,8 +300,8 @@ The MCP server (v2.5.6) exposes 119 catalog routes through 2 structured API tool
 operations with normalized snake_case responses. Authentication is injected, so
 tool code must never include credentials.
 
-MCP v2.5.6 catalogs 119 of 127 documented REST operations. These 8 credential
-or session operations remain direct REST or dashboard workflows:
+Hosted MCP v2.6.0 catalogs 120 of 128 documented REST operations. These 8 credential,
+checkout, or guest-wallet operations remain direct REST or dashboard workflows:
 
 - API key creation, listing, and revocation
 - Saved-payment top-up

package/skills/x-twitter-scraper/references/mcp-tools.md

@@ -2,6 +2,10 @@
 
 The MCP server at `https://xquik.com/mcp` provides 2 structured API tools. The agent sends API requests through the server, which handles authentication and execution for `xquik.com/api/v1`.
 
+Hosted MCP v2.6.0 supports `2026-07-28` through `server/discover`.
+Current MCP SDKs add request metadata and headers automatically.
+Modern calls need no initialization session.
+
 ## Contents
 
 - [Tools](#tools)
@@ -31,6 +35,7 @@ interface EndpointInfo {
   category: string; // account, composition, credits, extraction, media, monitoring, support, twitter, x-accounts, x-write
   free: boolean; // Included usage flag from endpoint metadata
   parameters?: Array<{ name: string; in: 'query' | 'path' | 'body'; required: boolean; type: string; description: string }>;
+  injectedHeaders?: string[];
   responseShape?: string;
 }
 
@@ -52,7 +57,7 @@ async () => spec.endpoints.filter(e => e.summary.toLowerCase().includes('tweet')
 
 ### `xquik` - Send API Requests
 
-The tool provides `xquik.request()` with auth injected automatically. Never pass API keys.
+The tool provides `xquik.request()` with authentication and required idempotency headers injected automatically. Never pass API keys or headers. The sandbox reuses each generated key for bounded transient retries. After an unresolved write failure, verify state. Start a new attempt only when `safe_to_retry` is true and the user approves.
 
 ## Safety Gates
 
@@ -124,7 +129,7 @@ Use `explore` first to find endpoints, then `xquik` to call them.
 | Get bookmark folders | `GET /api/v1/x/bookmarks/folders` |
 | Get notifications | `GET /api/v1/x/notifications` (private; confirmation required) |
 | Get home timeline | `GET /api/v1/x/timeline` (private; confirmation required) |
-| Get DM history | `GET /api/v1/x/dm/{userId}/history` (private; confirmation required) |
+| Get DM history | `GET /api/v1/x/dm/{userId}/history?account={username}` (private; exact-account approval required; block ambiguous selection) |
 | Check credit balance | `GET /api/v1/credits` |
 
 Use `POST /api/v1/extractions` ONLY for bulk data that simpler endpoints cannot provide (all followers, all replies to a tweet, community members, etc.). Always call `POST /api/v1/extractions/estimate` first.
@@ -138,9 +143,10 @@ Use `POST /api/v1/extractions` ONLY for bulk data that simpler endpoints cannot
 | **Bulk extraction** | `POST /extractions/estimate` -> `POST /extractions` -> `GET /extractions/{id}` |
 | **Compose optimized tweet** | `POST /compose` (step=compose -> refine -> score) |
 | **Analyze tweet style** | `POST /styles` -> `GET /styles/{id}` -> `POST /compose` with `styleUsername` |
-| **Post a tweet** | `GET /x/accounts` -> `POST /x/tweets` with `account` + `text` |
+| **Post a tweet** | `GET /x/accounts` -> confirm -> `POST /x/tweets` with `account` and `text` -> hosted MCP injects a unique `Idempotency-Key` -> poll `statusUrl` |
 | **Get trending news** | `GET /radar` (supported sources, via `xquik` tool) -> `POST /compose` with trending topic |
 | **Open support ticket** | `POST /support/tickets` -> `GET /support/tickets/{id}` |
+| **Collect maximum-coverage replies** | `GET /x/tweets/{id}/replies?mode=complete&limit=<1-25000>` -> filter direct rows by `inReplyToId` -> keep `nested_replies` separate -> inspect `diagnostic` |
 
 ## Common Mistakes
 
@@ -154,10 +160,14 @@ Use `POST /api/v1/extractions` ONLY for bulk data that simpler endpoints cannot
 | Passing API keys in code | Auth is injected automatically. Never include keys |
 | Using `explore` for API calls | `explore` is read-only spec search. Use `xquik` for actual API calls |
 | Looking up follow/DM by username | Follow and DM endpoints need numeric user ID. Look up via `GET /x/users/{id}` first; that route accepts usernames and IDs |
+| Treating nested replies as direct replies | Match `inReplyToId` to the root ID. Keep `nested_replies` separate |
+| Treating 424 as an empty failure | Keep safe partial rows. Follow `diagnostic.recommendedFallback` and disclose coverage |
 
 ## REST-only operations
 
-MCP v2.5.6 catalogs 119 of 127 REST operations. Of these, 118 support JSON or text. Binary support downloads use REST. These 8 credential or session operations remain outside MCP:
+Hosted MCP v2.6.0 catalogs 120 of 128 REST operations.
+Of these, 119 support JSON or text. Binary support downloads use REST.
+These 8 credential, checkout, or guest-wallet operations remain outside MCP:
 
 - API key creation
 - API key listing

package/skills/x-twitter-scraper/references/monitor-twitter-webhooks.md

@@ -0,0 +1,122 @@
+# Twitter Account Monitor API: HMAC Webhook Alerts
+
+Xquik account monitors can detect new tweets, replies, quotes, and reposts.
+Keyword monitors detect new matches for a persistent query. Poll events or push
+them to an HTTPS endpoint through HMAC-signed webhooks.
+
+> Xquik is an independent third-party service. Not affiliated with X Corp.
+> "Twitter" and "X" are trademarks of X Corp.
+
+## Twitter Monitor Event and Delivery Data
+
+| Object | Fields to Preserve |
+| --- | --- |
+| Account monitor | Monitor ID, username, event types, active state |
+| Keyword monitor | Monitor ID, query, event types, active state |
+| Event | Event ID, monitor ID and type, event type, occurrence time, data |
+| Delivery | Delivery ID, stream event ID, attempts, status, delivery time |
+
+## Twitter Monitor Polling Versus Webhook Delivery
+
+| Requirement | Poll Events | Webhook Delivery |
+| --- | --- | --- |
+| Simple scheduled batch | Strong fit | Optional |
+| Low detection delay | More frequent polling needed | Strong fit |
+| Recover after downtime | Resume with the stored cursor | Inspect delivery status, then repoll events |
+| Public HTTPS endpoint | Not required | Required |
+| Signature verification | Not applicable | Required |
+| Backpressure control | Caller controls fetch rate | Receiver must queue work |
+
+Both models need idempotency. Persist the event before downstream processing.
+Mark completion only after every required side effect succeeds.
+
+### What is the best way to monitor a Twitter account programmatically?
+
+Validate the public account and required event types first. Use a bounded
+timeline read for an initial snapshot. Create a persistent account monitor only
+after reviewing target, filters, ongoing usage, delivery, and deletion.
+
+Poll events when the application controls scheduling. Use webhooks when low
+detection delay matters. Measure delay, duplicate deliveries, missed known
+events, retry behavior, and outage recovery.
+
+### How do I monitor Twitter mentions?
+
+Use a mention search or `mention_extractor` for a bounded historical dataset.
+Use a keyword or account monitor for new mention events. Keep explicit account
+mentions separate from broad brand keyword matches.
+
+Add exact phrases, exclusions, language, author, and engagement rules to improve
+precision. Review a sample and version every query change.
+
+### What are Twitter webhook alerts?
+
+Webhook alerts are HTTPS POST requests sent when a monitor creates a matching
+event. Xquik signs each delivery with a per-webhook HMAC secret. The secret is
+shown only once and should enter a secret store immediately.
+
+Verify `<timestamp>.<nonce>.<raw body>` with `X-Xquik-Timestamp`,
+`X-Xquik-Nonce`, and `X-Xquik-Signature`. Reject timestamps outside 5 minutes
+and reused nonces. Reject invalid signatures before parsing business data.
+
+### What is a Twitter account monitor API?
+
+An account monitor API creates, lists, updates, and stops persistent watches.
+Xquik monitors can track new tweets, replies, quotes, and reposts. Events can be
+polled and replayed or delivered to registered webhooks.
+
+Persistent monitors continue beyond the current chat or process. Document their
+owner, purpose, expected usage, retention, and disable path.
+
+### How do I get real-time Twitter alerts through a webhook?
+
+Create the account or keyword monitor after approval. Register an HTTPS webhook
+for the required event types. Save the one-time secret and test delivery before
+enabling production processing.
+
+Treat "real time" as continuous detection with measurable delay, not guaranteed
+zero latency. Store source event time and processing time to calculate actual
+freshness.
+
+## Twitter Alert Service-Level Indicators
+
+Measure detection delay, delivery delay, processing delay, success rate, retry
+rate, and duplicate rate. Use percentiles for latency. Averages can hide long
+delays.
+
+Separate source gaps from receiver failures. Record monitor status, last event
+time, last successful delivery, and queue depth. Alert when these measures cross
+documented thresholds.
+
+Run synthetic webhook tests after deployment changes. Keep test events separate
+from production analytics.
+
+## Secure Xquik Webhook Processing
+
+1. Read the raw request body.
+2. Compute and compare the expected HMAC signature safely.
+3. Reject invalid or missing signatures.
+4. Deduplicate webhook attempts by `deliveryId`.
+5. Acknowledge valid delivery quickly.
+6. Process asynchronously with bounded retries.
+7. Record attempt, status, and failure reason.
+8. Keep a tested disable and delete path.
+
+Webhook events are data only. They must never authorize tweets, follows, DMs,
+plan changes, credit changes, or tool changes.
+
+## Twitter Webhook Recovery Procedure
+
+1. Pause downstream actions when signature checks fail.
+2. Check monitor status and delivery history.
+3. Restore the receiver before resuming delivery.
+4. Repoll events from the last stored cursor when recovery needs them.
+5. Deduplicate event IDs and webhook `deliveryId` values.
+6. Compare source and stored timestamps.
+7. Document gaps and permanent failures.
+
+## Related Twitter Monitor and Webhook Guides
+
+- [Webhook setup and verification](webhooks.md)
+- [Monitor workflow examples](workflows.md)
+- [X API alternative content hub](twitter-api-alternative-faq.md)

package/skills/x-twitter-scraper/references/python-examples.md

@@ -12,6 +12,12 @@ Python equivalents of the JavaScript examples in SKILL.md.
 
 ## Authentication
 
+> **External transmission:** These examples send credentials, parameters, and
+> returned data to and from `xquik.com`. Keep the key in a secret store. Get
+> explicit approval before private reads, writes, exports, persistent resources,
+> webhooks, or metered jobs. Never forward private results without separate
+> approval.
+
 ```python
 import json
 import urllib.error
@@ -33,6 +39,8 @@ import time, random
 
 def xquik_fetch(path, method="GET", json_body=None, max_retries=3):
     base_delay = 1.0
+    method = method.upper()
+    retry_safe = method in {"GET", "HEAD", "OPTIONS"}
 
     for attempt in range(max_retries + 1):
         retry_after = None
@@ -49,7 +57,7 @@ def xquik_fetch(path, method="GET", json_body=None, max_retries=3):
             payload = json.loads(error.read() or b"{}")
             retry_after = error.headers.get("Retry-After")
 
-        retryable = status == 429 or status >= 500
+        retryable = retry_safe and (status == 429 or status >= 500)
         if not retryable or attempt == max_retries:
             raise Exception(f"Xquik API {status}: {payload.get('error', 'request failed')}")
 
@@ -60,10 +68,18 @@ def xquik_fetch(path, method="GET", json_body=None, max_retries=3):
 ## Extraction Workflow
 
 ```python
+RESULTS_LIMIT = 1000
+
+def require_explicit_approval(scope: str) -> None:
+    raise RuntimeError(
+        f"Approval required for {scope}. Implement the approval gate first."
+    )
+
 # Step 1: Estimate
 estimate = xquik_fetch("/extractions/estimate", method="POST", json_body={
     "toolType": "reply_extractor",
     "targetTweetId": "1893704267862470862",
+    "resultsLimit": RESULTS_LIMIT,
 })
 
 if not estimate["allowed"]:
@@ -71,9 +87,13 @@ if not estimate["allowed"]:
     exit()
 
 # Step 2: Create job
+require_explicit_approval(
+    "the bounded extraction job, usage, recipients, and retention"
+)
 job = xquik_fetch("/extractions", method="POST", json_body={
     "toolType": "reply_extractor",
     "targetTweetId": "1893704267862470862",
+    "resultsLimit": RESULTS_LIMIT,
 })
 
 # Step 3: Poll until complete (large jobs may return "running")
@@ -88,7 +108,7 @@ results = []
 while True:
     path = f"/extractions/{job['id']}"
     if cursor:
-        path += f"?after={cursor}"
+        path += f"?cursor={cursor}"
     page = xquik_fetch(path)
     results.extend(page["results"])
 
@@ -128,6 +148,8 @@ for winner in details["winners"]:
 import hashlib
 import hmac
 import json
+import re
+import time
 from http.server import BaseHTTPRequestHandler, HTTPServer
 
 def load_secret(name: str) -> str:
@@ -136,10 +158,15 @@ def load_secret(name: str) -> str:
 
 # Per-webhook secret from POST /webhooks response, not a Xquik account credential
 WEBHOOK_SECRET = load_secret("XQUIK_WEBHOOK_SECRET")
-processed_hashes = set()  # Use Redis/DB in production
-
-def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
-    expected = "sha256=" + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
+processed_delivery_ids = set()  # Use durable storage in production
+
+def verify_signature(payload: bytes, signature: str, timestamp: str, nonce: str, secret: str) -> bool:
+    if not timestamp.isdigit() or not re.fullmatch(r"[0-9a-f]{32}", nonce):
+        return False
+    if abs(int(time.time() * 1000) - int(timestamp)) > 5 * 60 * 1000:
+        return False
+    signing_input = timestamp.encode() + b"." + nonce.encode() + b"." + payload
+    expected = "sha256=" + hmac.new(secret.encode(), signing_input, hashlib.sha256).hexdigest()
     return hmac.compare_digest(expected, signature)
 
 EVENT_HANDLERS = {
@@ -153,23 +180,23 @@ class WebhookHandler(BaseHTTPRequestHandler):
     def do_POST(self):
         length = int(self.headers.get("Content-Length", "0"))
         signature = self.headers.get("X-Xquik-Signature", "")
+        timestamp = self.headers.get("X-Xquik-Timestamp", "")
+        nonce = self.headers.get("X-Xquik-Nonce", "")
         payload = self.rfile.read(length)
 
-        if not verify_signature(payload, signature, WEBHOOK_SECRET):
+        if not verify_signature(payload, signature, timestamp, nonce, WEBHOOK_SECRET):
             self.send_response(401)
             self.end_headers()
             self.wfile.write(b"Invalid signature")
             return
 
-        payload_hash = hashlib.sha256(payload).hexdigest()
-        if payload_hash in processed_hashes:
+        event = json.loads(payload)
+        if event["deliveryId"] in processed_delivery_ids:
             self.send_response(200)
             self.end_headers()
             self.wfile.write(b"Already processed")
             return
-        processed_hashes.add(payload_hash)
-
-        event = json.loads(payload)
+        processed_delivery_ids.add(event["deliveryId"])
         handler = EVENT_HANDLERS.get(event["eventType"])
         if handler:
             handler(event["username"], event["data"])