@xpoz/xpoz 0.1.0 → 0.2.1

package/README.md

@@ -1,11 +1,13 @@
 # Xpoz TypeScript SDK
 
+[![npm version](https://img.shields.io/npm/v/@xpoz/xpoz)](https://www.npmjs.com/package/@xpoz/xpoz)
+
 TypeScript SDK for the [Xpoz](https://xpoz.ai) social media intelligence platform. Query Twitter/X, Instagram, and Reddit data through a simple, typed interface.
 
 ## Installation
 
 ```bash
-npm install xpoz
+npm install @xpoz/xpoz
 ```
 
 Requires Node.js 18+.
@@ -31,6 +33,7 @@ The SDK wraps Xpoz's [MCP](https://modelcontextprotocol.io) server, abstracting
 - **30 data methods** across Twitter, Instagram, and Reddit
 - **Fully async** — all methods return `Promise<T>`
 - **Automatic operation polling** — long-running queries are abstracted away
+- **Response types** — choose between fast (immediate), paging (full pagination), or CSV export
 - **Server-side pagination** — `PaginatedResult<T>` with `nextPage()`, `getPage(n)`
 - **CSV export** — `exportCsv()` on any paginated result
 - **Field selection** — request only the fields you need
@@ -40,7 +43,7 @@ The SDK wraps Xpoz's [MCP](https://modelcontextprotocol.io) server, abstracting
 ## Quick Start
 
 ```typescript
-import { XpozClient } from "xpoz";
+import { XpozClient, ResponseType } from "@xpoz/xpoz";
 
 const client = new XpozClient({ apiKey: "your-api-key" });
 await client.connect();
@@ -135,6 +138,73 @@ const user = await client.twitter.getUser("elonmusk", {
 
 Requesting fewer fields significantly improves response time.
 
+## Response Types
+
+Search and query methods support a `responseType` option that controls how results are returned. Import the `ResponseType` enum:
+
+```typescript
+import { XpozClient, ResponseType } from "@xpoz/xpoz";
+```
+
+| Mode | Enum Value | Behavior | Best For |
+| --- | --- | --- | --- |
+| **Fast** | `ResponseType.Fast` | Returns up to 300 results immediately, no async polling (default) | Quick queries, UI previews |
+| **Paging** | `ResponseType.Paging` | Async paginated query with full dataset access | Full analysis, large datasets |
+| **CSV** | `ResponseType.Csv` | Async bulk export, use `exportCsv()` to get download URL | Data exports |
+
+### Fast mode (default)
+
+The default behavior. Returns results immediately without polling. Use `limit` to constrain the number of results (max 300):
+
+```typescript
+const results = await client.twitter.searchPosts("bitcoin", {
+  startDate: "2025-01-01",
+  responseType: ResponseType.Fast,
+  limit: 50,
+});
+console.log(results.data.length); // up to 50 results, returned immediately
+```
+
+### Paging mode
+
+Returns paginated results with full `totalRows`, `totalPages`, and `tableName` for cursor-based navigation:
+
+```typescript
+const results = await client.twitter.searchPosts("bitcoin", {
+  startDate: "2025-01-01",
+  responseType: ResponseType.Paging, // optional — this is the default
+});
+console.log(results.pagination.totalRows);  // total matching rows
+if (results.hasNextPage()) {
+  const page2 = await results.nextPage();
+}
+```
+
+### CSV mode
+
+Initiates an async export. Call `exportCsv()` on the result to poll the export operation and get a download URL:
+
+```typescript
+const results = await client.twitter.searchPosts("bitcoin", {
+  startDate: "2025-01-01",
+  responseType: ResponseType.Csv,
+});
+const downloadUrl = await results.exportCsv();
+console.log(downloadUrl); // URL to download the CSV file
+```
+
+### Methods supporting `responseType` and `limit`
+
+The following methods accept both `responseType` and `limit`:
+
+- `twitter.getPostsByAuthor()`, `twitter.searchPosts()`, `twitter.getUsersByKeywords()`
+- `instagram.getPostsByUser()`, `instagram.searchPosts()`, `instagram.getUsersByKeywords()`
+- `reddit.searchPosts()`
+
+These methods accept `limit` only:
+
+- `twitter.searchUsers()`, `instagram.searchUsers()`, `reddit.searchUsers()`, `reddit.searchSubreddits()`
+
 ## Query Syntax
 
 The `query` parameter on all `search*` and `get*ByKeywords` methods supports a Lucene-style full-text syntax across Twitter, Instagram, and Reddit.
@@ -189,7 +259,8 @@ import {
   OperationTimeoutError,
   OperationFailedError,
   OperationCancelledError,
-} from "xpoz";
+  ResponseType,
+} from "@xpoz/xpoz";
 
 try {
   const user = await client.twitter.getUser("nonexistent_user_12345");
@@ -226,10 +297,11 @@ const user = await client.twitter.getUser("44196397", { identifierType: "id" });
 
 #### `searchUsers(name, options?) -> Promise<TwitterUser[]>`
 
-Search users by name or username. Returns up to 10 results.
+Search users by name or username. Returns up to 10 results by default. Use `limit` to adjust.
 
 ```typescript
 const users = await client.twitter.searchUsers("elon");
+const topFive = await client.twitter.searchUsers("elon", { limit: 5 });
 ```
 
 #### `getUserConnections(username, connectionType, options?) -> Promise<PaginatedResult<TwitterUser>>`
@@ -243,11 +315,13 @@ const following = await client.twitter.getUserConnections("elonmusk", "following
 
 #### `getUsersByKeywords(query, options?) -> Promise<PaginatedResult<TwitterUser>>`
 
-Find users who authored posts matching a keyword query.
+Find users who authored posts matching a keyword query. Supports `responseType` and `limit`.
 
 ```typescript
 const users = await client.twitter.getUsersByKeywords('"machine learning"', {
   fields: ["username", "name", "followersCount"],
+  responseType: ResponseType.Fast,
+  limit: 20,
 });
 ```
 
@@ -261,17 +335,19 @@ const tweets = await client.twitter.getPostsByIds(["1234567890", "0987654321"]);
 
 #### `getPostsByAuthor(identifier, options?) -> Promise<PaginatedResult<TwitterPost>>`
 
-Get all posts by an author with optional date filtering.
+Get all posts by an author with optional date filtering. Supports `responseType` and `limit`.
 
 ```typescript
 const results = await client.twitter.getPostsByAuthor("elonmusk", {
   startDate: "2025-01-01",
+  responseType: ResponseType.Fast,
+  limit: 100,
 });
 ```
 
 #### `searchPosts(query, options?) -> Promise<PaginatedResult<TwitterPost>>`
 
-Full-text search with filters. Supports exact phrases (`"machine learning"`), boolean operators (`AI AND python`), and parentheses.
+Full-text search with filters. Supports exact phrases (`"machine learning"`), boolean operators (`AI AND python`), and parentheses. Supports `responseType` and `limit`.
 
 ```typescript
 const results = await client.twitter.searchPosts('"artificial intelligence" AND ethics', {
@@ -279,6 +355,8 @@ const results = await client.twitter.searchPosts('"artificial intelligence" AND
   endDate: "2025-06-01",
   language: "en",
   fields: ["id", "text", "likeCount", "authorUsername", "createdAtDate"],
+  responseType: ResponseType.Fast,
+  limit: 50,
 });
 ```
 
@@ -336,8 +414,11 @@ console.log(`${user.fullName} — ${user.followerCount?.toLocaleString()} follow
 
 #### `searchUsers(name, options?) -> Promise<InstagramUser[]>`
 
+Search users by name. Use `limit` to adjust the number of results.
+
 ```typescript
 const users = await client.instagram.searchUsers("nasa");
+const topThree = await client.instagram.searchUsers("nasa", { limit: 3 });
 ```
 
 #### `getUserConnections(username, connectionType, options?) -> Promise<PaginatedResult<InstagramUser>>`
@@ -348,8 +429,13 @@ const followers = await client.instagram.getUserConnections("instagram", "follow
 
 #### `getUsersByKeywords(query, options?) -> Promise<PaginatedResult<InstagramUser>>`
 
+Find users who authored posts matching a keyword query. Supports `responseType` and `limit`.
+
 ```typescript
-const users = await client.instagram.getUsersByKeywords('"sustainable fashion"');
+const users = await client.instagram.getUsersByKeywords('"sustainable fashion"', {
+  responseType: ResponseType.Fast,
+  limit: 20,
+});
 ```
 
 #### `getPostsByIds(postIds, options?) -> Promise<InstagramPost[]>`
@@ -362,14 +448,24 @@ const posts = await client.instagram.getPostsByIds(["3606450040306139062_4836333
 
 #### `getPostsByUser(identifier, options?) -> Promise<PaginatedResult<InstagramPost>>`
 
+Get all posts by a user. Supports `responseType` and `limit`.
+
 ```typescript
-const results = await client.instagram.getPostsByUser("nasa");
+const results = await client.instagram.getPostsByUser("nasa", {
+  responseType: ResponseType.Fast,
+  limit: 50,
+});
 ```
 
 #### `searchPosts(query, options?) -> Promise<PaginatedResult<InstagramPost>>`
 
+Full-text search with filters. Supports `responseType` and `limit`.
+
 ```typescript
-const results = await client.instagram.searchPosts("travel photography");
+const results = await client.instagram.searchPosts("travel photography", {
+  responseType: ResponseType.Fast,
+  limit: 30,
+});
 ```
 
 #### `getComments(postId, options?) -> Promise<PaginatedResult<InstagramComment>>`
@@ -402,8 +498,11 @@ console.log(`${user.username} — ${user.totalKarma?.toLocaleString()} karma`);
 
 #### `searchUsers(name, options?) -> Promise<RedditUser[]>`
 
+Search users by name. Use `limit` to adjust the number of results.
+
 ```typescript
 const users = await client.reddit.searchUsers("spez");
+const topThree = await client.reddit.searchUsers("spez", { limit: 3 });
 ```
 
 #### `getUsersByKeywords(query, options?) -> Promise<PaginatedResult<RedditUser>>`
@@ -416,13 +515,15 @@ const users = await client.reddit.getUsersByKeywords('"machine learning"', {
 
 #### `searchPosts(query, options?) -> Promise<PaginatedResult<RedditPost>>`
 
-`sort`: `"relevance"`, `"hot"`, `"top"`, `"new"`, `"comments"`. `time`: `"hour"`, `"day"`, `"week"`, `"month"`, `"year"`, `"all"`.
+`sort`: `"relevance"`, `"hot"`, `"top"`, `"new"`, `"comments"`. `time`: `"hour"`, `"day"`, `"week"`, `"month"`, `"year"`, `"all"`. Supports `responseType` and `limit`.
 
 ```typescript
 const results = await client.reddit.searchPosts("python tutorial", {
   subreddit: "learnpython",
   sort: "top",
   time: "month",
+  responseType: ResponseType.Fast,
+  limit: 25,
 });
 ```
 
@@ -448,8 +549,11 @@ const comments = await client.reddit.searchComments("helpful tip", {
 
 #### `searchSubreddits(query, options?) -> Promise<RedditSubreddit[]>`
 
+Search subreddits by name. Use `limit` to adjust the number of results.
+
 ```typescript
 const subs = await client.reddit.searchSubreddits("machine learning");
+const topFive = await client.reddit.searchSubreddits("machine learning", { limit: 5 });
 ```
 
 #### `getSubredditWithPosts(subredditName, options?) -> Promise<SubredditWithPosts>`
@@ -634,12 +738,14 @@ All fields are optional and typed as their respective TypeScript types. Unknown
 - `post: RedditPost`
 - `comments: RedditComment[]`
 - `commentsPagination: PaginationInfo | null`
+- `commentsTableName: string | null`
 
 **`SubredditWithPosts`** — returned by `getSubredditWithPosts()`:
 
 - `subreddit: RedditSubreddit`
 - `posts: RedditPost[]`
 - `postsPagination: PaginationInfo | null`
+- `postsTableName: string | null`
 
 ---
 

package/dist/index.cjs

@@ -25,10 +25,12 @@ __export(index_exports, {
   OperationFailedError: () => OperationFailedError,
   OperationTimeoutError: () => OperationTimeoutError,
   PaginatedResult: () => PaginatedResult,
+  ResponseType: () => ResponseType,
   VERSION: () => VERSION,
   XpozClient: () => XpozClient,
   XpozConnectionError: () => XpozConnectionError,
-  XpozError: () => XpozError
+  XpozError: () => XpozError,
+  checkForUpdates: () => checkForUpdates
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -282,7 +284,7 @@ function coerce(value) {
 }
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.1";
 
 // src/mcp/transport.ts
 var USER_AGENT = `xpoz-ts-sdk/${VERSION}`;
@@ -395,6 +397,12 @@ var OperationCancelledError = class extends XpozError {
 var DEFAULT_SERVER_URL = "https://mcp.xpoz.ai/mcp";
 var ENV_API_KEY = "XPOZ_API_KEY";
 var ENV_SERVER_URL = "XPOZ_SERVER_URL";
+var ResponseType = /* @__PURE__ */ ((ResponseType2) => {
+  ResponseType2["Fast"] = "fast";
+  ResponseType2["Paging"] = "paging";
+  ResponseType2["Csv"] = "csv";
+  return ResponseType2;
+})(ResponseType || {});
 var POLL_INTERVAL_MS = 5e3;
 var DEFAULT_TIMEOUT_MS = 3e5;
 
@@ -499,6 +507,9 @@ var BaseNamespace = class {
   }
   async callAndMaybePoll(toolName, args) {
     const result = await this.callTool(toolName, args);
+    if ("results" in result) {
+      return result;
+    }
     const operationId = result["operationId"];
     if (operationId) {
       return waitForResult(this.callTool, operationId, this.timeoutMs);
@@ -517,7 +528,11 @@ var BaseNamespace = class {
       return this.buildPaginatedResult(pageRaw, parseItem, toolName, baseArgs);
     };
     const fetchExport = async (opId) => {
-      const pollResult = await waitForResult(this.callTool, opId, this.timeoutMs);
+      const pollResult = await waitForResult(
+        this.callTool,
+        opId,
+        this.timeoutMs
+      );
       return pollResult["downloadUrl"] ?? "";
     };
     return new PaginatedResult({
@@ -593,12 +608,13 @@ var TwitterNamespace = class extends BaseNamespace {
   }
   async getPostsByAuthor(identifier, options = {}) {
     const args = this.buildArgs({
-      identifier,
-      identifierType: options.identifierType ?? "username",
+      username: identifier,
       fields: options.fields,
       startDate: options.startDate,
       endDate: options.endDate,
-      forceLatest: options.forceLatest
+      forceLatest: options.forceLatest,
+      responseType: options.responseType,
+      limit: options.limit
     });
     const result = await this.callAndMaybePoll(GET_TWITTER_POSTS_BY_AUTHOR, args);
     return this.buildPaginatedResult(result, parseTwitterPost, GET_TWITTER_POSTS_BY_AUTHOR, args);
@@ -613,9 +629,10 @@ var TwitterNamespace = class extends BaseNamespace {
       authorId: options.authorId,
       language: options.language,
       forceLatest: options.forceLatest,
-      responseType: options.responseType
+      responseType: options.responseType,
+      limit: options.limit
     });
-    if (options.responseType === "csv") {
+    if (options.responseType === "csv" /* Csv */) {
       const raw = await this.callTool(SEARCH_TWITTER_POSTS, args);
       const exportOpId = raw["operationId"] ?? raw["dataDumpExportOperationId"] ?? null;
       const csvRaw = { results: [], dataDumpExportOperationId: exportOpId };
@@ -726,7 +743,9 @@ var InstagramNamespace = class extends BaseNamespace {
       fields: options.fields,
       startDate: options.startDate,
       endDate: options.endDate,
-      forceLatest: options.forceLatest
+      forceLatest: options.forceLatest,
+      responseType: options.responseType,
+      limit: options.limit
     });
     const result = await this.callAndMaybePoll(GET_INSTAGRAM_POSTS_BY_USER, args);
     return this.buildPaginatedResult(
@@ -737,7 +756,15 @@ var InstagramNamespace = class extends BaseNamespace {
     );
   }
   async searchPosts(query, options = {}) {
-    const args = this.buildArgs({ query, ...options });
+    const args = this.buildArgs({
+      query,
+      fields: options.fields,
+      startDate: options.startDate,
+      endDate: options.endDate,
+      forceLatest: options.forceLatest,
+      responseType: options.responseType,
+      limit: options.limit
+    });
     const result = await this.callAndMaybePoll(SEARCH_INSTAGRAM_POSTS, args);
     return this.buildPaginatedResult(result, parsePost, SEARCH_INSTAGRAM_POSTS, args);
   }
@@ -904,12 +931,53 @@ var RedditNamespace = class extends BaseNamespace {
   }
 };
 
+// src/versionCheck.ts
+var NPM_REGISTRY_URL = "https://registry.npmjs.org/@xpoz/xpoz/latest";
+var CHECK_TIMEOUT_MS = 3e3;
+var PACKAGE_NAME = "@xpoz/xpoz";
+var hasWarned = false;
+async function checkForUpdates() {
+  if (hasWarned) return;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS);
+    const response = await fetch(NPM_REGISTRY_URL, {
+      signal: controller.signal,
+      headers: { Accept: "application/json" }
+    });
+    clearTimeout(timeout);
+    if (!response.ok) return;
+    const data = await response.json();
+    const latest = data.version;
+    if (!latest || latest === VERSION) return;
+    if (isNewerVersion(latest, VERSION)) {
+      hasWarned = true;
+      console.warn(
+        `[xpoz] A newer version of ${PACKAGE_NAME} is available: ${latest} (current: ${VERSION}). Run \`npm install ${PACKAGE_NAME}@latest\` to update.`
+      );
+    }
+  } catch {
+  }
+}
+function isNewerVersion(latestVersion, currentVersion) {
+  const latestVersionParts = latestVersion.split(".").map(Number);
+  const currentVersionParts = currentVersion.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const latestVersionPart = latestVersionParts[i] ?? 0;
+    const currentVersionPart = currentVersionParts[i] ?? 0;
+    if (latestVersionPart > currentVersionPart) return true;
+    if (latestVersionPart < currentVersionPart) return false;
+  }
+  return false;
+}
+
 // src/client.ts
 var XpozClient = class {
   twitter;
   instagram;
   reddit;
   transport;
+  versionCheck;
   constructor(options = {}) {
     const apiKey = options.apiKey ?? process.env[ENV_API_KEY];
     if (!apiKey) {
@@ -917,6 +985,7 @@ var XpozClient = class {
         `API key required. Get your token at http://xpoz.ai/get-token?utm_source=ts_sdk&utm_medium=sdk (login \u2192 copy token), then pass it as apiKey or set the ${ENV_API_KEY} environment variable.`
       );
     }
+    this.versionCheck = options.versionCheck ?? true;
     const serverUrl = options.serverUrl ?? process.env[ENV_SERVER_URL] ?? DEFAULT_SERVER_URL;
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.transport = new McpTransport(serverUrl, apiKey);
@@ -927,6 +996,9 @@ var XpozClient = class {
   }
   async connect() {
     await this.transport.connect();
+    if (this.versionCheck) {
+      checkForUpdates();
+    }
   }
   async close() {
     await this.transport.close();
@@ -942,8 +1014,10 @@ var XpozClient = class {
   OperationFailedError,
   OperationTimeoutError,
   PaginatedResult,
+  ResponseType,
   VERSION,
   XpozClient,
   XpozConnectionError,
-  XpozError
+  XpozError,
+  checkForUpdates
 });

package/dist/index.d.cts

@@ -144,17 +144,24 @@ interface TwitterUser {
     [key: string]: unknown;
 }
 
+declare enum ResponseType {
+    Fast = "fast",
+    Paging = "paging",
+    Csv = "csv"
+}
+
 declare class TwitterNamespace extends BaseNamespace {
     getPostsByIds(postIds: string[], options?: {
         fields?: string[];
         forceLatest?: boolean;
     }): Promise<TwitterPost[]>;
     getPostsByAuthor(identifier: string, options?: {
-        identifierType?: string;
         fields?: string[];
         startDate?: string;
         endDate?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<TwitterPost>>;
     searchPosts(query: string, options?: {
         fields?: string[];
@@ -164,7 +171,8 @@ declare class TwitterNamespace extends BaseNamespace {
         authorId?: string;
         language?: string;
         forceLatest?: boolean;
-        responseType?: string;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<TwitterPost>>;
     getRetweets(postId: string, options?: {
         fields?: string[];
@@ -206,6 +214,8 @@ declare class TwitterNamespace extends BaseNamespace {
         endDate?: string;
         language?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<TwitterUser>>;
 }
 
@@ -300,12 +310,16 @@ declare class InstagramNamespace extends BaseNamespace {
         startDate?: string;
         endDate?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<InstagramPost>>;
     searchPosts(query: string, options?: {
         fields?: string[];
         startDate?: string;
         endDate?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<InstagramPost>>;
     getComments(postId: string, options?: {
         fields?: string[];
@@ -334,6 +348,8 @@ declare class InstagramNamespace extends BaseNamespace {
         startDate?: string;
         endDate?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<InstagramUser>>;
 }
 
@@ -490,6 +506,8 @@ declare class RedditNamespace extends BaseNamespace {
         time?: string;
         subreddit?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<RedditPost>>;
     getPostWithComments(postId: string, options?: {
         postFields?: string[];
@@ -540,10 +558,12 @@ declare class XpozClient {
     instagram: InstagramNamespace;
     reddit: RedditNamespace;
     private transport;
+    private versionCheck;
     constructor(options?: {
         apiKey?: string;
         serverUrl?: string;
         timeoutMs?: number;
+        versionCheck?: boolean;
     });
     connect(): Promise<void>;
     close(): Promise<void>;
@@ -574,6 +594,8 @@ declare class OperationCancelledError extends XpozError {
     constructor(operationId: string);
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.2.1";
+
+declare function checkForUpdates(): Promise<void>;
 
-export { AuthenticationError, type InstagramComment, type InstagramPost, type InstagramUser, OperationCancelledError, OperationFailedError, OperationTimeoutError, PaginatedResult, type PaginationInfo, type RedditComment, type RedditPost, type RedditPostWithComments, type RedditSubreddit, type RedditUser, type SubredditWithPosts, type TwitterPost, type TwitterUser, VERSION, XpozClient, XpozConnectionError, XpozError };
+export { AuthenticationError, type InstagramComment, type InstagramPost, type InstagramUser, OperationCancelledError, OperationFailedError, OperationTimeoutError, PaginatedResult, type PaginationInfo, type RedditComment, type RedditPost, type RedditPostWithComments, type RedditSubreddit, type RedditUser, ResponseType, type SubredditWithPosts, type TwitterPost, type TwitterUser, VERSION, XpozClient, XpozConnectionError, XpozError, checkForUpdates };

package/dist/index.d.ts

@@ -144,17 +144,24 @@ interface TwitterUser {
     [key: string]: unknown;
 }
 
+declare enum ResponseType {
+    Fast = "fast",
+    Paging = "paging",
+    Csv = "csv"
+}
+
 declare class TwitterNamespace extends BaseNamespace {
     getPostsByIds(postIds: string[], options?: {
         fields?: string[];
         forceLatest?: boolean;
     }): Promise<TwitterPost[]>;
     getPostsByAuthor(identifier: string, options?: {
-        identifierType?: string;
         fields?: string[];
         startDate?: string;
         endDate?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<TwitterPost>>;
     searchPosts(query: string, options?: {
         fields?: string[];
@@ -164,7 +171,8 @@ declare class TwitterNamespace extends BaseNamespace {
         authorId?: string;
         language?: string;
         forceLatest?: boolean;
-        responseType?: string;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<TwitterPost>>;
     getRetweets(postId: string, options?: {
         fields?: string[];
@@ -206,6 +214,8 @@ declare class TwitterNamespace extends BaseNamespace {
         endDate?: string;
         language?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<TwitterUser>>;
 }
 
@@ -300,12 +310,16 @@ declare class InstagramNamespace extends BaseNamespace {
         startDate?: string;
         endDate?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<InstagramPost>>;
     searchPosts(query: string, options?: {
         fields?: string[];
         startDate?: string;
         endDate?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<InstagramPost>>;
     getComments(postId: string, options?: {
         fields?: string[];
@@ -334,6 +348,8 @@ declare class InstagramNamespace extends BaseNamespace {
         startDate?: string;
         endDate?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<InstagramUser>>;
 }
 
@@ -490,6 +506,8 @@ declare class RedditNamespace extends BaseNamespace {
         time?: string;
         subreddit?: string;
         forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
     }): Promise<PaginatedResult<RedditPost>>;
     getPostWithComments(postId: string, options?: {
         postFields?: string[];
@@ -540,10 +558,12 @@ declare class XpozClient {
     instagram: InstagramNamespace;
     reddit: RedditNamespace;
     private transport;
+    private versionCheck;
     constructor(options?: {
         apiKey?: string;
         serverUrl?: string;
         timeoutMs?: number;
+        versionCheck?: boolean;
     });
     connect(): Promise<void>;
     close(): Promise<void>;
@@ -574,6 +594,8 @@ declare class OperationCancelledError extends XpozError {
     constructor(operationId: string);
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION = "0.2.1";
+
+declare function checkForUpdates(): Promise<void>;
 
-export { AuthenticationError, type InstagramComment, type InstagramPost, type InstagramUser, OperationCancelledError, OperationFailedError, OperationTimeoutError, PaginatedResult, type PaginationInfo, type RedditComment, type RedditPost, type RedditPostWithComments, type RedditSubreddit, type RedditUser, type SubredditWithPosts, type TwitterPost, type TwitterUser, VERSION, XpozClient, XpozConnectionError, XpozError };
+export { AuthenticationError, type InstagramComment, type InstagramPost, type InstagramUser, OperationCancelledError, OperationFailedError, OperationTimeoutError, PaginatedResult, type PaginationInfo, type RedditComment, type RedditPost, type RedditPostWithComments, type RedditSubreddit, type RedditUser, ResponseType, type SubredditWithPosts, type TwitterPost, type TwitterUser, VERSION, XpozClient, XpozConnectionError, XpozError, checkForUpdates };

package/dist/index.js

@@ -248,7 +248,7 @@ function coerce(value) {
 }
 
 // src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.2.1";
 
 // src/mcp/transport.ts
 var USER_AGENT = `xpoz-ts-sdk/${VERSION}`;
@@ -361,6 +361,12 @@ var OperationCancelledError = class extends XpozError {
 var DEFAULT_SERVER_URL = "https://mcp.xpoz.ai/mcp";
 var ENV_API_KEY = "XPOZ_API_KEY";
 var ENV_SERVER_URL = "XPOZ_SERVER_URL";
+var ResponseType = /* @__PURE__ */ ((ResponseType2) => {
+  ResponseType2["Fast"] = "fast";
+  ResponseType2["Paging"] = "paging";
+  ResponseType2["Csv"] = "csv";
+  return ResponseType2;
+})(ResponseType || {});
 var POLL_INTERVAL_MS = 5e3;
 var DEFAULT_TIMEOUT_MS = 3e5;
 
@@ -465,6 +471,9 @@ var BaseNamespace = class {
   }
   async callAndMaybePoll(toolName, args) {
     const result = await this.callTool(toolName, args);
+    if ("results" in result) {
+      return result;
+    }
     const operationId = result["operationId"];
     if (operationId) {
       return waitForResult(this.callTool, operationId, this.timeoutMs);
@@ -483,7 +492,11 @@ var BaseNamespace = class {
       return this.buildPaginatedResult(pageRaw, parseItem, toolName, baseArgs);
     };
     const fetchExport = async (opId) => {
-      const pollResult = await waitForResult(this.callTool, opId, this.timeoutMs);
+      const pollResult = await waitForResult(
+        this.callTool,
+        opId,
+        this.timeoutMs
+      );
       return pollResult["downloadUrl"] ?? "";
     };
     return new PaginatedResult({
@@ -559,12 +572,13 @@ var TwitterNamespace = class extends BaseNamespace {
   }
   async getPostsByAuthor(identifier, options = {}) {
     const args = this.buildArgs({
-      identifier,
-      identifierType: options.identifierType ?? "username",
+      username: identifier,
       fields: options.fields,
       startDate: options.startDate,
       endDate: options.endDate,
-      forceLatest: options.forceLatest
+      forceLatest: options.forceLatest,
+      responseType: options.responseType,
+      limit: options.limit
     });
     const result = await this.callAndMaybePoll(GET_TWITTER_POSTS_BY_AUTHOR, args);
     return this.buildPaginatedResult(result, parseTwitterPost, GET_TWITTER_POSTS_BY_AUTHOR, args);
@@ -579,9 +593,10 @@ var TwitterNamespace = class extends BaseNamespace {
       authorId: options.authorId,
       language: options.language,
       forceLatest: options.forceLatest,
-      responseType: options.responseType
+      responseType: options.responseType,
+      limit: options.limit
     });
-    if (options.responseType === "csv") {
+    if (options.responseType === "csv" /* Csv */) {
       const raw = await this.callTool(SEARCH_TWITTER_POSTS, args);
       const exportOpId = raw["operationId"] ?? raw["dataDumpExportOperationId"] ?? null;
       const csvRaw = { results: [], dataDumpExportOperationId: exportOpId };
@@ -692,7 +707,9 @@ var InstagramNamespace = class extends BaseNamespace {
       fields: options.fields,
       startDate: options.startDate,
       endDate: options.endDate,
-      forceLatest: options.forceLatest
+      forceLatest: options.forceLatest,
+      responseType: options.responseType,
+      limit: options.limit
     });
     const result = await this.callAndMaybePoll(GET_INSTAGRAM_POSTS_BY_USER, args);
     return this.buildPaginatedResult(
@@ -703,7 +720,15 @@ var InstagramNamespace = class extends BaseNamespace {
     );
   }
   async searchPosts(query, options = {}) {
-    const args = this.buildArgs({ query, ...options });
+    const args = this.buildArgs({
+      query,
+      fields: options.fields,
+      startDate: options.startDate,
+      endDate: options.endDate,
+      forceLatest: options.forceLatest,
+      responseType: options.responseType,
+      limit: options.limit
+    });
     const result = await this.callAndMaybePoll(SEARCH_INSTAGRAM_POSTS, args);
     return this.buildPaginatedResult(result, parsePost, SEARCH_INSTAGRAM_POSTS, args);
   }
@@ -870,12 +895,53 @@ var RedditNamespace = class extends BaseNamespace {
   }
 };
 
+// src/versionCheck.ts
+var NPM_REGISTRY_URL = "https://registry.npmjs.org/@xpoz/xpoz/latest";
+var CHECK_TIMEOUT_MS = 3e3;
+var PACKAGE_NAME = "@xpoz/xpoz";
+var hasWarned = false;
+async function checkForUpdates() {
+  if (hasWarned) return;
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), CHECK_TIMEOUT_MS);
+    const response = await fetch(NPM_REGISTRY_URL, {
+      signal: controller.signal,
+      headers: { Accept: "application/json" }
+    });
+    clearTimeout(timeout);
+    if (!response.ok) return;
+    const data = await response.json();
+    const latest = data.version;
+    if (!latest || latest === VERSION) return;
+    if (isNewerVersion(latest, VERSION)) {
+      hasWarned = true;
+      console.warn(
+        `[xpoz] A newer version of ${PACKAGE_NAME} is available: ${latest} (current: ${VERSION}). Run \`npm install ${PACKAGE_NAME}@latest\` to update.`
+      );
+    }
+  } catch {
+  }
+}
+function isNewerVersion(latestVersion, currentVersion) {
+  const latestVersionParts = latestVersion.split(".").map(Number);
+  const currentVersionParts = currentVersion.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    const latestVersionPart = latestVersionParts[i] ?? 0;
+    const currentVersionPart = currentVersionParts[i] ?? 0;
+    if (latestVersionPart > currentVersionPart) return true;
+    if (latestVersionPart < currentVersionPart) return false;
+  }
+  return false;
+}
+
 // src/client.ts
 var XpozClient = class {
   twitter;
   instagram;
   reddit;
   transport;
+  versionCheck;
   constructor(options = {}) {
     const apiKey = options.apiKey ?? process.env[ENV_API_KEY];
     if (!apiKey) {
@@ -883,6 +949,7 @@ var XpozClient = class {
         `API key required. Get your token at http://xpoz.ai/get-token?utm_source=ts_sdk&utm_medium=sdk (login \u2192 copy token), then pass it as apiKey or set the ${ENV_API_KEY} environment variable.`
       );
     }
+    this.versionCheck = options.versionCheck ?? true;
     const serverUrl = options.serverUrl ?? process.env[ENV_SERVER_URL] ?? DEFAULT_SERVER_URL;
     const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     this.transport = new McpTransport(serverUrl, apiKey);
@@ -893,6 +960,9 @@ var XpozClient = class {
   }
   async connect() {
     await this.transport.connect();
+    if (this.versionCheck) {
+      checkForUpdates();
+    }
   }
   async close() {
     await this.transport.close();
@@ -907,8 +977,10 @@ export {
   OperationFailedError,
   OperationTimeoutError,
   PaginatedResult,
+  ResponseType,
   VERSION,
   XpozClient,
   XpozConnectionError,
-  XpozError
+  XpozError,
+  checkForUpdates
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpoz/xpoz",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "TypeScript SDK for the Xpoz social media intelligence platform",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -43,5 +43,14 @@
     "url": "https://github.com/XPOZpublic/xpoz-ts-sdk/issues"
   },
   "license": "MIT",
-  "keywords": ["xpoz", "social-media", "twitter", "instagram", "reddit", "sdk", "mcp", "api"]
+  "keywords": [
+    "xpoz",
+    "social-media",
+    "twitter",
+    "instagram",
+    "reddit",
+    "sdk",
+    "mcp",
+    "api"
+  ]
 }