@mgcrea/mcp-x-api 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,836 @@
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/server";
+//#region src/build-info.d.ts
+type BuildInfo = {
+  name: string;
+  version: string;
+  gitCommit: string;
+  gitCommitDate: string;
+};
+declare const BUILD_INFO: BuildInfo;
+//#endregion
+//#region src/client/tokens.d.ts
+type StoredTokens = {
+  version: number;
+  /** A changed client id invalidates the whole file: the tokens belong to that app. */
+  clientId: string;
+  scopes: string[];
+  accessToken: string;
+  refreshToken?: string;
+  /**
+   * One generation back. X invalidates the old refresh token the instant a
+   * refresh succeeds, so if we crash between receiving new tokens and writing
+   * them, the on-disk token is already dead. Keeping the previous one lets a
+   * failed refresh retry once instead of forcing the user through a browser.
+   */
+  previousRefreshToken?: string;
+  /** Milliseconds since epoch. */
+  expiresAt: number;
+  obtainedAt: number;
+  userId?: string;
+  username?: string;
+};
+type TokenStore = {
+  read(): StoredTokens | undefined;
+  write(tokens: StoredTokens): void;
+  clear(): void;
+  path: string;
+};
+//#endregion
+//#region src/config.d.ts
+declare const DEFAULT_ADS_BASE_URL = "https://ads-api.x.com";
+/**
+ * The Ads API sandbox: free, isolated, and the only sane place to exercise the
+ * write tools. Note the host — X's own docs say `ads-api-sandbox.x.com`, which
+ * has no DNS record at all. `ads-api-sandbox.twitter.com` is the one that
+ * resolves, so this is not a typo waiting to be "fixed".
+ */
+declare const SANDBOX_ADS_BASE_URL = "https://ads-api-sandbox.twitter.com";
+/**
+ * X moved to pay-per-use on 2026-02-06; there is no free tier for new
+ * developers. These are list prices in USD, overridable via the config file's
+ * `pricing` key because a table baked into a schema with no escape hatch is
+ * wrong the day X changes it.
+ *
+ * The 24h dedup window is the load-bearing rule: within one UTC day, re-reading
+ * a resource id you already paid for is free. That is why the ledger keys on
+ * (kind, id, utcDay) rather than counting requests.
+ */
+declare const DEFAULT_PRICING: {
+  postRead: number;
+  userRead: number;
+  /** Your own posts and profile — five times cheaper than reading someone else's. */
+  ownedRead: number;
+  postCreate: number;
+  /** A post containing a URL costs 40x a post read. Not a typo. */
+  postCreateWithUrl: number;
+  monthlyReadCap: number;
+  effectiveFrom: string;
+};
+declare const PricingSchema: z.ZodObject<{
+  postRead: z.ZodDefault<z.ZodNumber>;
+  userRead: z.ZodDefault<z.ZodNumber>;
+  ownedRead: z.ZodDefault<z.ZodNumber>;
+  postCreate: z.ZodDefault<z.ZodNumber>;
+  postCreateWithUrl: z.ZodDefault<z.ZodNumber>;
+  monthlyReadCap: z.ZodDefault<z.ZodNumber>;
+  effectiveFrom: z.ZodDefault<z.ZodString>;
+}, z.core.$strict>;
+type Pricing = z.infer<typeof PricingSchema>;
+declare const ConfigSchema: z.ZodObject<{
+  bearerToken: z.ZodOptional<z.ZodString>;
+  clientId: z.ZodOptional<z.ZodString>;
+  clientSecret: z.ZodOptional<z.ZodString>;
+  redirectUri: z.ZodDefault<z.ZodString>;
+  scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  tokenFile: z.ZodString;
+  allowWrites: z.ZodDefault<z.ZodBoolean>;
+  writeBackend: z.ZodDefault<z.ZodEnum<{
+    api: "api";
+    intent: "intent";
+  }>>;
+  autoOpenBrowser: z.ZodDefault<z.ZodBoolean>;
+  enableFullArchive: z.ZodDefault<z.ZodBoolean>;
+  defaultMaxResults: z.ZodDefault<z.ZodNumber>;
+  monthlyBudgetUsd: z.ZodOptional<z.ZodNumber>;
+  cacheEnabled: z.ZodDefault<z.ZodBoolean>;
+  cacheMaxEntries: z.ZodDefault<z.ZodNumber>;
+  maxRetries: z.ZodDefault<z.ZodNumber>;
+  baseUrl: z.ZodDefault<z.ZodString>;
+  pricing: z.ZodDefault<z.ZodObject<{
+    postRead: z.ZodDefault<z.ZodNumber>;
+    userRead: z.ZodDefault<z.ZodNumber>;
+    ownedRead: z.ZodDefault<z.ZodNumber>;
+    postCreate: z.ZodDefault<z.ZodNumber>;
+    postCreateWithUrl: z.ZodDefault<z.ZodNumber>;
+    monthlyReadCap: z.ZodDefault<z.ZodNumber>;
+    effectiveFrom: z.ZodDefault<z.ZodString>;
+  }, z.core.$strict>>;
+  adsEnabled: z.ZodDefault<z.ZodBoolean>;
+  adsAllowWrites: z.ZodDefault<z.ZodBoolean>;
+  adsBaseUrl: z.ZodDefault<z.ZodString>;
+  adsAccountId: z.ZodOptional<z.ZodString>;
+  adsMaxDownloadBytes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+type Config = z.infer<typeof ConfigSchema>;
+/**
+ * Where the config file lives, most specific first: an explicit override, then
+ * the XDG location, then the conventional `~/.config`.
+ */
+declare const resolveConfigPath: (env?: NodeJS.ProcessEnv) => string;
+/**
+ * Environment first, config file second, **per field** — not whole-source.
+ * Docker and CI inject the environment and must keep working untouched, while a
+ * one-off `X_API_ALLOW_WRITES=0` still has to override a file that says `true`.
+ * Merging field by field is the only rule that gives both.
+ */
+declare const loadConfig: (env?: NodeJS.ProcessEnv, configPath?: string) => Config;
+/**
+ * Whether the ads tools should be registered. The Ads API rides the same OAuth
+ * 2.0 user token as bookmarks and the home timeline — the `ads.read` /
+ * `ads.write` scopes are what separate them — so a client id is the hard
+ * requirement, not a second set of credentials.
+ */
+declare const hasAdsAccess: (config: Config) => boolean;
+/**
+ * What to do when ads is enabled but the account cannot reach the Ads API.
+ * Surfaced by `x_auth_status`, because the two steps people miss are invisible
+ * from the error alone: the app needs the Ads Project attached, and any token
+ * minted *before* approval does not carry the entitlement.
+ */
+declare const adsSetupInstructions: (config: Config) => string[];
+/**
+ * The scopes actually requested at login. `tweet.write` is only asked for when
+ * the paid write backend is on, so a reader never holds a permission it cannot
+ * use — and the consent screen stays honest about what the server will do.
+ */
+declare const effectiveScopes: (config: Config) => string[];
+//#endregion
+//#region src/client/auth.d.ts
+type Logger = {
+  debug?: (message: string) => void;
+  warn?: (message: string) => void;
+  error?: (message: string) => void;
+};
+/**
+ * X has two credentials that are not interchangeable, so every request has to
+ * say which one it wants:
+ *
+ * - `"app"` — the app-only Bearer token. Reaches everything public: post
+ *   lookup, search, user profiles, user timelines.
+ * - `"user"` — an OAuth2 access token for a logged-in account. The only way to
+ *   reach bookmarks and the home timeline, and the only way to write.
+ *
+ * This is the one place the shape diverges from a single-credential API: the
+ * token provider is asked for a context rather than just "the token".
+ */
+type AuthContext = "app" | "user";
+type UserAuthStatus = {
+  authenticated: false;
+  reason: string;
+} | {
+  authenticated: true;
+  username?: string;
+  userId?: string;
+  scopes: string[];
+  expiresAt: number;
+};
+type AuthStatus = {
+  app: boolean;
+  user: UserAuthStatus;
+};
+type TokenProvider = {
+  /** Bearer value for the requested context. Throws `UserContextRequiredError` if unavailable. */
+  getToken(context: AuthContext): Promise<string>;
+  /** Called on a 401 to force the next call to remint or refresh. */
+  invalidate(context: AuthContext): void;
+  /** Powers `x_auth_status` and the startup banner. */
+  describe(): AuthStatus;
+};
+/**
+ * The app-only Bearer token, copied from the developer portal. It never
+ * expires and cannot be reminted, so `invalidate` is a no-op: a 401 here means
+ * the token is wrong, and retrying with the same string would only burn the
+ * retry budget.
+ */
+declare const bearerTokenProvider: (token: string) => TokenProvider;
+/**
+ * Combine whichever providers are configured, dispatching by context. Either
+ * side may be absent — a Bearer-only install is the common case, and a
+ * user-only install is legitimate too (an OAuth2 access token can read
+ * everything an app-only token can).
+ */
+declare const compositeTokenProvider: (parts: {
+  app?: TokenProvider;
+  user?: TokenProvider;
+}) => TokenProvider;
+/** The test double: one token, both contexts, no network. */
+declare const staticTokenProvider: (token: string) => TokenProvider;
+//#endregion
+//#region src/client/http.d.ts
+type QueryValue = string | number | boolean | string[] | undefined;
+type Query = Record<string, QueryValue>;
+/**
+ * What the last response told us about how much of an endpoint's budget is left.
+ *
+ * `scope` and `api` are optional because the v2 API reports exactly one family
+ * of rate-limit headers and has no need to distinguish them. The Ads API
+ * reports three (endpoint, account and cost), so it fills them in.
+ */
+type RateLimitSnapshot = {
+  endpoint: string;
+  limit?: number;
+  remaining?: number;
+  /** Unix seconds, as X reports it. */
+  reset?: number;
+  resetAt?: string;
+  scope?: "endpoint" | "account" | "cost";
+  api?: "v2" | "ads";
+};
+//#endregion
+//#region src/client/ads.d.ts
+type AdsApiClientOptions = {
+  baseUrl?: string;
+  /**
+   * The same provider the v2 client uses. The Ads API is always asked for the
+   * `"user"` context: there is no app-only path to `/12/accounts`.
+   */
+  tokenProvider: TokenProvider;
+  maxRetries?: number;
+  maxDownloadBytes?: number;
+  fetch?: typeof fetch;
+  logger?: Logger;
+  userAgent?: string;
+};
+type CursorPage<T> = {
+  data: T[];
+  pages: number;
+  nextCursor?: string;
+  totalCount?: number;
+};
+/**
+ * Fetch-based client for the X Ads API v12. Deliberately not an `XApiClient`
+ * subclass: the two share transport concerns and nothing else. Ads paginates by
+ * cursor rather than `next_token`, answers errors in two envelopes neither of
+ * which is v2's problem-details, reports three families of rate-limit headers,
+ * and needs its own diagnostics — the v2 prose about the Pay-per-use package is
+ * actively misleading here. What genuinely is shared lives in `./http.js`.
+ *
+ * Writes send their parameters in the query string, never a JSON body: that is
+ * what the Ads API takes on POST and PUT, and what X's own SDKs send.
+ */
+declare class AdsApiClient {
+  readonly sandbox: boolean;
+  readonly baseUrl: string;
+  private readonly tokenProvider;
+  private readonly maxRetries;
+  private readonly maxDownloadBytes;
+  private readonly fetchImpl;
+  private readonly logger;
+  private readonly userAgent;
+  private readonly rateLimits;
+  constructor(opts: AdsApiClientOptions);
+  rateLimitStatus(): RateLimitSnapshot[];
+  /**
+   * Ads reports three independent budgets, and a 429 can come from any of them.
+   * Recording only the endpoint family would leave the account-level limit —
+   * the one that actually bites during a bulk read — invisible.
+   */
+  private recordRateLimit;
+  request<T = unknown>(method: string, path: string, query?: Query): Promise<T>;
+  get<T = unknown>(path: string, query?: Query): Promise<T>;
+  post<T = unknown>(path: string, query?: Query): Promise<T>;
+  put<T = unknown>(path: string, query?: Query): Promise<T>;
+  del<T = unknown>(path: string, query?: Query): Promise<T>;
+  /**
+   * GET a collection, following `next_cursor` until the pages run out or a
+   * bound is hit.
+   *
+   * Unlike v2, the cursor is a top-level field rather than nested under `meta`,
+   * it is `null` (not absent) on the last page, and it goes back out as
+   * `cursor`. Everything else about the loop matches `XApiClient.paginate`,
+   * which is why this is a separate method rather than a shared one — the
+   * differences are exactly the parts that matter.
+   */
+  paginateCursor<T = unknown>(path: string, query: Query, opts: {
+    maxItems: number;
+    maxPages?: number;
+  }): Promise<CursorPage<T>>;
+  /**
+   * Fetch a finished analytics job's result file and decompress it.
+   *
+   * Three things here are load-bearing. The URL is a presigned object-store
+   * link on a different host, so it must go out with **no** Authorization
+   * header — signing it makes the store reject it. The host is checked first,
+   * because the URL came from a remote response. And both the compressed and
+   * decompressed sizes are capped: a 25 MB gzip of repetitive JSON expands to
+   * hundreds of megabytes, so an uncapped gunzip here is an OOM waiting for a
+   * big enough report.
+   */
+  downloadGzipped(url: string): Promise<{
+    text: string;
+    bytes: number;
+  }>;
+  private parseErrors;
+  /**
+   * Ads answers in two envelopes. The gateway rejects bad auth with the legacy
+   * v1.1 shape and a *numeric* code — and with HTTP 400, not 401. Past that,
+   * application errors use CAPS_CASE string codes. Both are quoted here, and
+   * each status gets the sentence that actually fixes it: a bare
+   * "UNAUTHORIZED_ACCESS" sends people to re-check a token that is usually fine.
+   */
+  private errorMessage;
+}
+//#endregion
+//#region src/client/ads-shape.d.ts
+/** X states every money field in millionths of a currency unit. */
+declare const MICRO = 1000000;
+declare const toMicro: (major: number) => number;
+declare const fromMicro: (micro: number) => number;
+/**
+ * Pair every `*_amount_local_micro` field with the value a human would say.
+ *
+ * This is not cosmetic. A model that reads `daily_budget_amount_local_micro:
+ * 50000000` and reasons about it concludes the budget is fifty million, and the
+ * next thing it proposes is scaled by a factor of a million. The write path
+ * guards against the same mistake by refusing micro inputs; this is the other
+ * half, and without it the guard only covers one direction.
+ *
+ * The micro field is kept rather than replaced, so the raw value X returned
+ * stays auditable.
+ */
+declare const shapeMoney: <T>(value: T, currency?: string) => T;
+//#endregion
+//#region src/client/cache.d.ts
+type ResourceKind = "post" | "user" | "owned";
+type CacheStats = {
+  day: string;
+  entries: number;
+  hits: number;
+  misses: number;
+  hit_rate: number;
+};
+type DayCache = {
+  get(kind: ResourceKind, id: string): unknown | undefined;
+  set(kind: ResourceKind, id: string, value: unknown): void;
+  stats(): CacheStats;
+};
+/**
+ * The dedup window is the UTC calendar day, not a rolling 24 hours — so the
+ * whole cache turns over at once at UTC midnight rather than expiring entry by
+ * entry. Comparing a stored day string is both cheaper and more faithful than
+ * per-entry timestamps.
+ */
+declare const utcDay: (now: number) => string;
+declare const createDayCache: (opts: {
+  maxEntries: number;
+  enabled?: boolean;
+  now?: () => number;
+}) => DayCache;
+//#endregion
+//#region src/client/cost.d.ts
+/**
+ * Which resource ids we have already been billed for today.
+ *
+ * This is deliberately NOT the response cache. The cache stores payloads and is
+ * LRU-bounded; this stores only ids and is unbounded. If they were one
+ * structure, evicting a payload under memory pressure would make the estimator
+ * re-count an id X already charged us for, and over-report spend. Ids are ~20
+ * bytes, so keeping every one for a day costs kilobytes in practice.
+ */
+type Ledger = {
+  /** Split ids into the ones today's read actually bills for and the ones already paid. */
+  record(kind: ResourceKind, ids: string[]): {
+    billable: string[];
+    free: string[];
+  };
+  /** Estimate a read before issuing it, for the budget guard. */
+  estimate(kind: ResourceKind, ids: string[]): number;
+  /** Estimate by count, for reads whose result ids are unknown in advance (searches). */
+  estimateCount(kind: ResourceKind, count: number): number;
+  recordCreate(hasUrl: boolean): void;
+  spentUsd(): number;
+  report(cache: CacheStats): UsageReport;
+};
+type CostNote = {
+  billable_post_reads?: number;
+  billable_user_reads?: number;
+  owned_reads?: number;
+  free_from_cache?: number;
+  estimated_usd: number;
+  note?: string;
+};
+type UsageReport = {
+  day: string;
+  since_process_start: {
+    billable_post_reads: number;
+    billable_user_reads: number;
+    owned_reads: number;
+    free_from_dedup: number;
+    posts_created: number;
+    estimated_usd: number;
+  };
+  read_cap: {
+    monthly_cap: number;
+    reads_this_session: number;
+    cap_used_pct: number;
+  };
+  budget?: {
+    limit_usd: number;
+    remaining_usd: number;
+  };
+  cache: CacheStats;
+  pricing: Pricing;
+  disclaimer: string;
+};
+declare const createLedger: (opts: {
+  pricing: Pricing;
+  budgetUsd?: number | undefined;
+  now?: () => number;
+}) => Ledger;
+//#endregion
+//#region src/client/errors.d.ts
+/**
+ * X answers errors in two shapes depending on the endpoint: a problem-details
+ * object (`{ title, detail, status, type }`) on v2, and a legacy
+ * `{ errors: [{ message, code }] }` on a few others. Both are modelled here so
+ * the client can quote whichever it got.
+ */
+type XApiError = {
+  title?: string;
+  detail?: string;
+  type?: string;
+  status?: number;
+  message?: string;
+  code?: number | string;
+  /** Ads application errors carry the offending field here. */
+  details?: unknown;
+  /** Present on partial responses, e.g. one deleted post in a batch lookup. */
+  resource_type?: string;
+  parameter?: string;
+  value?: string;
+};
+declare class XApiRequestError extends Error {
+  readonly name = "XApiRequestError";
+  readonly status: number;
+  readonly errors: XApiError[] | unknown;
+  constructor(message: string, opts: {
+    status: number;
+    errors?: XApiError[] | unknown;
+  });
+}
+/**
+ * Thrown when a tool needs a logged-in user and only an app-only Bearer token
+ * is available. The message carries the fix, because "401 Unauthorized" tells
+ * you nothing about which of two credentials was missing.
+ */
+declare class UserContextRequiredError extends Error {
+  readonly name = "UserContextRequiredError";
+  constructor(what: string, reason?: string);
+}
+/** Thrown when a write tool is reached while X_API_ALLOW_WRITES is off. */
+declare class WritesDisabledError extends Error {
+  readonly name = "WritesDisabledError";
+  constructor(what: string);
+}
+/**
+ * Thrown when the Ads API is reachable but this account cannot use it — no Ads
+ * entitlement on the app, or no ads account behind the logged-in user. Separate
+ * from `UserContextRequiredError` because logging in again does not fix it: the
+ * missing piece is an approval, not a token.
+ */
+declare class AdsAccessError extends Error {
+  readonly name = "AdsAccessError";
+  readonly details: Record<string, unknown>;
+  constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * A local guard that fires *before* the request goes out, so an agent in a loop
+ * cannot spend past the ceiling. Carries the arithmetic so the number is
+ * auditable rather than mysterious.
+ */
+declare class BudgetExceededError extends Error {
+  readonly name = "BudgetExceededError";
+  readonly details: Record<string, unknown>;
+  constructor(opts: {
+    estimateUsd: number;
+    spentUsd: number;
+    limitUsd: number;
+    what: string;
+  });
+}
+/**
+ * A local check that failed before we sent anything to X. Carries the state it
+ * read, so the caller sees why rather than just that something was wrong.
+ */
+declare class PreconditionError extends Error {
+  readonly name = "PreconditionError";
+  readonly details: Record<string, unknown>;
+  constructor(message: string, details?: Record<string, unknown>);
+}
+//#endregion
+//#region src/client/shape.d.ts
+type Rec$1 = Record<string, unknown>;
+/** Three lookup tables built once per response. */
+type Includes = {
+  users: Map<string, Rec$1>;
+  tweets: Map<string, Rec$1>;
+  media: Map<string, Rec$1>;
+};
+/**
+ * Build the lookup tables from one `includes` block or several (paginated reads
+ * return one per page).
+ *
+ * These are `Map`s rather than an `Array.find` per lookup on purpose: a 100-post
+ * page with 100 distinct authors would otherwise be quadratic, and the whole
+ * point of this module is that it stays cheap on the largest responses.
+ */
+declare const buildIncludesIndex: (includes: Rec$1 | Rec$1[] | undefined) => Includes;
+/** A referenced post, resolved one level deep only. */
+type ShapedRef = {
+  id: string;
+  author?: string;
+  text?: string;
+  created_at?: string;
+};
+type ShapedPost = {
+  id: string;
+  url: string;
+  author: string;
+  created_at?: string;
+  text: string;
+  lang?: string;
+  metrics?: {
+    likes?: number;
+    reposts?: number;
+    replies?: number;
+    quotes?: number;
+    views?: number;
+  };
+  quotes?: ShapedRef;
+  replies_to?: ShapedRef;
+  reposts?: ShapedRef;
+  media?: string[];
+  conversation_id?: string;
+};
+type ShapedUser = {
+  id: string;
+  username: string;
+  name?: string;
+  url: string;
+  description?: string;
+  verified?: boolean;
+  protected?: boolean;
+  location?: string;
+  created_at?: string;
+  metrics?: {
+    followers?: number;
+    following?: number;
+    posts?: number;
+    listed?: number;
+  };
+};
+declare const shapeUser: (raw: Rec$1) => ShapedUser;
+type ShapedPosts = {
+  posts: ShapedPost[];
+  result_count?: number;
+  next_token?: string;
+  /** Ids X refused to return — deleted, protected, or suspended. */
+  not_found?: string[];
+};
+/** Flatten a list-of-posts response. Accepts a single- or multi-page envelope. */
+declare const shapePostsResponse: (response: unknown) => ShapedPosts;
+/** Flatten a single-post response. */
+declare const shapePostResponse: (response: unknown) => ShapedPost | {
+  error: string;
+};
+type ShapedUsers = {
+  users: ShapedUser[];
+  not_found?: string[];
+};
+declare const shapeUsersResponse: (response: unknown) => ShapedUsers;
+//#endregion
+//#region src/client/x.d.ts
+type RequestOptions = {
+  query?: Query;
+  body?: unknown;
+  /** Which credential to send. Defaults to the app-only Bearer token. */
+  auth?: AuthContext;
+};
+type XApiClientOptions = {
+  baseUrl?: string;
+  tokenProvider: TokenProvider;
+  maxRetries?: number;
+  fetch?: typeof fetch;
+  logger?: Logger;
+  userAgent?: string;
+};
+/**
+ * Minimal fetch-based client for the X API v2. Paths are absolute (`/2/tweets`).
+ * Retries a 401 (invalidating the token first) and 429/5xx with exponential
+ * backoff honoring `Retry-After`, and records every response's rate-limit
+ * headers so a 429 can say what it is waiting for.
+ */
+declare class XApiClient {
+  private readonly baseUrl;
+  private readonly tokenProvider;
+  private readonly maxRetries;
+  private readonly fetchImpl;
+  private readonly logger;
+  private readonly userAgent;
+  private readonly rateLimits;
+  constructor(opts: XApiClientOptions);
+  /** Everything the last response said about each endpoint's remaining budget. */
+  rateLimitStatus(): RateLimitSnapshot[];
+  private recordRateLimit;
+  request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+  get<T = unknown>(path: string, query?: Query, auth?: AuthContext): Promise<T>;
+  post<T = unknown>(path: string, body?: unknown, auth?: AuthContext): Promise<T>;
+  del<T = unknown>(path: string, auth?: AuthContext): Promise<T>;
+  /**
+   * GET a collection, following `meta.next_token` until the pages run out or a
+   * bound is hit.
+   *
+   * Both bounds exist because unbounded pagination here spends real money: at
+   * $0.005 a post, walking a busy hashtag to the end is a three-figure mistake
+   * an agent can make in one call. `maxItems` is the one callers actually set.
+   *
+   * X carries the cursor in `meta.next_token` and expects it back as
+   * `pagination_token`, so — unlike a `links.next` API — the original query has
+   * to be re-sent on every page rather than replaced.
+   */
+  paginate<T = unknown>(path: string, query: Query, opts: {
+    maxItems: number;
+    maxPages?: number;
+    auth?: AuthContext;
+  }): Promise<{
+    data: T[];
+    pages: number;
+    nextToken?: string;
+    includes: Rec[];
+  }>;
+  private parseErrors;
+  /**
+   * The three statuses that actually happen get a sentence naming the fix. A
+   * bare "HTTP 403" sends people to the wrong place — usually to re-check a
+   * token that was fine, when the real answer is that their access tier does
+   * not include the endpoint.
+   */
+  private errorMessage;
+  private problemDetail;
+}
+type Rec = Record<string, unknown>;
+//#endregion
+//#region src/compose/intent.d.ts
+/**
+ * X's web intent: a documented, credential-free URL that opens the composer
+ * pre-filled. Nothing is posted until a human clicks Post, which is why it
+ * needs no auth, consumes no API quota and costs nothing.
+ *
+ * The path is `/intent/tweet`, not `/intent/post`. X renamed Tweet to Post
+ * throughout its docs prose but never changed the URL, and `/intent/post` is
+ * undocumented with known edge-case bugs. `twitter.com` 301s to `x.com`, so
+ * there is no reason to emit the legacy domain.
+ */
+declare const INTENT_BASE_URL = "https://x.com/intent/tweet";
+type IntentInput = {
+  text: string;
+  /** Appended by the composer and counted against the 280. */
+  url?: string | undefined;
+  /** Without the leading '#'. */
+  hashtags?: string[] | undefined;
+  /** Handle without the leading '@'. */
+  via?: string | undefined;
+  /** The post id being replied to. */
+  inReplyTo?: string | undefined;
+  lang?: string | undefined;
+};
+/**
+ * What the composer will actually contain, in X's documented assembly order:
+ * text, then url, then hashtags, then "via @handle".
+ *
+ * Validating `text` alone and then handing back a URL the composer rejects is
+ * exactly the bug this module exists to prevent, so counting happens on this
+ * string rather than on the input.
+ */
+declare const assembleComposerText: (input: IntentInput) => string;
+declare const buildIntentUrl: (input: IntentInput) => string;
+type IntentValidation = {
+  valid: boolean;
+  weighted: number;
+  remaining: number;
+  composed: string;
+  intent_url: string;
+  warnings: string[];
+  error?: string;
+};
+declare const validateIntent: (input: IntentInput) => IntentValidation;
+//#endregion
+//#region src/compose/weighted.d.ts
+declare const MAX_WEIGHTED_LENGTH = 280;
+/**
+ * Every URL costs the same whatever its real length: X rewrites it to t.co.
+ * There is a single value now — the old http/https split was deprecated once
+ * every t.co link became https.
+ */
+declare const TCO_URL_LENGTH = 23;
+type WeightedLength = {
+  /** 0-280+, in the units X shows the user. */
+  weighted: number;
+  remaining: number;
+  valid: boolean;
+  urls: {
+    url: string;
+    countedAs: number;
+  }[];
+};
+/**
+ * Count a draft the way X will.
+ *
+ * NFC normalization comes first because twitter-text normalizes first: without
+ * it a decomposed "café" counts 5 instead of 4, and the user is told they have
+ * one character less than they do.
+ */
+declare const weightedLength: (text: string) => WeightedLength;
+//#endregion
+//#region src/server.d.ts
+declare const SERVER_NAME: string;
+declare const SERVER_VERSION: string;
+type CreateServerOptions = {
+  config: Config;
+  fetch?: typeof fetch;
+  logger?: Logger;
+  /** Override the token provider (tests, and the OAuth user flow). */
+  tokenProvider?: TokenProvider;
+  now?: () => number;
+};
+type CreatedServer = {
+  server: McpServer;
+  client: XApiClient;
+  /** Present only when ads is configured. Exposed for tests and diagnostics. */
+  ads?: AdsApiClient | undefined;
+  tokenProvider: TokenProvider;
+  cache: DayCache;
+  ledger: Ledger;
+  store: TokenStore;
+};
+declare const createServer: (opts: CreateServerOptions) => CreatedServer;
+//#endregion
+//#region src/tools/index.d.ts
+/**
+ * Everything the ads tools need, as one object rather than four independently
+ * optional fields: "the client exists exactly when ads is configured" is then
+ * an invariant the type enforces rather than one that can drift.
+ */
+type AdsContext = {
+  client: AdsApiClient;
+  /** Register the campaign-mutating tools. Off by default — see X_ADS_ALLOW_WRITES. */
+  allowWrites: boolean;
+  /** Default ads account. Absent means "resolve it lazily from GET /12/accounts". */
+  accountId?: string | undefined;
+  /** True when pointed at the Ads sandbox, where nothing spends real money. */
+  sandbox: boolean;
+  baseUrl: string;
+};
+/**
+ * Threaded through every tool rather than a bare `allowWrites` boolean: the
+ * cache and ledger are needed by every read tool, so a boolean would have been
+ * widened on the first commit anyway.
+ */
+type ToolContext = {
+  /** Register the paid write tools too. Off by default — see X_API_ALLOW_WRITES. */
+  allowWrites: boolean;
+  /** "intent" (free web-intent URLs, the default) or "api" (paid POST /2/tweets). */
+  writeBackend: "intent" | "api";
+  autoOpenBrowser: boolean;
+  /** Register x_search_all. Off by default — full-archive search needs a paid tier. */
+  enableFullArchive: boolean;
+  defaultMaxResults: number;
+  pricing: Pricing;
+  budgetUsd?: number | undefined;
+  cache: DayCache;
+  ledger: Ledger;
+  tokenProvider: TokenProvider;
+  /**
+   * False when neither a Bearer token nor an OAuth client id is configured. The
+   * server still starts and still serves the free local tools; the ones that
+   * would call the X API are simply not registered.
+   */
+  hasCredentials: boolean;
+  /** Setup guidance surfaced by x_auth_status when nothing is configured. */
+  setup?: string[] | undefined;
+  /** Where the OAuth tokens live, for x_auth_status. Absent when OAuth is unconfigured. */
+  tokenFile?: string | undefined;
+  /**
+   * The token file, so a user id discovered lazily can be written back and not
+   * re-fetched on every call. Absent when OAuth is unconfigured.
+   */
+  tokenStore?: TokenStore | undefined;
+  /** Present only when a client id is configured; its presence registers the login tools. */
+  login?: ((open: boolean) => Promise<LoginSummary>) | undefined;
+  logout?: (() => void) | undefined;
+  /** Present only when X_ADS_ENABLED is on and an OAuth client id is configured. */
+  ads?: AdsContext | undefined;
+  /** Ads setup guidance surfaced by x_auth_status when ads is not configured. */
+  adsSetup?: string[] | undefined;
+};
+type LoginSummary = {
+  username?: string | undefined;
+  userId?: string | undefined;
+  scopes: string[];
+  tokenFile: string;
+};
+/**
+ * Register the X API tools.
+ *
+ * Read tools and the free compose tools are always registered. The paid write
+ * tools appear only when `allowWrites` *and* `writeBackend === "api"`;
+ * `x_search_all` only when full-archive access is enabled; and the login tools
+ * and user-context timelines only when an OAuth client id is configured — so
+ * with the defaults those tools are not merely refused, they are invisible and
+ * cannot be called at all.
+ */
+declare const registerTools: (server: McpServer, client: XApiClient, ctx: ToolContext) => void;
+//#endregion
+export { AdsAccessError, AdsApiClient, type AdsApiClientOptions, type AdsContext, type AuthContext, type AuthStatus, BUILD_INFO, BudgetExceededError, type BuildInfo, type Config, type CostNote, type CreateServerOptions, type CreatedServer, type CursorPage, DEFAULT_ADS_BASE_URL, DEFAULT_PRICING, type DayCache, INTENT_BASE_URL, type IntentInput, type Ledger, type Logger, MAX_WEIGHTED_LENGTH, MICRO, PreconditionError, type Pricing, type Query, type RateLimitSnapshot, type ResourceKind, SANDBOX_ADS_BASE_URL, SERVER_NAME, SERVER_VERSION, type ShapedPost, type ShapedUser, TCO_URL_LENGTH, type TokenProvider, type ToolContext, type UsageReport, UserContextRequiredError, WritesDisabledError, XApiClient, type XApiClientOptions, type XApiError, XApiRequestError, adsSetupInstructions, assembleComposerText, bearerTokenProvider, buildIncludesIndex, buildIntentUrl, compositeTokenProvider, createDayCache, createLedger, createServer, effectiveScopes, fromMicro, hasAdsAccess, loadConfig, registerTools, resolveConfigPath, shapeMoney, shapePostResponse, shapePostsResponse, shapeUser, shapeUsersResponse, staticTokenProvider, toMicro, utcDay, validateIntent, weightedLength };
+//# sourceMappingURL=index.d.ts.map