@xpoz/xpoz 0.6.10 → 0.6.12

package/README.md

@@ -2,7 +2,7 @@
 
 [![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.
+TypeScript SDK for the [Xpoz](https://xpoz.ai) social media intelligence platform. Query Twitter/X, Instagram, Reddit, and TikTok data through a simple, typed interface.
 
 ## Installation
 
@@ -24,7 +24,7 @@ export XPOZ_API_KEY=your-token-here
 
 ## What is Xpoz?
 
-Xpoz provides unified access to social media data across Twitter/X, Instagram, and Reddit. The platform indexes billions of posts, user profiles, and engagement metrics — making it possible to search, analyze, and export social media data at scale.
+Xpoz provides unified access to social media data across Twitter/X, Instagram, Reddit, and TikTok. The platform indexes billions of posts, user profiles, and engagement metrics — making it possible to search, analyze, and export social media data at scale.
 
 The SDK wraps Xpoz's [MCP](https://modelcontextprotocol.io) server, abstracting away transport, authentication, operation polling, and pagination into a clean developer-friendly API.
 
@@ -154,6 +154,45 @@ const page5 = await results.getPage(5);     // jump to specific page
 const csvUrl = await results.exportCsv();   // returns download URL
 ```
 
+## Live Data — `client.instagramLive`
+
+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>`:
+
+```typescript
+const page = await client.instagramLive.searchPosts("travel", { fields: ["id", "caption"] });
+
+page.data;             // InstagramPost[] — this page
+page.hasMore;          // another page is available upstream
+page.nextPageCursor;   // opaque token for the next call
+page.hasNextPage();    // boolean
+
+const next = await page.nextPage();
+
+// Walk every page
+for await (const post of page.items()) {
+  console.log(post.id);
+}
+```
+
+Cursor paging is forward-only: there is no `getPage(n)`, `totalPages`, or `totalRows`, because the upstream API does not report them. Drive iteration off `hasMore` and the cursor — never off the item count, since a page can be short or empty while `hasMore` is still true.
+
+These routes talk to the Xpoz REST API rather than the MCP server, so **`connect()` is not required** to use them. Override the base URL with `new XpozClient({ apiUrl })` or the `XPOZ_API_URL` environment variable.
+
+They always trigger a live fetch, so they are **not available on trial access** and throw `AuthenticationError` (HTTP 403).
+
+| Method | Returns |
+|---|---|
+| `searchPosts(query, options?)` | `CursorResult<InstagramPost>` |
+| `getPostsByUser(identifier, options?)` | `CursorResult<InstagramPost>` |
+| `getPost(postId, options?)` | `InstagramPost \| null` |
+| `getComments(postId, options?)` | `CursorResult<InstagramComment>` |
+| `getPostInteractingUsers(postId, interactionType, options?)` | `CursorResult<InstagramUser>` |
+| `searchUsers(name, options?)` | `CursorResult<InstagramUser>` |
+| `getUser(identifier, options?)` | `InstagramUser \| null` |
+| `getUserConnections(identifier, connectionType, options?)` | `CursorResult<InstagramUser>` |
+
+`interactionType` is `"commenters"` or `"likers"`; `connectionType` is `"followers"` or `"following"`.
+
 ## Field Selection
 
 All methods accept a `fields` option. Use camelCase field names.
@@ -582,6 +621,16 @@ const comments = await client.reddit.searchComments("helpful tip", {
 });
 ```
 
+#### `getCommentById(commentId, options?) -> Promise<RedditComment>`
+
+Fetch a single Reddit comment by its id (bare base36 or `t1_`-prefixed). Database-first with live API fallback when the comment is missing or stale.
+
+```typescript
+const comment = await client.reddit.getCommentById("laz1ytq", {
+  fields: ["id", "body", "rank", "removal"],
+});
+```
+
 #### `searchSubreddits(query, options?) -> Promise<RedditSubreddit[]>`
 
 Search subreddits by name. Use `limit` to adjust the number of results.
@@ -797,6 +846,19 @@ for (const bucket of history.credits) {
 
 All fields are optional and typed as their respective TypeScript types. Unknown fields are preserved on the object.
 
+> **Date fields.** Post models expose up to three creation-time fields whose
+> runtime formats differ from what their names suggest:
+>
+> - `createdAt` — full ISO 8601 datetime on Twitter; epoch **seconds** on
+>   Reddit/Instagram/TikTok.
+> - `createdAtTimestamp` — full ISO 8601 datetime (Reddit/Instagram/TikTok;
+>   not returned for Twitter).
+> - `createdAtDate` — the creation **date only**, rendered as ISO midnight
+>   (`2026-07-20T00:00:00.000Z`); it carries no real time-of-day.
+>
+> Depending on response quoting, values can arrive as strings or numbers —
+> treat all three as `string | number`.
+
 ### TwitterPost
 
 | Field               | Type       | Description                |
@@ -816,9 +878,13 @@ All fields are optional and typed as their respective TypeScript types. Unknown
 | `mentions`          | `string[]` | Mentioned usernames        |
 | `mediaUrls`         | `string[]` | Media attachment URLs      |
 | `urls`              | `string[]` | URLs in tweet text         |
-| `country`           | `string`   | Country (if geo-tagged)    |
-| `createdAt`         | `string`   | Creation timestamp         |
-| `createdAtDate`     | `string`   | Creation date (YYYY-MM-DD) |
+| `placeName`         | `string`   | Tagged place name          |
+| `placeCountry`      | `string`   | Tagged place country       |
+| `placeCountryCode`  | `string`   | Tagged place country code (ISO 3166-1 alpha-2) |
+| `placeBoundingBoxCoordinates` | `unknown` | Tagged place bounding box  |
+| `placeCentroid`     | `unknown`  | Tagged place centroid      |
+| `createdAt`         | `string \| number` | Creation datetime (ISO 8601) |
+| `createdAtDate`     | `string \| number` | Creation date (ISO midnight, no time-of-day) |
 | `conversationId`    | `string`   | Thread conversation ID     |
 | `quotedTweetId`     | `string`   | ID of quoted tweet         |
 | `replyToTweetId`    | `string`   | ID of parent tweet         |
@@ -864,7 +930,9 @@ All fields are optional and typed as their respective TypeScript types. Unknown
 | `mediaType`      | `string` | Media type                 |
 | `imageUrl`       | `string` | Image URL                  |
 | `videoUrl`                          | `string`  | Video URL                         |
-| `createdAtDate`                     | `string`  | Creation date                     |
+| `createdAt`                         | `string \| number` | Creation time (epoch seconds)     |
+| `createdAtTimestamp`                | `string \| number` | Creation datetime (ISO 8601)      |
+| `createdAtDate`                     | `string \| number` | Creation date (ISO midnight, no time-of-day) |
 | `genAiChatWithAiCtaInfo`            | `string`  | Gen AI chat CTA info              |
 | `hasHighRiskGenAiInformTreatment`   | `boolean` | High risk Gen AI treatment flag   |
 
@@ -911,7 +979,9 @@ All fields are optional and typed as their respective TypeScript types. Unknown
 | `permalink`      | `string`  | Reddit permalink      |
 | `isSelf`         | `boolean` | Self post (text only) |
 | `over18`         | `boolean` | NSFW flag             |
-| `createdAtDate`  | `string`  | Creation date         |
+| `createdAt`      | `string \| number` | Creation time (epoch seconds) |
+| `createdAtTimestamp` | `string \| number` | Creation datetime (ISO 8601) |
+| `createdAtDate`  | `string \| number` | Creation date (ISO midnight, no time-of-day) |
 
 ### RedditUser
 
@@ -976,8 +1046,9 @@ All fields are optional and typed as their respective TypeScript types. Unknown
 | `hashtags`                   | `string[]` | Hashtags in the post        |
 | `postType`                   | `number`  | Post type code               |
 | `isPrivate`                  | `boolean` | Private post flag            |
-| `createdAt`                  | `string`  | Creation timestamp           |
-| `createdAtDate`              | `string`  | Creation date (YYYY-MM-DD)   |
+| `createdAt`                  | `string \| number` | Creation time (epoch seconds) |
+| `createdAtTimestamp`         | `string \| number` | Creation datetime (ISO 8601)  |
+| `createdAtDate`              | `string \| number` | Creation date (ISO midnight, no time-of-day) |
 
 ### TiktokUser
 

package/dist/index.cjs

@@ -33,6 +33,8 @@ __export(index_exports, {
   AuthenticationError: () => AuthenticationError,
   BillingPeriod: () => BillingPeriod,
   CreditResetFrequency: () => CreditResetFrequency,
+  CursorResult: () => CursorResult,
+  NotFoundError: () => NotFoundError,
   OperationCancelledError: () => OperationCancelledError,
   OperationFailedError: () => OperationFailedError,
   OperationTimeoutError: () => OperationTimeoutError,
@@ -41,6 +43,7 @@ __export(index_exports, {
   TrackedItemPlatform: () => TrackedItemPlatform,
   TrackedItemType: () => TrackedItemType,
   VERSION: () => VERSION,
+  ValidationError: () => ValidationError,
   XpozClient: () => XpozClient,
   XpozConnectionError: () => XpozConnectionError,
   XpozError: () => XpozError,
@@ -298,7 +301,7 @@ function coerce(value) {
 }
 
 // src/version.ts
-var VERSION = "0.6.10";
+var VERSION = "0.6.12";
 
 // src/mcp/transport.ts
 var USER_AGENT = `xpoz-ts-sdk/${VERSION}`;
@@ -393,6 +396,18 @@ var XpozConnectionError = class extends XpozError {
     this.name = "XpozConnectionError";
   }
 };
+var NotFoundError = class extends XpozError {
+  constructor(message) {
+    super(message);
+    this.name = "NotFoundError";
+  }
+};
+var ValidationError = class extends XpozError {
+  constructor(message) {
+    super(message);
+    this.name = "ValidationError";
+  }
+};
 var OperationTimeoutError = class extends XpozError {
   operationId;
   elapsedMs;
@@ -435,6 +450,216 @@ var ResponseType = /* @__PURE__ */ ((ResponseType2) => {
 var POLL_INTERVAL_MS = 5e3;
 var DEFAULT_TIMEOUT_MS = 3e5;
 
+// src/config/routes.ts
+var DEFAULT_API_URL = "https://api.xpoz.ai";
+var ENV_API_URL = "XPOZ_API_URL";
+var INSTAGRAM_BASE = "/api/data/instagram";
+var INSTAGRAM_LIVE_ROUTES = {
+  posts: `${INSTAGRAM_BASE}/posts/live`,
+  userPosts: (identifier) => `${INSTAGRAM_BASE}/posts/users/${encodeURIComponent(identifier)}/live`,
+  post: (postId) => `${INSTAGRAM_BASE}/posts/${encodeURIComponent(postId)}/live`,
+  postComments: (postId) => `${INSTAGRAM_BASE}/posts/${encodeURIComponent(postId)}/comments/live`,
+  postInteractingUsers: (postId) => `${INSTAGRAM_BASE}/posts/${encodeURIComponent(postId)}/interacting-users/live`,
+  users: `${INSTAGRAM_BASE}/users/live`,
+  user: (identifier) => `${INSTAGRAM_BASE}/users/${encodeURIComponent(identifier)}/live`,
+  userConnections: (identifier) => `${INSTAGRAM_BASE}/users/${encodeURIComponent(identifier)}/connections/live`
+};
+var REST_TIMEOUT_MS = 12e4;
+
+// src/rest/transport.ts
+var USER_AGENT2 = `xpoz-ts-sdk/${VERSION}`;
+function buildQuery(params) {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0 && value !== null && value !== "") {
+      search.append(key, String(value));
+    }
+  }
+  const query = search.toString();
+  return query ? `?${query}` : "";
+}
+async function extractErrorMessage(response) {
+  try {
+    const body = await response.json();
+    const message = body.error ?? body.message;
+    return typeof message === "string" ? message : response.statusText;
+  } catch {
+    return response.statusText;
+  }
+}
+async function raiseForStatus(response) {
+  if (response.ok) {
+    return;
+  }
+  const message = await extractErrorMessage(response);
+  if (response.status === 401 || response.status === 403) {
+    throw new AuthenticationError(message);
+  }
+  if (response.status === 404) {
+    throw new NotFoundError(message);
+  }
+  if (response.status === 400) {
+    throw new ValidationError(message);
+  }
+  throw new XpozError(`HTTP ${response.status}: ${message}`);
+}
+var RestTransport = class {
+  baseUrl;
+  apiKey;
+  timeoutMs;
+  constructor(baseUrl, apiKey, timeoutMs = REST_TIMEOUT_MS) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
+    this.timeoutMs = timeoutMs;
+  }
+  async get(path, params = {}) {
+    const url = `${this.baseUrl}${path}${buildQuery(params)}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await fetch(url, {
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "User-Agent": USER_AGENT2,
+          Accept: "application/json"
+        },
+        signal: controller.signal
+      });
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new XpozConnectionError(reason);
+    } finally {
+      clearTimeout(timer);
+    }
+    await raiseForStatus(response);
+    return await response.json();
+  }
+};
+
+// src/cursor.ts
+var CursorResult = class {
+  data;
+  hasMore;
+  nextPageCursor;
+  _fetchPage;
+  constructor(options) {
+    this.data = options.data;
+    this.hasMore = options.hasMore;
+    this.nextPageCursor = options.nextPageCursor;
+    this._fetchPage = options.fetchPage;
+  }
+  hasNextPage() {
+    return this.hasMore && this.nextPageCursor !== null;
+  }
+  async nextPage() {
+    if (!this.hasNextPage()) {
+      throw new RangeError("No more pages available");
+    }
+    return this._fetchPage(this.nextPageCursor);
+  }
+  async *pages() {
+    let page = this;
+    yield page;
+    while (page.hasNextPage()) {
+      page = await page.nextPage();
+      yield page;
+    }
+  }
+  async *items() {
+    for await (const page of this.pages()) {
+      yield* page.data;
+    }
+  }
+  [Symbol.iterator]() {
+    return this.data[Symbol.iterator]();
+  }
+};
+
+// src/namespaces/instagramLive.ts
+var STRING_ID_FIELDS = ["id", "userId", "user_id", "postId", "post_id"];
+function coerceStringIds(item) {
+  const record = item;
+  for (const field of STRING_ID_FIELDS) {
+    if (typeof record[field] === "number") {
+      record[field] = String(record[field]);
+    }
+  }
+  return item;
+}
+function csvFields(fields) {
+  return fields && fields.length > 0 ? fields.join(",") : void 0;
+}
+var InstagramLiveNamespace = class {
+  transport;
+  constructor(transport) {
+    this.transport = transport;
+  }
+  async page(path, params) {
+    const payload = await this.transport.get(path, params);
+    return new CursorResult({
+      data: (payload.results ?? []).map(coerceStringIds),
+      hasMore: Boolean(payload.has_more),
+      nextPageCursor: payload.next_page_cursor ?? null,
+      fetchPage: (cursor) => this.page(path, { ...params, cursor })
+    });
+  }
+  async single(path, params) {
+    const page = await this.page(path, params);
+    return page.data[0] ?? null;
+  }
+  async searchPosts(query, options = {}) {
+    return this.page(INSTAGRAM_LIVE_ROUTES.posts, {
+      q: query,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getPostsByUser(identifier, options = {}) {
+    return this.page(INSTAGRAM_LIVE_ROUTES.userPosts(identifier), {
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getPost(postId, options = {}) {
+    return this.single(INSTAGRAM_LIVE_ROUTES.post(postId), {
+      fields: csvFields(options.fields)
+    });
+  }
+  async getComments(postId, options = {}) {
+    return this.page(INSTAGRAM_LIVE_ROUTES.postComments(postId), {
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getPostInteractingUsers(postId, interactionType, options = {}) {
+    return this.page(INSTAGRAM_LIVE_ROUTES.postInteractingUsers(postId), {
+      interactionType,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async searchUsers(name, options = {}) {
+    return this.page(INSTAGRAM_LIVE_ROUTES.users, {
+      name,
+      fields: csvFields(options.fields),
+      cursor: options.cursor
+    });
+  }
+  async getUser(identifier, options = {}) {
+    return this.single(INSTAGRAM_LIVE_ROUTES.user(identifier), {
+      fields: csvFields(options.fields)
+    });
+  }
+  async getUserConnections(identifier, connectionType, options = {}) {
+    return this.page(INSTAGRAM_LIVE_ROUTES.userConnections(identifier), {
+      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();
@@ -622,6 +847,7 @@ var GET_INSTAGRAM_USERS_BY_KEYWORDS = "getInstagramUsersByKeywords";
 var SEARCH_REDDIT_POSTS = "getRedditPostsByKeywords";
 var GET_REDDIT_POST_WITH_COMMENTS = "getRedditPostWithCommentsById";
 var SEARCH_REDDIT_COMMENTS = "getRedditCommentsByKeywords";
+var GET_REDDIT_COMMENT_BY_ID = "getRedditCommentById";
 var GET_REDDIT_USER = "getRedditUser";
 var SEARCH_REDDIT_USERS = "searchRedditUsers";
 var GET_REDDIT_USERS_BY_KEYWORDS = "getRedditUsersByKeywords";
@@ -980,6 +1206,15 @@ var RedditNamespace = class extends BaseNamespace {
     const result = await this.callAndMaybePoll(SEARCH_REDDIT_COMMENTS, args);
     return this.buildPaginatedResult(result, parseComment2, SEARCH_REDDIT_COMMENTS, args);
   }
+  async getCommentById(commentId, options = {}) {
+    const args = this.buildArgs({ commentId, ...options });
+    const result = await this.callAndMaybePoll(GET_REDDIT_COMMENT_BY_ID, args);
+    const results = result["results"];
+    if (Array.isArray(results) && results.length > 0) {
+      return results[0];
+    }
+    return result;
+  }
   async getUser(username, options = {}) {
     const args = this.buildArgs({ username, ...options });
     const result = await this.callAndMaybePoll(GET_REDDIT_USER, args);
@@ -1254,6 +1489,8 @@ var XpozClient = class {
   account;
   transport;
   versionCheck;
+  restTransport;
+  instagramLiveNamespace;
   constructor(options = {}) {
     const apiKey = options.apiKey ?? process.env[ENV_API_KEY];
     if (!apiKey) {
@@ -1265,6 +1502,8 @@ var XpozClient = class {
     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);
+    const apiUrl = options.apiUrl ?? process.env[ENV_API_URL] ?? DEFAULT_API_URL;
+    this.restTransport = new RestTransport(apiUrl, apiKey);
     const callTool = this.transport.callTool.bind(this.transport);
     this.twitter = new TwitterNamespace(callTool, timeoutMs);
     this.instagram = new InstagramNamespace(callTool, timeoutMs);
@@ -1273,6 +1512,12 @@ var XpozClient = class {
     this.tracking = new TrackingNamespace(callTool, timeoutMs);
     this.account = new AccountNamespace(callTool, timeoutMs);
   }
+  get instagramLive() {
+    if (!this.instagramLiveNamespace) {
+      this.instagramLiveNamespace = new InstagramLiveNamespace(this.restTransport);
+    }
+    return this.instagramLiveNamespace;
+  }
   async connect() {
     await this.transport.connect();
     if (this.versionCheck) {
@@ -1319,6 +1564,8 @@ var CreditResetFrequency = /* @__PURE__ */ ((CreditResetFrequency2) => {
   AuthenticationError,
   BillingPeriod,
   CreditResetFrequency,
+  CursorResult,
+  NotFoundError,
   OperationCancelledError,
   OperationFailedError,
   OperationTimeoutError,
@@ -1327,6 +1574,7 @@ var CreditResetFrequency = /* @__PURE__ */ ((CreditResetFrequency2) => {
   TrackedItemPlatform,
   TrackedItemType,
   VERSION,
+  ValidationError,
   XpozClient,
   XpozConnectionError,
   XpozError,