const XQUIK_BASE_URL = "https://xquik.com";

function readXquikApiKey(): string {
  const apiKey = process.env.XQUIK_API_KEY;
  if (!apiKey) throw new Error("XQUIK_API_KEY is required.");
  return apiKey;
}

async function xquikRequest(path: string): Promise<Response> {
  return fetch(`${XQUIK_BASE_URL}${path}`, {
    headers: { "x-api-key": readXquikApiKey() },
  });
}

export { xquikRequest };

const response = await fetch(
  "https://xquik.com/api/v1/account?api_key=xq_example",
);

const OPENAPI_URL = "https://xquik.com/openapi.json";
const SEARCH_PATH = "/api/v1/x/tweets/search";

async function assertSearchOperationExists(): Promise<void> {
  const response = await fetch(OPENAPI_URL);
  if (!response.ok) throw new Error("Unable to load Xquik OpenAPI.");
  const spec = (await response.json()) as {
    paths?: Record<string, { get?: unknown }>;
  };
  if (!spec.paths?.[SEARCH_PATH]?.get) {
    throw new Error("Tweet search is absent from the current contract.");
  }
}

export { assertSearchOperationExists };

async function search(query: string): Promise<unknown> {
  return fetch(`https://xquik.com/v2/search?query=${query}`);
}

const DEFAULT_SEARCH_LIMIT = 20;

function buildSearchPath(query: string, cursor?: string): string {
  const params = new URLSearchParams({
    q: query,
    queryType: "Latest",
    limit: String(DEFAULT_SEARCH_LIMIT),
  });
  if (cursor) params.set("cursor", cursor);
  return `/api/v1/x/tweets/search?${params}`;
}

export { buildSearchPath };

function nextSearchPath(query: string, cursor: string): string {
  const decoded = Buffer.from(cursor, "base64").toString("utf8");
  return `/api/v1/x/tweets/search?q=${query}&cursor=${decoded}`;
}

const RETRYABLE_STATUS_CODES = new Set([429, 500, 502, 503, 504]);

function canRetryRead(response: Response): boolean {
  return RETRYABLE_STATUS_CODES.has(response.status);
}

export { canRetryRead };

async function retryAnyRequest(request: Request): Promise<Response> {
  const response = await fetch(request);
  return response.ok ? response : fetch(request);
}

type CreatePostInput = {
  account: string;
  text: string;
};

async function createPostAfterApproval(
  input: CreatePostInput,
  approved: boolean,
): Promise<Response> {
  if (!approved) throw new Error("Explicit approval is required.");
  return fetch("https://xquik.com/api/v1/x/tweets", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      "x-api-key": readXquikApiKey(),
    },
    body: JSON.stringify(input),
  });
}

export { createPostAfterApproval };

async function autoPost(text: string): Promise<Response> {
  return fetch("https://xquik.com/api/v1/x/tweets", {
    method: "POST",
    body: JSON.stringify({ text }),
  });
}

type WebhookEnvelope = {
  rawBody: Uint8Array;
  signature: string;
  timestamp: string;
  nonce: string;
};

type VerifyWebhook = (envelope: WebhookEnvelope) => Promise<void>;
type ProcessEvent = (payload: unknown) => Promise<void>;

async function acceptWebhook(
  envelope: WebhookEnvelope,
  verifyWebhook: VerifyWebhook,
  processEvent: ProcessEvent,
): Promise<void> {
  await verifyWebhook(envelope);
  const payload = JSON.parse(new TextDecoder().decode(envelope.rawBody));
  await processEvent(payload);
}

export { acceptWebhook };

async function acceptWebhook(
  request: Request,
  processEvent: ProcessEvent,
): Promise<void> {
  const payload = await request.json();
  await processEvent(payload);
}

What does the workflow need?
- A backend or script needs precise endpoint control -> Use REST
- An AI client needs natural-language tools -> Use the Xquik MCP server
- A one-time public data read -> Use a bounded GET request
- Multiple result pages -> Follow next_cursor while has_next_page is true
- Live monitor events -> Create a monitor and signed webhook after approval
- An X mutation -> Display account and payload, request approval, then call once
- A 202 write response -> Poll the returned write action; do not resubmit
- A 429 or temporary 5xx on a GET -> Honor Retry-After and retry with backoff
- A 4xx validation or authentication response -> Correct the request; do not retry