strapi-plugin-xquik 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xquik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# X API & Twitter API Plugin for Strapi 5
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="https://raw.githubusercontent.com/Xquik-dev/strapi-plugin-xquik/main/assets/logo.png" alt="Xquik logo" width="96" height="96">
+
+[Xquik](https://xquik.com) is the world's fastest and cheapest X Twitter data API with the most complete X data.
+Searches & extractions charge only for delivered, unique, filter-matching results.
+
+Xquik is an independent third-party service. Not affiliated with X Corp. "Twitter" and "X" are trademarks of X Corp.
+Xquik makes this plugin. Strapi doesn't make or endorse it.
+
+This plugin adds an `xquik` service to your Strapi 5 server.
+The service searches X posts & reads X profiles.
+It runs on the server only. It adds no admin pages, routes or content types.
+
+## Requirements
+
+- Strapi 5
+- Node.js 20 to 26
+- An Xquik API key from your dashboard at [xquik.com](https://xquik.com)
+
+## Install
+
+```sh
+npm install strapi-plugin-xquik
+```
+
+Strapi 5 enables the plugin on its next start.
+
+## Configure
+
+Add your API key to your app's `.env` file.
+
+```sh
+XQUIK_API_KEY=xq_...
+```
+
+The plugin reads `XQUIK_API_KEY` by default.
+To set the key another way, set `apiKey` in `config/plugins.js`.
+
+```js
+module.exports = ({ env }) => ({
+  xquik: {
+    config: {
+      apiKey: env("XQUIK_API_KEY"),
+    },
+  },
+});
+```
+
+| Option   | Type   | Default                  | Use                                            |
+| -------- | ------ | ------------------------ | ---------------------------------------------- |
+| `apiKey` | string | `XQUIK_API_KEY`, or `""` | The key the plugin sends in `x-api-key`.       |
+
+The plugin reads the key on each call.
+With no key, a call fails before it sends a request.
+
+## Search posts
+
+Call the service from any controller, service or lifecycle hook.
+
+```js
+const page = await strapi
+  .plugin("xquik")
+  .service("xquik")
+  .searchPosts({ q: "from:NASA", limit: 10 });
+```
+
+`searchPosts(query)` takes these fields.
+
+| Field       | Type   | Use                                                                |
+| ----------- | ------ | ------------------------------------------------------------------ |
+| `q`         | string | Required. A search query, a post ID or a post URL.                 |
+| `limit`     | number | Most posts to return, from 1 to 10,000. The API default is 20.     |
+| `cursor`    | string | The `next_cursor` of the previous page.                            |
+| `queryType` | string | `Latest` lists the newest posts first. `Top` lists high-engagement posts first.|
+
+It also passes every other search filter in the [search API reference](https://docs.xquik.com/api-reference/x/search-tweets).
+Examples are `language`, `minLikes`, `sinceDate` & `untilDate`.
+`q` takes [X search operators](https://github.com/Xquik-dev/x-twitter-advanced-search), such as `from:` & `since:`.
+
+It returns `{ tweets, has_next_page, next_cursor }`.
+Each post has an `id`. It also has fields such as `text`, `createdAt`, `likeCount`, `viewCount` & `author`.
+
+To read the next page, pass `next_cursor` as `cursor` with the same filters.
+Stop when `has_next_page` is `false`.
+
+## Read a profile
+
+```js
+const profile = await strapi.plugin("xquik").service("xquik").getUser("NASA");
+```
+
+`getUser(id)` takes a user ID, a username with or without `@`, or a profile URL such as `x.com/nasa`.
+It returns the profile with `id`, `username` & `name`.
+It also has fields such as `description`, `followers`, `following` & `verified`.
+The [profile API reference](https://docs.xquik.com/api-reference/x/get-user) lists every field.
+
+## Handle errors
+
+Each failure throws an `XquikError`.
+Its `code` names the failure. Its `status` holds the HTTP status when the API answered.
+
+| `code`                 | `status`    | Next step                                                   |
+| ---------------------- | ----------- | ----------------------------------------------------------- |
+| `missing_api_key`      | `undefined` | Set `XQUIK_API_KEY` or `apiKey`.                            |
+| `network_error`        | `undefined` | The request failed or took over 30 seconds. Retry.          |
+| `unauthenticated`      | `401`       | Check your API key.                                         |
+| `insufficient_credits` | `402`       | Add credits in your Xquik dashboard.                        |
+| `rate_limit_exceeded`  | `429`       | Wait, then retry.                                           |
+| `http_error`           | The status  | The API sent an error without a JSON body. Retry.           |
+| `invalid_response`     | The status  | The response didn't match the contract. Update the plugin.  |
+
+Other API errors keep the API's own `code` & `message`.
+The [API reference](https://docs.xquik.com/api-reference/overview) lists every code.
+
+This controller returns search results & turns an `XquikError` into a JSON error.
+
+```js
+module.exports = ({ strapi }) => ({
+  async search(ctx) {
+    try {
+      ctx.body = await strapi
+        .plugin("xquik")
+        .service("xquik")
+        .searchPosts({ q: ctx.query.q, limit: 10 });
+    } catch (error) {
+      if (error.name !== "XquikError") {
+        throw error;
+      }
+      ctx.status = error.status ?? 500;
+      ctx.body = { error: { code: error.code, message: error.message } };
+    }
+  },
+});
+```
+
+## Develop
+
+```sh
+bin/check-local
+```
+
+`bin/check-local` runs every check in order.
+It installs, then checks format, lint, types & tests.
+It builds & verifies the plugin, then runs `npm audit` & `npm pack --dry-run`.
+Last, it starts a fresh Strapi 5 app with the packed plugin & calls the service over HTTP.
+With `XQUIK_API_KEY` set, that last check calls the live API.
+
+## License
+
+[MIT](LICENSE)

package/dist/server/index.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: "Module" } });
+const zod = require("zod");
+const config = {
+  default: ({ env }) => ({
+    apiKey: env("XQUIK_API_KEY", "")
+  }),
+  validator(config2) {
+    if (typeof config2.apiKey !== "string") {
+      throw new TypeError("Set the xquik apiKey config to a string.");
+    }
+  }
+};
+const XQUIK_URL = "https://xquik.com";
+const API_URL = `${XQUIK_URL}/api/v1/x`;
+const REQUEST_TIMEOUT_MS = 3e4;
+class XquikError extends Error {
+  name = "XquikError";
+  code;
+  status;
+  constructor(code, message, status, options) {
+    super(message, options);
+    this.code = code;
+    this.status = status;
+  }
+}
+const postPageSchema = zod.z.looseObject({
+  tweets: zod.z.array(zod.z.looseObject({ id: zod.z.string() })),
+  has_next_page: zod.z.boolean(),
+  next_cursor: zod.z.string()
+});
+const userProfileSchema = zod.z.looseObject({
+  id: zod.z.string(),
+  username: zod.z.string(),
+  name: zod.z.string()
+});
+const failureSchema = zod.z.looseObject({
+  error: zod.z.string(),
+  message: zod.z.string().optional()
+});
+const failureFrom = (status, body) => {
+  const failure = failureSchema.safeParse(body);
+  return failure.success ? new XquikError(
+    failure.data.error,
+    failure.data.message ?? "Xquik rejected the request. Check the error code.",
+    status
+  ) : new XquikError(
+    "http_error",
+    "Xquik returned an unknown error. Retry later.",
+    status
+  );
+};
+const readApi = async (strapi, path, schema) => {
+  const apiKey = strapi.plugin("xquik").config("apiKey");
+  if (apiKey === "") {
+    throw new XquikError(
+      "missing_api_key",
+      `Set XQUIK_API_KEY. Get a key at ${XQUIK_URL}.`
+    );
+  }
+  const response = await fetch(`${API_URL}${path}`, {
+    headers: { accept: "application/json", "x-api-key": apiKey },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    redirect: "error"
+  }).catch((cause) => {
+    throw new XquikError(
+      "network_error",
+      "Xquik did not answer. Check the network and retry.",
+      void 0,
+      { cause }
+    );
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw failureFrom(response.status, body);
+  }
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) {
+    throw new XquikError(
+      "invalid_response",
+      "Xquik sent an unexpected response. Update the plugin or retry.",
+      response.status
+    );
+  }
+  return parsed.data;
+};
+const xquikService = ({ strapi }) => ({
+  searchPosts(query) {
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) {
+      if (value !== void 0) {
+        params.set(name, String(value));
+      }
+    }
+    return readApi(
+      strapi,
+      `/tweets/search?${params.toString()}`,
+      postPageSchema
+    );
+  },
+  getUser(id) {
+    return readApi(
+      strapi,
+      `/users/${encodeURIComponent(id)}`,
+      userProfileSchema
+    );
+  }
+});
+const index = {
+  config,
+  services: { xquik: xquikService }
+};
+exports.XquikError = XquikError;
+exports.default = index;

package/dist/server/index.mjs

@@ -0,0 +1,114 @@
+import { z } from "zod";
+const config = {
+  default: ({ env }) => ({
+    apiKey: env("XQUIK_API_KEY", "")
+  }),
+  validator(config2) {
+    if (typeof config2.apiKey !== "string") {
+      throw new TypeError("Set the xquik apiKey config to a string.");
+    }
+  }
+};
+const XQUIK_URL = "https://xquik.com";
+const API_URL = `${XQUIK_URL}/api/v1/x`;
+const REQUEST_TIMEOUT_MS = 3e4;
+class XquikError extends Error {
+  name = "XquikError";
+  code;
+  status;
+  constructor(code, message, status, options) {
+    super(message, options);
+    this.code = code;
+    this.status = status;
+  }
+}
+const postPageSchema = z.looseObject({
+  tweets: z.array(z.looseObject({ id: z.string() })),
+  has_next_page: z.boolean(),
+  next_cursor: z.string()
+});
+const userProfileSchema = z.looseObject({
+  id: z.string(),
+  username: z.string(),
+  name: z.string()
+});
+const failureSchema = z.looseObject({
+  error: z.string(),
+  message: z.string().optional()
+});
+const failureFrom = (status, body) => {
+  const failure = failureSchema.safeParse(body);
+  return failure.success ? new XquikError(
+    failure.data.error,
+    failure.data.message ?? "Xquik rejected the request. Check the error code.",
+    status
+  ) : new XquikError(
+    "http_error",
+    "Xquik returned an unknown error. Retry later.",
+    status
+  );
+};
+const readApi = async (strapi, path, schema) => {
+  const apiKey = strapi.plugin("xquik").config("apiKey");
+  if (apiKey === "") {
+    throw new XquikError(
+      "missing_api_key",
+      `Set XQUIK_API_KEY. Get a key at ${XQUIK_URL}.`
+    );
+  }
+  const response = await fetch(`${API_URL}${path}`, {
+    headers: { accept: "application/json", "x-api-key": apiKey },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    redirect: "error"
+  }).catch((cause) => {
+    throw new XquikError(
+      "network_error",
+      "Xquik did not answer. Check the network and retry.",
+      void 0,
+      { cause }
+    );
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw failureFrom(response.status, body);
+  }
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) {
+    throw new XquikError(
+      "invalid_response",
+      "Xquik sent an unexpected response. Update the plugin or retry.",
+      response.status
+    );
+  }
+  return parsed.data;
+};
+const xquikService = ({ strapi }) => ({
+  searchPosts(query) {
+    const params = new URLSearchParams();
+    for (const [name, value] of Object.entries(query)) {
+      if (value !== void 0) {
+        params.set(name, String(value));
+      }
+    }
+    return readApi(
+      strapi,
+      `/tweets/search?${params.toString()}`,
+      postPageSchema
+    );
+  },
+  getUser(id) {
+    return readApi(
+      strapi,
+      `/users/${encodeURIComponent(id)}`,
+      userProfileSchema
+    );
+  }
+});
+const index = {
+  config,
+  services: { xquik: xquikService }
+};
+export {
+  XquikError,
+  index as default
+};

package/dist/server/src/config.d.ts

@@ -0,0 +1,11 @@
+declare const _default: {
+    default: ({ env }: {
+        env: (key: string, fallback: string) => string;
+    }) => {
+        apiKey: string;
+    };
+    validator(config: {
+        apiKey: unknown;
+    }): void;
+};
+export default _default;

package/dist/server/src/index.d.ts

@@ -0,0 +1,23 @@
+export { XquikError } from './services/xquik';
+export type { Post, PostPage, SearchPostsQuery, UserProfile, } from './services/xquik';
+declare const _default: {
+    config: {
+        default: ({ env }: {
+            env: (key: string, fallback: string) => string;
+        }) => {
+            apiKey: string;
+        };
+        validator(config: {
+            apiKey: unknown;
+        }): void;
+    };
+    services: {
+        xquik: ({ strapi }: {
+            strapi: import('./services/xquik').StrapiHandle;
+        }) => {
+            searchPosts(query: import('.').SearchPostsQuery): Promise<import('.').PostPage>;
+            getUser(id: string): Promise<import('.').UserProfile>;
+        };
+    };
+};
+export default _default;

package/dist/server/src/services/xquik.d.ts

@@ -0,0 +1,69 @@
+export declare class XquikError extends Error {
+    readonly name = "XquikError";
+    readonly code: string;
+    readonly status: number | undefined;
+    constructor(code: string, message: string, status?: number, options?: ErrorOptions);
+}
+export interface UserProfile {
+    id: string;
+    username: string;
+    name: string;
+    description?: string;
+    followers?: number;
+    following?: number;
+    verified?: boolean;
+    isBlueVerified?: boolean;
+    isVerified?: boolean;
+    profilePicture?: string;
+    profilePictureOriginal?: string;
+    coverPicture?: string;
+    location?: string;
+    url?: string;
+    createdAt?: string;
+    statusesCount?: number;
+    [field: string]: unknown;
+}
+export interface Post {
+    id: string;
+    text?: string;
+    createdAt?: string;
+    url?: string;
+    lang?: string;
+    likeCount?: number;
+    retweetCount?: number;
+    replyCount?: number;
+    quoteCount?: number;
+    viewCount?: number;
+    bookmarkCount?: number;
+    conversationId?: string;
+    isReply?: boolean;
+    isRetweet?: boolean;
+    isQuoteStatus?: boolean;
+    author?: UserProfile;
+    [field: string]: unknown;
+}
+export interface PostPage {
+    tweets: Post[];
+    has_next_page: boolean;
+    next_cursor: string;
+    [field: string]: unknown;
+}
+export interface SearchPostsQuery {
+    q: string;
+    limit?: number;
+    cursor?: string;
+    queryType?: string;
+    [filter: string]: string | number | boolean | undefined;
+}
+export interface StrapiHandle {
+    plugin(name: "xquik"): {
+        config(key: "apiKey"): string;
+    };
+}
+declare const xquikService: ({ strapi }: {
+    strapi: StrapiHandle;
+}) => {
+    searchPosts(query: SearchPostsQuery): Promise<PostPage>;
+    getUser(id: string): Promise<UserProfile>;
+};
+export default xquikService;

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "strapi-plugin-xquik",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Search X posts & read profiles from Strapi 5 with the Xquik X Twitter data API.",
+  "keywords": [
+    "strapi",
+    "strapi-plugin",
+    "strapi-5",
+    "xquik",
+    "x-twitter-data-api",
+    "twitter-api",
+    "x-api"
+  ],
+  "homepage": "https://xquik.com",
+  "bugs": {
+    "url": "https://github.com/Xquik-dev/strapi-plugin-xquik/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xquik-dev/strapi-plugin-xquik.git"
+  },
+  "license": "MIT",
+  "author": "Xquik",
+  "type": "commonjs",
+  "exports": {
+    "./package.json": "./package.json",
+    "./strapi-server": {
+      "types": "./dist/server/src/index.d.ts",
+      "source": "./server/src/index.ts",
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepack": "strapi-plugin build",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@strapi/sdk-plugin": "6.1.1",
+    "@types/bun": "1.4.4",
+    "oxlint": "1.90.0",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "@strapi/strapi": "^5"
+  },
+  "overrides": {
+    "minimatch": "11.0.4"
+  },
+  "engines": {
+    "node": ">=20.0.0 <=26.x.x"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "strapi": {
+    "kind": "plugin",
+    "name": "xquik",
+    "displayName": "Xquik",
+    "description": "Search X posts & read profiles from Strapi 5 with the Xquik X Twitter data API."
+  }
+}