@xpoz/xpoz 0.6.11 → 0.6.13

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,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.

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.11";
+var VERSION = "0.6.13";
 
 // 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();
@@ -1264,6 +1489,8 @@ var XpozClient = class {
   account;
   transport;
   versionCheck;
+  restTransport;
+  instagramLiveNamespace;
   constructor(options = {}) {
     const apiKey = options.apiKey ?? process.env[ENV_API_KEY];
     if (!apiKey) {
@@ -1275,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);
@@ -1283,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) {
@@ -1329,6 +1564,8 @@ var CreditResetFrequency = /* @__PURE__ */ ((CreditResetFrequency2) => {
   AuthenticationError,
   BillingPeriod,
   CreditResetFrequency,
+  CursorResult,
+  NotFoundError,
   OperationCancelledError,
   OperationFailedError,
   OperationTimeoutError,
@@ -1337,6 +1574,7 @@ var CreditResetFrequency = /* @__PURE__ */ ((CreditResetFrequency2) => {
   TrackedItemPlatform,
   TrackedItemType,
   VERSION,
+  ValidationError,
   XpozClient,
   XpozConnectionError,
   XpozError,

package/dist/index.d.cts

@@ -1,3 +1,40 @@
+type FetchPage$1<T> = (cursor: string) => Promise<CursorResult<T>>;
+declare class CursorResult<T> {
+    data: T[];
+    hasMore: boolean;
+    nextPageCursor: string | null;
+    private _fetchPage;
+    constructor(options: {
+        data: T[];
+        hasMore: boolean;
+        nextPageCursor: string | null;
+        fetchPage: FetchPage$1<T>;
+    });
+    hasNextPage(): boolean;
+    nextPage(): Promise<CursorResult<T>>;
+    pages(): AsyncGenerator<CursorResult<T>>;
+    items(): AsyncGenerator<T>;
+    [Symbol.iterator](): Iterator<T>;
+}
+
+type QueryParams = Record<string, string | number | boolean | undefined | null>;
+declare class RestTransport {
+    private baseUrl;
+    private apiKey;
+    private timeoutMs;
+    constructor(baseUrl: string, apiKey: string, timeoutMs?: number);
+    get<T>(path: string, params?: QueryParams): Promise<T>;
+}
+
+interface CursorPageResponse<T> {
+    results: T[];
+    count: number;
+    dataSource?: string;
+    has_more: boolean;
+    next_page_cursor: string | null;
+}
+type InstagramConnectionType = "followers" | "following";
+type InstagramInteractionType = "commenters" | "likers";
 interface PaginationInfo {
     tableName?: string | null;
     totalRows: number;
@@ -7,6 +44,116 @@ interface PaginationInfo {
     resultsCount: number;
 }
 
+interface InstagramPost {
+    id?: string | null;
+    postType?: string | null;
+    userId?: string | null;
+    username?: string | null;
+    fullName?: string | null;
+    caption?: string | null;
+    mediaType?: string | null;
+    codeUrl?: string | null;
+    imageUrl?: string | null;
+    videoUrl?: string | null;
+    audioOnlyUrl?: string | null;
+    profilePicUrl?: string | null;
+    videoSubtitlesUri?: string | null;
+    subtitles?: string | null;
+    videoDuration?: number | null;
+    likeCount?: number | null;
+    commentCount?: number | null;
+    reshareCount?: number | null;
+    videoPlayCount?: number | null;
+    location?: string | null;
+    genAiChatWithAiCtaInfo?: string | null;
+    hasHighRiskGenAiInformTreatment?: boolean | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
+    [key: string]: unknown;
+}
+interface InstagramUser {
+    id?: string | null;
+    username?: string | null;
+    fullName?: string | null;
+    biography?: string | null;
+    isPrivate?: boolean | null;
+    isVerified?: boolean | null;
+    followerCount?: number | null;
+    followingCount?: number | null;
+    mediaCount?: number | null;
+    profilePicUrl?: string | null;
+    profilePicId?: string | null;
+    profileUrl?: string | null;
+    externalUrl?: string | null;
+    hasAnonymousProfilePicture?: boolean | null;
+    aggRelevance?: number | null;
+    relevantPostsCount?: number | null;
+    relevantPostsLikesSum?: number | null;
+    relevantPostsCommentsSum?: number | null;
+    relevantPostsResharesSum?: number | null;
+    relevantPostsVideoPlaysSum?: number | null;
+    [key: string]: unknown;
+}
+interface InstagramComment {
+    id?: string | null;
+    text?: string | null;
+    parentPostId?: string | null;
+    parentPostUserId?: string | null;
+    type?: string | null;
+    parentCommentId?: string | null;
+    repliedToCommentId?: string | null;
+    childCommentCount?: number | null;
+    userId?: string | null;
+    username?: string | null;
+    fullName?: string | null;
+    likeCount?: number | null;
+    status?: string | null;
+    isSpam?: boolean | null;
+    hasTranslation?: boolean | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
+    [key: string]: unknown;
+}
+
+declare class InstagramLiveNamespace {
+    private transport;
+    constructor(transport: RestTransport);
+    private page;
+    private single;
+    searchPosts(query: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<InstagramPost>>;
+    getPostsByUser(identifier: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<InstagramPost>>;
+    getPost(postId: string, options?: {
+        fields?: string[];
+    }): Promise<InstagramPost | null>;
+    getComments(postId: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<InstagramComment>>;
+    getPostInteractingUsers(postId: string, interactionType: InstagramInteractionType, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<InstagramUser>>;
+    searchUsers(name: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<InstagramUser>>;
+    getUser(identifier: string, options?: {
+        fields?: string[];
+    }): Promise<InstagramUser | null>;
+    getUserConnections(identifier: string, connectionType: InstagramConnectionType, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): 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> {
@@ -216,79 +363,6 @@ declare class TwitterNamespace extends BaseNamespace {
     }): Promise<PaginatedResult<TwitterUser>>;
 }
 
-interface InstagramPost {
-    id?: string | null;
-    postType?: string | null;
-    userId?: string | null;
-    username?: string | null;
-    fullName?: string | null;
-    caption?: string | null;
-    mediaType?: string | null;
-    codeUrl?: string | null;
-    imageUrl?: string | null;
-    videoUrl?: string | null;
-    audioOnlyUrl?: string | null;
-    profilePicUrl?: string | null;
-    videoSubtitlesUri?: string | null;
-    subtitles?: string | null;
-    videoDuration?: number | null;
-    likeCount?: number | null;
-    commentCount?: number | null;
-    reshareCount?: number | null;
-    videoPlayCount?: number | null;
-    location?: string | null;
-    genAiChatWithAiCtaInfo?: string | null;
-    hasHighRiskGenAiInformTreatment?: boolean | null;
-    createdAt?: string | number | null;
-    createdAtTimestamp?: string | number | null;
-    createdAtDate?: string | number | null;
-    [key: string]: unknown;
-}
-interface InstagramUser {
-    id?: string | null;
-    username?: string | null;
-    fullName?: string | null;
-    biography?: string | null;
-    isPrivate?: boolean | null;
-    isVerified?: boolean | null;
-    followerCount?: number | null;
-    followingCount?: number | null;
-    mediaCount?: number | null;
-    profilePicUrl?: string | null;
-    profilePicId?: string | null;
-    profileUrl?: string | null;
-    externalUrl?: string | null;
-    hasAnonymousProfilePicture?: boolean | null;
-    aggRelevance?: number | null;
-    relevantPostsCount?: number | null;
-    relevantPostsLikesSum?: number | null;
-    relevantPostsCommentsSum?: number | null;
-    relevantPostsResharesSum?: number | null;
-    relevantPostsVideoPlaysSum?: number | null;
-    [key: string]: unknown;
-}
-interface InstagramComment {
-    id?: string | null;
-    text?: string | null;
-    parentPostId?: string | null;
-    parentPostUserId?: string | null;
-    type?: string | null;
-    parentCommentId?: string | null;
-    repliedToCommentId?: string | null;
-    childCommentCount?: number | null;
-    userId?: string | null;
-    username?: string | null;
-    fullName?: string | null;
-    likeCount?: number | null;
-    status?: string | null;
-    isSpam?: boolean | null;
-    hasTranslation?: boolean | null;
-    createdAt?: string | number | null;
-    createdAtTimestamp?: string | number | null;
-    createdAtDate?: string | number | null;
-    [key: string]: unknown;
-}
-
 declare class InstagramNamespace extends BaseNamespace {
     getPostsByIds(postIds: string[], options?: {
         fields?: string[];
@@ -797,12 +871,16 @@ declare class XpozClient {
     account: AccountNamespace;
     private transport;
     private versionCheck;
+    private restTransport;
+    private instagramLiveNamespace?;
     constructor(options?: {
         apiKey?: string;
         serverUrl?: string;
         timeoutMs?: number;
         versionCheck?: boolean;
+        apiUrl?: string;
     });
+    get instagramLive(): InstagramLiveNamespace;
     connect(): Promise<void>;
     close(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
@@ -817,6 +895,12 @@ declare class AuthenticationError extends XpozError {
 declare class XpozConnectionError extends XpozError {
     constructor(message: string);
 }
+declare class NotFoundError extends XpozError {
+    constructor(message: string);
+}
+declare class ValidationError extends XpozError {
+    constructor(message: string);
+}
 declare class OperationTimeoutError extends XpozError {
     operationId: string;
     elapsedMs: number;
@@ -832,8 +916,8 @@ declare class OperationCancelledError extends XpozError {
     constructor(operationId: string);
 }
 
-declare const VERSION = "0.6.11";
+declare const VERSION = "0.6.13";
 
 declare function checkForUpdates(): Promise<void>;
 
-export { type AccountBilling, type AccountDetails, type AccountUsage, type AddTrackedItemsResult, AuthenticationError, BillingPeriod, CreditResetFrequency, type CreditsUsageHistory, type InstagramComment, type InstagramPost, type InstagramUser, 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, 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 TwitterPost, type TwitterUser, type UsageHistoryBucket, VERSION, ValidationError, XpozClient, XpozConnectionError, XpozError, checkForUpdates };

package/dist/index.d.ts

@@ -1,3 +1,40 @@
+type FetchPage$1<T> = (cursor: string) => Promise<CursorResult<T>>;
+declare class CursorResult<T> {
+    data: T[];
+    hasMore: boolean;
+    nextPageCursor: string | null;
+    private _fetchPage;
+    constructor(options: {
+        data: T[];
+        hasMore: boolean;
+        nextPageCursor: string | null;
+        fetchPage: FetchPage$1<T>;
+    });
+    hasNextPage(): boolean;
+    nextPage(): Promise<CursorResult<T>>;
+    pages(): AsyncGenerator<CursorResult<T>>;
+    items(): AsyncGenerator<T>;
+    [Symbol.iterator](): Iterator<T>;
+}
+
+type QueryParams = Record<string, string | number | boolean | undefined | null>;
+declare class RestTransport {
+    private baseUrl;
+    private apiKey;
+    private timeoutMs;
+    constructor(baseUrl: string, apiKey: string, timeoutMs?: number);
+    get<T>(path: string, params?: QueryParams): Promise<T>;
+}
+
+interface CursorPageResponse<T> {
+    results: T[];
+    count: number;
+    dataSource?: string;
+    has_more: boolean;
+    next_page_cursor: string | null;
+}
+type InstagramConnectionType = "followers" | "following";
+type InstagramInteractionType = "commenters" | "likers";
 interface PaginationInfo {
     tableName?: string | null;
     totalRows: number;
@@ -7,6 +44,116 @@ interface PaginationInfo {
     resultsCount: number;
 }
 
+interface InstagramPost {
+    id?: string | null;
+    postType?: string | null;
+    userId?: string | null;
+    username?: string | null;
+    fullName?: string | null;
+    caption?: string | null;
+    mediaType?: string | null;
+    codeUrl?: string | null;
+    imageUrl?: string | null;
+    videoUrl?: string | null;
+    audioOnlyUrl?: string | null;
+    profilePicUrl?: string | null;
+    videoSubtitlesUri?: string | null;
+    subtitles?: string | null;
+    videoDuration?: number | null;
+    likeCount?: number | null;
+    commentCount?: number | null;
+    reshareCount?: number | null;
+    videoPlayCount?: number | null;
+    location?: string | null;
+    genAiChatWithAiCtaInfo?: string | null;
+    hasHighRiskGenAiInformTreatment?: boolean | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
+    [key: string]: unknown;
+}
+interface InstagramUser {
+    id?: string | null;
+    username?: string | null;
+    fullName?: string | null;
+    biography?: string | null;
+    isPrivate?: boolean | null;
+    isVerified?: boolean | null;
+    followerCount?: number | null;
+    followingCount?: number | null;
+    mediaCount?: number | null;
+    profilePicUrl?: string | null;
+    profilePicId?: string | null;
+    profileUrl?: string | null;
+    externalUrl?: string | null;
+    hasAnonymousProfilePicture?: boolean | null;
+    aggRelevance?: number | null;
+    relevantPostsCount?: number | null;
+    relevantPostsLikesSum?: number | null;
+    relevantPostsCommentsSum?: number | null;
+    relevantPostsResharesSum?: number | null;
+    relevantPostsVideoPlaysSum?: number | null;
+    [key: string]: unknown;
+}
+interface InstagramComment {
+    id?: string | null;
+    text?: string | null;
+    parentPostId?: string | null;
+    parentPostUserId?: string | null;
+    type?: string | null;
+    parentCommentId?: string | null;
+    repliedToCommentId?: string | null;
+    childCommentCount?: number | null;
+    userId?: string | null;
+    username?: string | null;
+    fullName?: string | null;
+    likeCount?: number | null;
+    status?: string | null;
+    isSpam?: boolean | null;
+    hasTranslation?: boolean | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
+    [key: string]: unknown;
+}
+
+declare class InstagramLiveNamespace {
+    private transport;
+    constructor(transport: RestTransport);
+    private page;
+    private single;
+    searchPosts(query: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<InstagramPost>>;
+    getPostsByUser(identifier: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<InstagramPost>>;
+    getPost(postId: string, options?: {
+        fields?: string[];
+    }): Promise<InstagramPost | null>;
+    getComments(postId: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<InstagramComment>>;
+    getPostInteractingUsers(postId: string, interactionType: InstagramInteractionType, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<InstagramUser>>;
+    searchUsers(name: string, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): Promise<CursorResult<InstagramUser>>;
+    getUser(identifier: string, options?: {
+        fields?: string[];
+    }): Promise<InstagramUser | null>;
+    getUserConnections(identifier: string, connectionType: InstagramConnectionType, options?: {
+        fields?: string[];
+        cursor?: string;
+    }): 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> {
@@ -216,79 +363,6 @@ declare class TwitterNamespace extends BaseNamespace {
     }): Promise<PaginatedResult<TwitterUser>>;
 }
 
-interface InstagramPost {
-    id?: string | null;
-    postType?: string | null;
-    userId?: string | null;
-    username?: string | null;
-    fullName?: string | null;
-    caption?: string | null;
-    mediaType?: string | null;
-    codeUrl?: string | null;
-    imageUrl?: string | null;
-    videoUrl?: string | null;
-    audioOnlyUrl?: string | null;
-    profilePicUrl?: string | null;
-    videoSubtitlesUri?: string | null;
-    subtitles?: string | null;
-    videoDuration?: number | null;
-    likeCount?: number | null;
-    commentCount?: number | null;
-    reshareCount?: number | null;
-    videoPlayCount?: number | null;
-    location?: string | null;
-    genAiChatWithAiCtaInfo?: string | null;
-    hasHighRiskGenAiInformTreatment?: boolean | null;
-    createdAt?: string | number | null;
-    createdAtTimestamp?: string | number | null;
-    createdAtDate?: string | number | null;
-    [key: string]: unknown;
-}
-interface InstagramUser {
-    id?: string | null;
-    username?: string | null;
-    fullName?: string | null;
-    biography?: string | null;
-    isPrivate?: boolean | null;
-    isVerified?: boolean | null;
-    followerCount?: number | null;
-    followingCount?: number | null;
-    mediaCount?: number | null;
-    profilePicUrl?: string | null;
-    profilePicId?: string | null;
-    profileUrl?: string | null;
-    externalUrl?: string | null;
-    hasAnonymousProfilePicture?: boolean | null;
-    aggRelevance?: number | null;
-    relevantPostsCount?: number | null;
-    relevantPostsLikesSum?: number | null;
-    relevantPostsCommentsSum?: number | null;
-    relevantPostsResharesSum?: number | null;
-    relevantPostsVideoPlaysSum?: number | null;
-    [key: string]: unknown;
-}
-interface InstagramComment {
-    id?: string | null;
-    text?: string | null;
-    parentPostId?: string | null;
-    parentPostUserId?: string | null;
-    type?: string | null;
-    parentCommentId?: string | null;
-    repliedToCommentId?: string | null;
-    childCommentCount?: number | null;
-    userId?: string | null;
-    username?: string | null;
-    fullName?: string | null;
-    likeCount?: number | null;
-    status?: string | null;
-    isSpam?: boolean | null;
-    hasTranslation?: boolean | null;
-    createdAt?: string | number | null;
-    createdAtTimestamp?: string | number | null;
-    createdAtDate?: string | number | null;
-    [key: string]: unknown;
-}
-
 declare class InstagramNamespace extends BaseNamespace {
     getPostsByIds(postIds: string[], options?: {
         fields?: string[];
@@ -797,12 +871,16 @@ declare class XpozClient {
     account: AccountNamespace;
     private transport;
     private versionCheck;
+    private restTransport;
+    private instagramLiveNamespace?;
     constructor(options?: {
         apiKey?: string;
         serverUrl?: string;
         timeoutMs?: number;
         versionCheck?: boolean;
+        apiUrl?: string;
     });
+    get instagramLive(): InstagramLiveNamespace;
     connect(): Promise<void>;
     close(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
@@ -817,6 +895,12 @@ declare class AuthenticationError extends XpozError {
 declare class XpozConnectionError extends XpozError {
     constructor(message: string);
 }
+declare class NotFoundError extends XpozError {
+    constructor(message: string);
+}
+declare class ValidationError extends XpozError {
+    constructor(message: string);
+}
 declare class OperationTimeoutError extends XpozError {
     operationId: string;
     elapsedMs: number;
@@ -832,8 +916,8 @@ declare class OperationCancelledError extends XpozError {
     constructor(operationId: string);
 }
 
-declare const VERSION = "0.6.11";
+declare const VERSION = "0.6.13";
 
 declare function checkForUpdates(): Promise<void>;
 
-export { type AccountBilling, type AccountDetails, type AccountUsage, type AddTrackedItemsResult, AuthenticationError, BillingPeriod, CreditResetFrequency, type CreditsUsageHistory, type InstagramComment, type InstagramPost, type InstagramUser, 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, 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 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.11";
+var VERSION = "0.6.13";
 
 // src/mcp/transport.ts
 var USER_AGENT = `xpoz-ts-sdk/${VERSION}`;
@@ -343,6 +343,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;
@@ -385,6 +397,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();
@@ -1214,6 +1436,8 @@ var XpozClient = class {
   account;
   transport;
   versionCheck;
+  restTransport;
+  instagramLiveNamespace;
   constructor(options = {}) {
     const apiKey = options.apiKey ?? process.env[ENV_API_KEY];
     if (!apiKey) {
@@ -1225,6 +1449,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);
@@ -1233,6 +1459,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) {
@@ -1278,6 +1510,8 @@ export {
   AuthenticationError,
   BillingPeriod,
   CreditResetFrequency,
+  CursorResult,
+  NotFoundError,
   OperationCancelledError,
   OperationFailedError,
   OperationTimeoutError,
@@ -1286,6 +1520,7 @@ export {
   TrackedItemPlatform,
   TrackedItemType,
   VERSION,
+  ValidationError,
   XpozClient,
   XpozConnectionError,
   XpozError,

package/package.json

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