@xpoz/xpoz 0.6.12 → 0.7.0

package/README.md

@@ -86,11 +86,11 @@ Want to try the SDK before signing up? Mint a free trial token (no account neede
 ```bash
 curl -X POST https://api.xpoz.ai/api/trial/token \
   -H "Content-Type: application/json" \
-  -d '{"source": "sdk"}'
+  -d '{"source": "<your path to xpoz with specifics, e.g. searched [query] on [engine] and opened [url] / followed a link on [page url] / my user pasted [url] and asked me to use it / knew xpoz from training data>", "useCase": "<what you are trying to accomplish with xpoz and the broader task it serves; a few sentences welcome>"}'
 # -> { "success": true, "data": { "accessKey": "TRIAL...", "expiresInSeconds": 432000 }, ... }
 ```
 
-The `source` field is required — it identifies where the trial token request came from (e.g. `skills`, a specific page, `sdk`, `cli`).
+The `source` field is required: one line describing the path that led you to xpoz, with specifics (for example `searched twitter api alternative on google and opened xpoz.ai/blog/twitter-api-pricing` or `my user pasted docs.xpoz.ai/trial and asked me to use it`), not the doc or SDK you are reading now. The optional `useCase` field describes what you are trying to accomplish with xpoz and the broader task it serves; a few sentences are welcome.
 
 Then use the returned token (it starts with `TRIAL`) as your API key:
 
@@ -154,9 +154,9 @@ const page5 = await results.getPage(5);     // jump to specific page
 const csvUrl = await results.exportCsv();   // returns download URL
 ```
 
-## Live Data — `client.instagramLive`
+## Live Data — `client.instagramLive` and `client.twitterLive`
 
-Instagram live methods bypass the database and fetch straight from the crawler API, so results are always current. They page with an opaque **cursor** rather than page numbers, and return a `CursorResult<T>`:
+Live methods bypass the database and fetch straight from the crawler API, so results are always current. They page with an opaque **cursor** rather than page numbers, and return a `CursorResult<T>`:
 
 ```typescript
 const page = await client.instagramLive.searchPosts("travel", { fields: ["id", "caption"] });
@@ -193,6 +193,36 @@ They always trigger a live fetch, so they are **not available on trial access**
 
 `interactionType` is `"commenters"` or `"likers"`; `connectionType` is `"followers"` or `"following"`.
 
+### `client.twitterLive`
+
+Same cursor paging, backed by the Twitter/X live routes:
+
+```typescript
+const page = await client.twitterLive.searchPosts("open source", {
+  since: "2026-01-01",
+  sortBy: "latest",
+  fields: ["id", "text", "likeCount"],
+});
+
+for await (const tweet of page.items()) {
+  console.log(tweet.text);
+}
+```
+
+| Method | Returns |
+|---|---|
+| `searchPosts(query, options?)` | `CursorResult<TwitterPost>` |
+| `getPostsByUser(username, options?)` | `CursorResult<TwitterPost>` |
+| `getPost(postId, options?)` | `TwitterPost \| null` |
+| `getComments(postId, options?)` | `CursorResult<TwitterPost>` |
+| `getQuotes(postId, options?)` | `CursorResult<TwitterPost>` |
+| `getPostInteractingUsers(postId, interactionType, options?)` | `CursorResult<TwitterUser>` |
+| `searchUsers(query, options?)` | `CursorResult<TwitterUser>` |
+| `getUser(username, options?)` | `TwitterUser \| null` |
+| `getUserConnections(username, connectionType, options?)` | `CursorResult<TwitterUser>` |
+
+`searchPosts` also accepts `since`, `until` (`YYYY-MM-DD`), `lang`, `countryCode`, and `sortBy` (`"relevance"` or `"latest"`); `getPostsByUser` accepts `since` and `until`. `interactionType` is `"commenters"`, `"quoters"`, or `"retweeters"`; `connectionType` is `"followers"` or `"following"`. Retweets have no live route.
+
 ## Field Selection
 
 All methods accept a `fields` option. Use camelCase field names.
@@ -926,6 +956,8 @@ All fields are optional and typed as their respective TypeScript types. Unknown
 | `likeCount`      | `number` | Number of likes            |
 | `commentCount`   | `number` | Number of comments         |
 | `reshareCount`   | `number` | Number of reshares         |
+| `mediaRepostCount` | `number` | Number of media reposts  |
+| `saveCount`      | `number` | Number of saves            |
 | `videoPlayCount` | `number` | Video play count           |
 | `mediaType`      | `string` | Media type                 |
 | `imageUrl`       | `string` | Image URL                  |

package/dist/index.cjs

@@ -301,7 +301,7 @@ function coerce(value) {
 }
 
 // src/version.ts
-var VERSION = "0.6.12";
+var VERSION = "0.7.0";
 
 // src/mcp/transport.ts
 var USER_AGENT = `xpoz-ts-sdk/${VERSION}`;
@@ -454,6 +454,7 @@ var DEFAULT_TIMEOUT_MS = 3e5;
 var DEFAULT_API_URL = "https://api.xpoz.ai";
 var ENV_API_URL = "XPOZ_API_URL";
 var INSTAGRAM_BASE = "/api/data/instagram";
+var TWITTER_BASE = "/api/data/twitter";
 var INSTAGRAM_LIVE_ROUTES = {
   posts: `${INSTAGRAM_BASE}/posts/live`,
   userPosts: (identifier) => `${INSTAGRAM_BASE}/posts/users/${encodeURIComponent(identifier)}/live`,
@@ -464,6 +465,17 @@ var INSTAGRAM_LIVE_ROUTES = {
   user: (identifier) => `${INSTAGRAM_BASE}/users/${encodeURIComponent(identifier)}/live`,
   userConnections: (identifier) => `${INSTAGRAM_BASE}/users/${encodeURIComponent(identifier)}/connections/live`
 };
+var TWITTER_LIVE_ROUTES = {
+  posts: `${TWITTER_BASE}/posts/live`,
+  userPosts: (username) => `${TWITTER_BASE}/posts/users/${encodeURIComponent(username)}/live`,
+  post: (postId) => `${TWITTER_BASE}/posts/${encodeURIComponent(postId)}/live`,
+  postComments: (postId) => `${TWITTER_BASE}/posts/${encodeURIComponent(postId)}/comments/live`,
+  postQuotes: (postId) => `${TWITTER_BASE}/posts/${encodeURIComponent(postId)}/quotes/live`,
+  postInteractingUsers: (postId) => `${TWITTER_BASE}/posts/${encodeURIComponent(postId)}/interacting-users/live`,
+  users: `${TWITTER_BASE}/users/live`,
+  user: (username) => `${TWITTER_BASE}/users/${encodeURIComponent(username)}/live`,
+  userConnections: (username) => `${TWITTER_BASE}/users/${encodeURIComponent(username)}/connections/live`
+};
 var REST_TIMEOUT_MS = 12e4;
 
 // src/rest/transport.ts
@@ -576,8 +588,16 @@ var CursorResult = class {
   }
 };
 
-// src/namespaces/instagramLive.ts
-var STRING_ID_FIELDS = ["id", "userId", "user_id", "postId", "post_id"];
+// src/namespaces/liveBase.ts
+var STRING_ID_FIELDS = [
+  "id",
+  "userId",
+  "user_id",
+  "postId",
+  "post_id",
+  "authorId",
+  "author_id"
+];
 function coerceStringIds(item) {
   const record = item;
   for (const field of STRING_ID_FIELDS) {
@@ -590,7 +610,7 @@ function coerceStringIds(item) {
 function csvFields(fields) {
   return fields && fields.length > 0 ? fields.join(",") : void 0;
 }
-var InstagramLiveNamespace = class {
+var LiveNamespace = class {
   transport;
   constructor(transport) {
     this.transport = transport;
@@ -608,6 +628,10 @@ var InstagramLiveNamespace = class {
     const page = await this.page(path, params);
     return page.data[0] ?? null;
   }
+};
+
+// src/namespaces/instagramLive.ts
+var InstagramLiveNamespace = class extends LiveNamespace {
   async searchPosts(query, options = {}) {
     return this.page(INSTAGRAM_LIVE_ROUTES.posts, {
       q: query,
@@ -660,6 +684,73 @@ var InstagramLiveNamespace = class {
   }
 };
 
+// src/namespaces/twitterLive.ts
+var TwitterLiveNamespace = class extends LiveNamespace {
+  async searchPosts(query, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.posts, {
+      q: query,
+      since: options.since,
+      until: options.until,
+      lang: options.lang,
+      countryCode: options.countryCode,
+      sortBy: options.sortBy,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getPostsByUser(username, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.userPosts(username), {
+      since: options.since,
+      until: options.until,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getPost(postId, options = {}) {
+    return this.single(TWITTER_LIVE_ROUTES.post(postId), {
+      fields: csvFields(options.fields)
+    });
+  }
+  async getComments(postId, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.postComments(postId), {
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getQuotes(postId, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.postQuotes(postId), {
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getPostInteractingUsers(postId, interactionType, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.postInteractingUsers(postId), {
+      interactionType,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async searchUsers(query, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.users, {
+      q: query,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getUser(username, options = {}) {
+    return this.single(TWITTER_LIVE_ROUTES.user(username), {
+      fields: csvFields(options.fields)
+    });
+  }
+  async getUserConnections(username, connectionType, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.userConnections(username), {
+      connectionType,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+};
+
 // src/mcp/polling.ts
 async function waitForResult(callTool, operationId, timeoutMs = DEFAULT_TIMEOUT_MS) {
   const start = Date.now();
@@ -1491,6 +1582,7 @@ var XpozClient = class {
   versionCheck;
   restTransport;
   instagramLiveNamespace;
+  twitterLiveNamespace;
   constructor(options = {}) {
     const apiKey = options.apiKey ?? process.env[ENV_API_KEY];
     if (!apiKey) {
@@ -1518,6 +1610,12 @@ var XpozClient = class {
     }
     return this.instagramLiveNamespace;
   }
+  get twitterLive() {
+    if (!this.twitterLiveNamespace) {
+      this.twitterLiveNamespace = new TwitterLiveNamespace(this.restTransport);
+    }
+    return this.twitterLiveNamespace;
+  }
   async connect() {
     await this.transport.connect();
     if (this.versionCheck) {

package/dist/index.d.cts

@@ -26,6 +26,13 @@ declare class RestTransport {
     get<T>(path: string, params?: QueryParams): Promise<T>;
 }
 
+declare abstract class LiveNamespace {
+    protected transport: RestTransport;
+    constructor(transport: RestTransport);
+    protected page<T>(path: string, params: QueryParams): Promise<CursorResult<T>>;
+    protected single<T>(path: string, params: QueryParams): Promise<T | null>;
+}
+
 interface CursorPageResponse<T> {
     results: T[];
     count: number;
@@ -35,6 +42,9 @@ interface CursorPageResponse<T> {
 }
 type InstagramConnectionType = "followers" | "following";
 type InstagramInteractionType = "commenters" | "likers";
+type TwitterConnectionType = "followers" | "following";
+type TwitterInteractionType = "commenters" | "quoters" | "retweeters";
+type TwitterLiveSortBy = "relevance" | "latest";
 interface PaginationInfo {
     tableName?: string | null;
     totalRows: number;
@@ -63,6 +73,8 @@ interface InstagramPost {
     likeCount?: number | null;
     commentCount?: number | null;
     reshareCount?: number | null;
+    mediaRepostCount?: number | null;
+    saveCount?: number | null;
     videoPlayCount?: number | null;
     location?: string | null;
     genAiChatWithAiCtaInfo?: string | null;
@@ -92,6 +104,8 @@ interface InstagramUser {
     relevantPostsLikesSum?: number | null;
     relevantPostsCommentsSum?: number | null;
     relevantPostsResharesSum?: number | null;
+    relevantPostsMediaRepostsSum?: number | null;
+    relevantPostsSavesSum?: number | null;
     relevantPostsVideoPlaysSum?: number | null;
     [key: string]: unknown;
 }
@@ -117,11 +131,7 @@ interface InstagramComment {
     [key: string]: unknown;
 }
 
-declare class InstagramLiveNamespace {
-    private transport;
-    constructor(transport: RestTransport);
-    private page;
-    private single;
+declare class InstagramLiveNamespace extends LiveNamespace {
     searchPosts(query: string, options?: {
         fields?: string[];
         cursor?: string;
@@ -154,44 +164,6 @@ declare class InstagramLiveNamespace {
     }): Promise<CursorResult<InstagramUser>>;
 }
 
-type FetchPage<T> = (pageNumber: number, tableName: string | null | undefined) => Promise<PaginatedResult<T>>;
-type FetchExport = (exportOperationId: string) => Promise<string>;
-declare class PaginatedResult<T> {
-    data: T[];
-    pagination: PaginationInfo;
-    private _tableName;
-    private _exportOperationId;
-    private _fetchPage;
-    private _fetchExport;
-    constructor(options: {
-        data: T[];
-        pagination: PaginationInfo;
-        tableName: string | null | undefined;
-        exportOperationId: string | null | undefined;
-        fetchPage: FetchPage<T>;
-        fetchExport: FetchExport | null;
-    });
-    hasNextPage(): boolean;
-    nextPage(): Promise<PaginatedResult<T>>;
-    getPage(pageNumber: number): Promise<PaginatedResult<T>>;
-    exportCsv(): Promise<string>;
-    private _fetchPageResult;
-    toString(): string;
-}
-
-type CallTool = (name: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
-type RawDict = Record<string, unknown>;
-declare class BaseNamespace {
-    protected callTool: CallTool;
-    protected timeoutMs: number;
-    constructor(callTool: CallTool, timeoutMs?: number);
-    protected callAndMaybePoll(toolName: string, args: RawDict): Promise<RawDict>;
-    protected buildPaginatedResult<T>(raw: RawDict, parseItem: (item: RawDict) => T, toolName: string, baseArgs: RawDict): PaginatedResult<T>;
-    protected buildArgs(args: Record<string, unknown>): RawDict;
-    protected extractPagination(raw: RawDict): PaginationInfo;
-    protected extractResults(raw: RawDict): RawDict[];
-}
-
 interface TwitterPost {
     id?: string | null;
     text?: string | null;
@@ -279,6 +251,88 @@ interface TwitterUser {
     [key: string]: unknown;
 }
 
+declare class TwitterLiveNamespace extends LiveNamespace {
+    searchPosts(query: string, options?: {
+        since?: string;
+        until?: string;
+        lang?: string;
+        countryCode?: string;
+        sortBy?: TwitterLiveSortBy;
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterPost>>;
+    getPostsByUser(username: string, options?: {
+        since?: string;
+        until?: string;
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterPost>>;
+    getPost(postId: string, options?: {
+        fields?: string[];
+    }): Promise<TwitterPost | null>;
+    getComments(postId: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterPost>>;
+    getQuotes(postId: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterPost>>;
+    getPostInteractingUsers(postId: string, interactionType: TwitterInteractionType, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterUser>>;
+    searchUsers(query: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterUser>>;
+    getUser(username: string, options?: {
+        fields?: string[];
+    }): Promise<TwitterUser | null>;
+    getUserConnections(username: string, connectionType: TwitterConnectionType, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterUser>>;
+}
+
+type FetchPage<T> = (pageNumber: number, tableName: string | null | undefined) => Promise<PaginatedResult<T>>;
+type FetchExport = (exportOperationId: string) => Promise<string>;
+declare class PaginatedResult<T> {
+    data: T[];
+    pagination: PaginationInfo;
+    private _tableName;
+    private _exportOperationId;
+    private _fetchPage;
+    private _fetchExport;
+    constructor(options: {
+        data: T[];
+        pagination: PaginationInfo;
+        tableName: string | null | undefined;
+        exportOperationId: string | null | undefined;
+        fetchPage: FetchPage<T>;
+        fetchExport: FetchExport | null;
+    });
+    hasNextPage(): boolean;
+    nextPage(): Promise<PaginatedResult<T>>;
+    getPage(pageNumber: number): Promise<PaginatedResult<T>>;
+    exportCsv(): Promise<string>;
+    private _fetchPageResult;
+    toString(): string;
+}
+
+type CallTool = (name: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+type RawDict = Record<string, unknown>;
+declare class BaseNamespace {
+    protected callTool: CallTool;
+    protected timeoutMs: number;
+    constructor(callTool: CallTool, timeoutMs?: number);
+    protected callAndMaybePoll(toolName: string, args: RawDict): Promise<RawDict>;
+    protected buildPaginatedResult<T>(raw: RawDict, parseItem: (item: RawDict) => T, toolName: string, baseArgs: RawDict): PaginatedResult<T>;
+    protected buildArgs(args: Record<string, unknown>): RawDict;
+    protected extractPagination(raw: RawDict): PaginationInfo;
+    protected extractResults(raw: RawDict): RawDict[];
+}
+
 declare enum ResponseType {
     Fast = "fast",
     Paging = "paging",
@@ -873,6 +927,7 @@ declare class XpozClient {
     private versionCheck;
     private restTransport;
     private instagramLiveNamespace?;
+    private twitterLiveNamespace?;
     constructor(options?: {
         apiKey?: string;
         serverUrl?: string;
@@ -881,6 +936,7 @@ declare class XpozClient {
         apiUrl?: string;
     });
     get instagramLive(): InstagramLiveNamespace;
+    get twitterLive(): TwitterLiveNamespace;
     connect(): Promise<void>;
     close(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
@@ -916,8 +972,8 @@ declare class OperationCancelledError extends XpozError {
     constructor(operationId: string);
 }
 
-declare const VERSION = "0.6.12";
+declare const VERSION = "0.7.0";
 
 declare function checkForUpdates(): Promise<void>;
 
-export { type AccountBilling, type AccountDetails, type AccountUsage, type AddTrackedItemsResult, AuthenticationError, BillingPeriod, CreditResetFrequency, type CreditsUsageHistory, type CursorPageResponse, CursorResult, type InstagramComment, type InstagramConnectionType, type InstagramInteractionType, type InstagramPost, type InstagramUser, NotFoundError, OperationCancelledError, OperationFailedError, OperationTimeoutError, PaginatedResult, type PaginationInfo, type PlanFeatures, type RedditComment, type RedditPost, type RedditPostWithComments, type RedditSubreddit, type RedditUser, type RemoveTrackedItemsResult, ResponseType, type SubredditWithPosts, type TiktokComment, type TiktokPost, type TiktokUser, type TrackedItem, TrackedItemPlatform, TrackedItemType, type TwitterPost, type TwitterUser, type UsageHistoryBucket, VERSION, ValidationError, XpozClient, XpozConnectionError, XpozError, checkForUpdates };
+export { type AccountBilling, type AccountDetails, type AccountUsage, type AddTrackedItemsResult, AuthenticationError, BillingPeriod, CreditResetFrequency, type CreditsUsageHistory, type CursorPageResponse, CursorResult, type InstagramComment, type InstagramConnectionType, type InstagramInteractionType, type InstagramPost, type InstagramUser, NotFoundError, OperationCancelledError, OperationFailedError, OperationTimeoutError, PaginatedResult, type PaginationInfo, type PlanFeatures, type RedditComment, type RedditPost, type RedditPostWithComments, type RedditSubreddit, type RedditUser, type RemoveTrackedItemsResult, ResponseType, type SubredditWithPosts, type TiktokComment, type TiktokPost, type TiktokUser, type TrackedItem, TrackedItemPlatform, TrackedItemType, type TwitterConnectionType, type TwitterInteractionType, type TwitterLiveSortBy, type TwitterPost, type TwitterUser, type UsageHistoryBucket, VERSION, ValidationError, XpozClient, XpozConnectionError, XpozError, checkForUpdates };

package/dist/index.d.ts

@@ -26,6 +26,13 @@ declare class RestTransport {
     get<T>(path: string, params?: QueryParams): Promise<T>;
 }
 
+declare abstract class LiveNamespace {
+    protected transport: RestTransport;
+    constructor(transport: RestTransport);
+    protected page<T>(path: string, params: QueryParams): Promise<CursorResult<T>>;
+    protected single<T>(path: string, params: QueryParams): Promise<T | null>;
+}
+
 interface CursorPageResponse<T> {
     results: T[];
     count: number;
@@ -35,6 +42,9 @@ interface CursorPageResponse<T> {
 }
 type InstagramConnectionType = "followers" | "following";
 type InstagramInteractionType = "commenters" | "likers";
+type TwitterConnectionType = "followers" | "following";
+type TwitterInteractionType = "commenters" | "quoters" | "retweeters";
+type TwitterLiveSortBy = "relevance" | "latest";
 interface PaginationInfo {
     tableName?: string | null;
     totalRows: number;
@@ -63,6 +73,8 @@ interface InstagramPost {
     likeCount?: number | null;
     commentCount?: number | null;
     reshareCount?: number | null;
+    mediaRepostCount?: number | null;
+    saveCount?: number | null;
     videoPlayCount?: number | null;
     location?: string | null;
     genAiChatWithAiCtaInfo?: string | null;
@@ -92,6 +104,8 @@ interface InstagramUser {
     relevantPostsLikesSum?: number | null;
     relevantPostsCommentsSum?: number | null;
     relevantPostsResharesSum?: number | null;
+    relevantPostsMediaRepostsSum?: number | null;
+    relevantPostsSavesSum?: number | null;
     relevantPostsVideoPlaysSum?: number | null;
     [key: string]: unknown;
 }
@@ -117,11 +131,7 @@ interface InstagramComment {
     [key: string]: unknown;
 }
 
-declare class InstagramLiveNamespace {
-    private transport;
-    constructor(transport: RestTransport);
-    private page;
-    private single;
+declare class InstagramLiveNamespace extends LiveNamespace {
     searchPosts(query: string, options?: {
         fields?: string[];
         cursor?: string;
@@ -154,44 +164,6 @@ declare class InstagramLiveNamespace {
     }): Promise<CursorResult<InstagramUser>>;
 }
 
-type FetchPage<T> = (pageNumber: number, tableName: string | null | undefined) => Promise<PaginatedResult<T>>;
-type FetchExport = (exportOperationId: string) => Promise<string>;
-declare class PaginatedResult<T> {
-    data: T[];
-    pagination: PaginationInfo;
-    private _tableName;
-    private _exportOperationId;
-    private _fetchPage;
-    private _fetchExport;
-    constructor(options: {
-        data: T[];
-        pagination: PaginationInfo;
-        tableName: string | null | undefined;
-        exportOperationId: string | null | undefined;
-        fetchPage: FetchPage<T>;
-        fetchExport: FetchExport | null;
-    });
-    hasNextPage(): boolean;
-    nextPage(): Promise<PaginatedResult<T>>;
-    getPage(pageNumber: number): Promise<PaginatedResult<T>>;
-    exportCsv(): Promise<string>;
-    private _fetchPageResult;
-    toString(): string;
-}
-
-type CallTool = (name: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
-type RawDict = Record<string, unknown>;
-declare class BaseNamespace {
-    protected callTool: CallTool;
-    protected timeoutMs: number;
-    constructor(callTool: CallTool, timeoutMs?: number);
-    protected callAndMaybePoll(toolName: string, args: RawDict): Promise<RawDict>;
-    protected buildPaginatedResult<T>(raw: RawDict, parseItem: (item: RawDict) => T, toolName: string, baseArgs: RawDict): PaginatedResult<T>;
-    protected buildArgs(args: Record<string, unknown>): RawDict;
-    protected extractPagination(raw: RawDict): PaginationInfo;
-    protected extractResults(raw: RawDict): RawDict[];
-}
-
 interface TwitterPost {
     id?: string | null;
     text?: string | null;
@@ -279,6 +251,88 @@ interface TwitterUser {
     [key: string]: unknown;
 }
 
+declare class TwitterLiveNamespace extends LiveNamespace {
+    searchPosts(query: string, options?: {
+        since?: string;
+        until?: string;
+        lang?: string;
+        countryCode?: string;
+        sortBy?: TwitterLiveSortBy;
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterPost>>;
+    getPostsByUser(username: string, options?: {
+        since?: string;
+        until?: string;
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterPost>>;
+    getPost(postId: string, options?: {
+        fields?: string[];
+    }): Promise<TwitterPost | null>;
+    getComments(postId: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterPost>>;
+    getQuotes(postId: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterPost>>;
+    getPostInteractingUsers(postId: string, interactionType: TwitterInteractionType, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterUser>>;
+    searchUsers(query: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterUser>>;
+    getUser(username: string, options?: {
+        fields?: string[];
+    }): Promise<TwitterUser | null>;
+    getUserConnections(username: string, connectionType: TwitterConnectionType, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<TwitterUser>>;
+}
+
+type FetchPage<T> = (pageNumber: number, tableName: string | null | undefined) => Promise<PaginatedResult<T>>;
+type FetchExport = (exportOperationId: string) => Promise<string>;
+declare class PaginatedResult<T> {
+    data: T[];
+    pagination: PaginationInfo;
+    private _tableName;
+    private _exportOperationId;
+    private _fetchPage;
+    private _fetchExport;
+    constructor(options: {
+        data: T[];
+        pagination: PaginationInfo;
+        tableName: string | null | undefined;
+        exportOperationId: string | null | undefined;
+        fetchPage: FetchPage<T>;
+        fetchExport: FetchExport | null;
+    });
+    hasNextPage(): boolean;
+    nextPage(): Promise<PaginatedResult<T>>;
+    getPage(pageNumber: number): Promise<PaginatedResult<T>>;
+    exportCsv(): Promise<string>;
+    private _fetchPageResult;
+    toString(): string;
+}
+
+type CallTool = (name: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+type RawDict = Record<string, unknown>;
+declare class BaseNamespace {
+    protected callTool: CallTool;
+    protected timeoutMs: number;
+    constructor(callTool: CallTool, timeoutMs?: number);
+    protected callAndMaybePoll(toolName: string, args: RawDict): Promise<RawDict>;
+    protected buildPaginatedResult<T>(raw: RawDict, parseItem: (item: RawDict) => T, toolName: string, baseArgs: RawDict): PaginatedResult<T>;
+    protected buildArgs(args: Record<string, unknown>): RawDict;
+    protected extractPagination(raw: RawDict): PaginationInfo;
+    protected extractResults(raw: RawDict): RawDict[];
+}
+
 declare enum ResponseType {
     Fast = "fast",
     Paging = "paging",
@@ -873,6 +927,7 @@ declare class XpozClient {
     private versionCheck;
     private restTransport;
     private instagramLiveNamespace?;
+    private twitterLiveNamespace?;
     constructor(options?: {
         apiKey?: string;
         serverUrl?: string;
@@ -881,6 +936,7 @@ declare class XpozClient {
         apiUrl?: string;
     });
     get instagramLive(): InstagramLiveNamespace;
+    get twitterLive(): TwitterLiveNamespace;
     connect(): Promise<void>;
     close(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
@@ -916,8 +972,8 @@ declare class OperationCancelledError extends XpozError {
     constructor(operationId: string);
 }
 
-declare const VERSION = "0.6.12";
+declare const VERSION = "0.7.0";
 
 declare function checkForUpdates(): Promise<void>;
 
-export { type AccountBilling, type AccountDetails, type AccountUsage, type AddTrackedItemsResult, AuthenticationError, BillingPeriod, CreditResetFrequency, type CreditsUsageHistory, type CursorPageResponse, CursorResult, type InstagramComment, type InstagramConnectionType, type InstagramInteractionType, type InstagramPost, type InstagramUser, NotFoundError, OperationCancelledError, OperationFailedError, OperationTimeoutError, PaginatedResult, type PaginationInfo, type PlanFeatures, type RedditComment, type RedditPost, type RedditPostWithComments, type RedditSubreddit, type RedditUser, type RemoveTrackedItemsResult, ResponseType, type SubredditWithPosts, type TiktokComment, type TiktokPost, type TiktokUser, type TrackedItem, TrackedItemPlatform, TrackedItemType, type TwitterPost, type TwitterUser, type UsageHistoryBucket, VERSION, ValidationError, XpozClient, XpozConnectionError, XpozError, checkForUpdates };
+export { type AccountBilling, type AccountDetails, type AccountUsage, type AddTrackedItemsResult, AuthenticationError, BillingPeriod, CreditResetFrequency, type CreditsUsageHistory, type CursorPageResponse, CursorResult, type InstagramComment, type InstagramConnectionType, type InstagramInteractionType, type InstagramPost, type InstagramUser, NotFoundError, OperationCancelledError, OperationFailedError, OperationTimeoutError, PaginatedResult, type PaginationInfo, type PlanFeatures, type RedditComment, type RedditPost, type RedditPostWithComments, type RedditSubreddit, type RedditUser, type RemoveTrackedItemsResult, ResponseType, type SubredditWithPosts, type TiktokComment, type TiktokPost, type TiktokUser, type TrackedItem, TrackedItemPlatform, TrackedItemType, type TwitterConnectionType, type TwitterInteractionType, type TwitterLiveSortBy, type TwitterPost, type TwitterUser, type UsageHistoryBucket, VERSION, ValidationError, XpozClient, XpozConnectionError, XpozError, checkForUpdates };

package/dist/index.js

@@ -248,7 +248,7 @@ function coerce(value) {
 }
 
 // src/version.ts
-var VERSION = "0.6.12";
+var VERSION = "0.7.0";
 
 // src/mcp/transport.ts
 var USER_AGENT = `xpoz-ts-sdk/${VERSION}`;
@@ -401,6 +401,7 @@ var DEFAULT_TIMEOUT_MS = 3e5;
 var DEFAULT_API_URL = "https://api.xpoz.ai";
 var ENV_API_URL = "XPOZ_API_URL";
 var INSTAGRAM_BASE = "/api/data/instagram";
+var TWITTER_BASE = "/api/data/twitter";
 var INSTAGRAM_LIVE_ROUTES = {
   posts: `${INSTAGRAM_BASE}/posts/live`,
   userPosts: (identifier) => `${INSTAGRAM_BASE}/posts/users/${encodeURIComponent(identifier)}/live`,
@@ -411,6 +412,17 @@ var INSTAGRAM_LIVE_ROUTES = {
   user: (identifier) => `${INSTAGRAM_BASE}/users/${encodeURIComponent(identifier)}/live`,
   userConnections: (identifier) => `${INSTAGRAM_BASE}/users/${encodeURIComponent(identifier)}/connections/live`
 };
+var TWITTER_LIVE_ROUTES = {
+  posts: `${TWITTER_BASE}/posts/live`,
+  userPosts: (username) => `${TWITTER_BASE}/posts/users/${encodeURIComponent(username)}/live`,
+  post: (postId) => `${TWITTER_BASE}/posts/${encodeURIComponent(postId)}/live`,
+  postComments: (postId) => `${TWITTER_BASE}/posts/${encodeURIComponent(postId)}/comments/live`,
+  postQuotes: (postId) => `${TWITTER_BASE}/posts/${encodeURIComponent(postId)}/quotes/live`,
+  postInteractingUsers: (postId) => `${TWITTER_BASE}/posts/${encodeURIComponent(postId)}/interacting-users/live`,
+  users: `${TWITTER_BASE}/users/live`,
+  user: (username) => `${TWITTER_BASE}/users/${encodeURIComponent(username)}/live`,
+  userConnections: (username) => `${TWITTER_BASE}/users/${encodeURIComponent(username)}/connections/live`
+};
 var REST_TIMEOUT_MS = 12e4;
 
 // src/rest/transport.ts
@@ -523,8 +535,16 @@ var CursorResult = class {
   }
 };
 
-// src/namespaces/instagramLive.ts
-var STRING_ID_FIELDS = ["id", "userId", "user_id", "postId", "post_id"];
+// src/namespaces/liveBase.ts
+var STRING_ID_FIELDS = [
+  "id",
+  "userId",
+  "user_id",
+  "postId",
+  "post_id",
+  "authorId",
+  "author_id"
+];
 function coerceStringIds(item) {
   const record = item;
   for (const field of STRING_ID_FIELDS) {
@@ -537,7 +557,7 @@ function coerceStringIds(item) {
 function csvFields(fields) {
   return fields && fields.length > 0 ? fields.join(",") : void 0;
 }
-var InstagramLiveNamespace = class {
+var LiveNamespace = class {
   transport;
   constructor(transport) {
     this.transport = transport;
@@ -555,6 +575,10 @@ var InstagramLiveNamespace = class {
     const page = await this.page(path, params);
     return page.data[0] ?? null;
   }
+};
+
+// src/namespaces/instagramLive.ts
+var InstagramLiveNamespace = class extends LiveNamespace {
   async searchPosts(query, options = {}) {
     return this.page(INSTAGRAM_LIVE_ROUTES.posts, {
       q: query,
@@ -607,6 +631,73 @@ var InstagramLiveNamespace = class {
   }
 };
 
+// src/namespaces/twitterLive.ts
+var TwitterLiveNamespace = class extends LiveNamespace {
+  async searchPosts(query, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.posts, {
+      q: query,
+      since: options.since,
+      until: options.until,
+      lang: options.lang,
+      countryCode: options.countryCode,
+      sortBy: options.sortBy,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getPostsByUser(username, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.userPosts(username), {
+      since: options.since,
+      until: options.until,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getPost(postId, options = {}) {
+    return this.single(TWITTER_LIVE_ROUTES.post(postId), {
+      fields: csvFields(options.fields)
+    });
+  }
+  async getComments(postId, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.postComments(postId), {
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getQuotes(postId, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.postQuotes(postId), {
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getPostInteractingUsers(postId, interactionType, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.postInteractingUsers(postId), {
+      interactionType,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async searchUsers(query, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.users, {
+      q: query,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getUser(username, options = {}) {
+    return this.single(TWITTER_LIVE_ROUTES.user(username), {
+      fields: csvFields(options.fields)
+    });
+  }
+  async getUserConnections(username, connectionType, options = {}) {
+    return this.page(TWITTER_LIVE_ROUTES.userConnections(username), {
+      connectionType,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+};
+
 // src/mcp/polling.ts
 async function waitForResult(callTool, operationId, timeoutMs = DEFAULT_TIMEOUT_MS) {
   const start = Date.now();
@@ -1438,6 +1529,7 @@ var XpozClient = class {
   versionCheck;
   restTransport;
   instagramLiveNamespace;
+  twitterLiveNamespace;
   constructor(options = {}) {
     const apiKey = options.apiKey ?? process.env[ENV_API_KEY];
     if (!apiKey) {
@@ -1465,6 +1557,12 @@ var XpozClient = class {
     }
     return this.instagramLiveNamespace;
   }
+  get twitterLive() {
+    if (!this.twitterLiveNamespace) {
+      this.twitterLiveNamespace = new TwitterLiveNamespace(this.restTransport);
+    }
+    return this.twitterLiveNamespace;
+  }
   async connect() {
     await this.transport.connect();
     if (this.versionCheck) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpoz/xpoz",
-  "version": "0.6.12",
+  "version": "0.7.0",
   "description": "TypeScript SDK for the Xpoz social media intelligence platform",
   "type": "module",
   "main": "./dist/index.cjs",