Loading components
Xquik
Access 190 typed X/Twitter API actions, signed webhook delivery, and live event queries in Convex without an X developer account.
Installation
npm install xquik-convexAbout Xquik
xquik-convex wraps the full Xquik API surface into 190 typed Convex actions covering X (Twitter) data retrieval, giving you argument and return value validation via Convex's schema system without needing an X developer account or bearer token. It adds a signature-verified webhook receiver that deduplicates deliveries and stores events in Convex tables, exposes those events as live paginated queries, and supports durable scheduled jobs with automatic retry logic for safe operations.
Benefits
- Call any of 190 X/Twitter operations as typed Convex actions with argument and return value validation built in
- Receive webhook events with signature verification, replay protection, and exactly-once storage without writing boilerplate
- Query stored events live so your UI updates reactively as new tweets or social signals arrive
- Schedule durable polling jobs with automatic retry on 429s and 5xx errors, no X developer account required
Use cases
how to get tweets from a user in Convex without Twitter API account
xquik-convex provides a Convex action called searchTweets that accepts standard query parameters like `q: 'from:username'` and returns typed results. You call it via `ctx.runAction(components.xquik.operations.searchTweets, { q: 'from:username', limit: 20 })` from an internal action. No X developer account or bearer token is needed.
how to receive Twitter webhook events in Convex
xquik-convex exposes a webhook receiver that Convex hosts at your deployment's HTTP endpoint. You call `xquik.createWebhook(ctx, { eventTypes: ['tweet.new'], onEvent: internal.x.onEvent })` and the component registers the URL with Xquik, stores the signing secret, and validates every delivery's HMAC signature and timestamp. Replayed nonces are rejected with a 401.
how to poll Twitter data on a schedule in Convex
xquik-convex provides a `schedule` helper that registers a durable recurring job. Calling `xquik.schedule(ctx, 'listEvents', { limit: 100 }, { key: 'events', everyMs: 5 * 60 * 1000 })` creates a job that repeats every 5 minutes. The component retries safe calls up to 5 times on 429 or 5xx responses and stores results alongside webhook events so they appear in the same live query.
how to display live Twitter feed in Convex React app
xquik-convex stores both webhook events and scheduled poll results in a shared table. You expose a query that calls `ctx.runQuery(components.xquik.events.list, { paginationOpts })` and use `usePaginatedQuery` on the client. Because the data lives in Convex, the UI re-renders automatically when new events are stored. You can filter by `eventType` or `monitorId` to narrow the feed.
Frequently asked questions
Does xquik-convex require an X developer account or Twitter API credentials?
No. xquik-convex uses the Xquik third-party scraping service, not the official X API. You only need an Xquik API key from xquik.com/dashboard, which you set with `npx convex env set XQUIK_API_KEY xq_your_key`. Every component function returns `missing_api_key` until the key is set, and no X bearer token or developer app is required.
How does xquik-convex handle webhook signature verification?
The xquik-convex component hosts a webhook receiver at `https://<deployment>.convex.site/xquik/webhooks/<token>` and checks the `X-Xquik-Signature` header and timestamp on every delivery. Deliveries older than 5 minutes or with a replayed nonce are rejected with a 401. The signing secret is stored in the component's own table, not in environment variables you manage. A `webhook.test` alert returns 200 and records `testedAt` on the endpoint.
How many X/Twitter operations does xquik-convex support?
xquik-convex exposes 190 typed Convex actions, one for each public operation in the Xquik API reference. Each action validates its arguments and return value using Convex validators derived from the Xquik OpenAPI schema. Operations cover data retrieval (tweets, users, search) and write actions where the Xquik API supports them.
How do I prevent unauthorized use of Xquik credits in xquik-convex?
xquik-convex component functions are only callable from your backend, not directly from the client. The recommended pattern is to wrap every credit-spending operation in an `internalAction` or `internalMutation` so it cannot be called from the browser. For any public Convex function that triggers an Xquik call, you should check the caller's identity with `ctx.auth.getUserIdentity()` and apply rate limiting before proceeding.
How do I test my Convex app that uses xquik-convex?
xquik-convex ships a test helper compatible with the convex-test framework. You import `xquikTest` from `xquik-convex/test`, call `xquikTest.register(t)` on your `convexTest` instance, and then write tests against your functions normally. The component's own test suite verifies that every operation in the OpenAPI spec has a corresponding action and that every event type has a receiver test.
Links
Components
Open-source building blocks for your Convex app
Browse components in this category.