@xpoz/xpoz 0.6.9 → 0.6.11

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.
 
@@ -84,10 +84,14 @@ const client = new XpozClient({ apiKey: "your-api-key", timeoutMs: 600_000 });
 Want to try the SDK before signing up? Mint a free trial token (no account needed, valid for 5 days):
 
 ```bash
-curl -X POST https://api.xpoz.ai/api/trial/token
+curl -X POST https://api.xpoz.ai/api/trial/token \
+  -H "Content-Type: application/json" \
+  -d '{"source": "sdk"}'
 # -> { "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`).
+
 Then use the returned token (it starts with `TRIAL`) as your API key:
 
 ```typescript
@@ -578,6 +582,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.
@@ -793,6 +807,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                |
@@ -812,9 +839,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         |
@@ -860,7 +891,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   |
 
@@ -907,7 +940,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
 
@@ -972,8 +1007,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

@@ -298,7 +298,7 @@ function coerce(value) {
 }
 
 // src/version.ts
-var VERSION = "0.6.9";
+var VERSION = "0.6.11";
 
 // src/mcp/transport.ts
 var USER_AGENT = `xpoz-ts-sdk/${VERSION}`;
@@ -622,6 +622,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 +981,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);

package/dist/index.d.cts

@@ -80,11 +80,13 @@ interface TwitterPost {
     mediaUrls?: string[] | null;
     urls?: string[] | null;
     grokGeneratedContent?: Record<string, unknown>[] | null;
-    country?: string | null;
-    region?: string | null;
-    city?: string | null;
-    createdAt?: string | null;
-    createdAtDate?: string | null;
+    placeName?: string | null;
+    placeCountry?: string | null;
+    placeCountryCode?: string | null;
+    placeBoundingBoxCoordinates?: unknown | null;
+    placeCentroid?: unknown | null;
+    createdAt?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface TwitterUser {
@@ -118,7 +120,7 @@ interface TwitterUser {
     verifiedSinceDatetime?: string | null;
     usernameChanges?: string[] | null;
     lastUsernameChangeDatetime?: string | null;
-    createdAt?: string | null;
+    createdAt?: string | number | null;
     modifiedAt?: string | null;
     aggRelevance?: number | null;
     relevantTweetsCount?: number | null;
@@ -237,9 +239,9 @@ interface InstagramPost {
     location?: string | null;
     genAiChatWithAiCtaInfo?: string | null;
     hasHighRiskGenAiInformTreatment?: boolean | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface InstagramUser {
@@ -281,9 +283,9 @@ interface InstagramComment {
     status?: string | null;
     isSpam?: boolean | null;
     hasTranslation?: boolean | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 
@@ -372,9 +374,12 @@ interface RedditPost {
     postHint?: string | null;
     domain?: string | null;
     crosspostParent?: string | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    selftextHtml?: string | null;
+    editedAt?: string | null;
+    removal?: Record<string, unknown> | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface RedditUser {
@@ -402,9 +407,9 @@ interface RedditUser {
     profileDescription?: string | null;
     profileBannerUrl?: string | null;
     profileTitle?: string | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     aggRelevance?: number | null;
     relevantPostsCount?: number | null;
     relevantPostsUpvotesSum?: number | null;
@@ -430,9 +435,14 @@ interface RedditComment {
     collapsed?: boolean | null;
     edited?: boolean | null;
     distinguished?: string | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    rank?: number | null;
+    topLevelRank?: number | null;
+    collapsedReasonCode?: string | null;
+    collapsedReason?: string | null;
+    removal?: Record<string, unknown> | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface RedditSubreddit {
@@ -444,6 +454,7 @@ interface RedditSubreddit {
     subscribersCount?: number | null;
     activeUserCount?: number | null;
     subredditType?: string | null;
+    submissionType?: string | null;
     over18?: boolean | null;
     lang?: string | null;
     url?: string | null;
@@ -452,9 +463,9 @@ interface RedditSubreddit {
     bannerImg?: string | null;
     headerImg?: string | null;
     communityIcon?: string | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     aggRelevance?: number | null;
     relevantPostsCount?: number | null;
     relevantPostsUpvotesSum?: number | null;
@@ -497,6 +508,10 @@ declare class RedditNamespace extends BaseNamespace {
         endDate?: string;
         subreddit?: string;
     }): Promise<PaginatedResult<RedditComment>>;
+    getCommentById(commentId: string, options?: {
+        fields?: string[];
+        forceLatest?: boolean;
+    }): Promise<RedditComment>;
     getUser(username: string, options?: {
         fields?: string[];
         forceLatest?: boolean;
@@ -551,9 +566,9 @@ interface TiktokPost {
     duration?: number | null;
     videoUrl?: string[] | null;
     transcriptsJson?: Record<string, string> | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface TiktokUser {
@@ -571,7 +586,7 @@ interface TiktokUser {
     postCount?: number | null;
     language?: string | null;
     region?: string | null;
-    createdAt?: string | null;
+    createdAt?: string | number | null;
     usernameModifyTime?: string | null;
     aggRelevance?: number | null;
     relevantPostsCount?: number | null;
@@ -588,9 +603,9 @@ interface TiktokComment {
     username?: string | null;
     text?: string | null;
     likeCount?: number | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface TiktokSound {
@@ -817,7 +832,7 @@ declare class OperationCancelledError extends XpozError {
     constructor(operationId: string);
 }
 
-declare const VERSION = "0.6.9";
+declare const VERSION = "0.6.11";
 
 declare function checkForUpdates(): Promise<void>;
 

package/dist/index.d.ts

@@ -80,11 +80,13 @@ interface TwitterPost {
     mediaUrls?: string[] | null;
     urls?: string[] | null;
     grokGeneratedContent?: Record<string, unknown>[] | null;
-    country?: string | null;
-    region?: string | null;
-    city?: string | null;
-    createdAt?: string | null;
-    createdAtDate?: string | null;
+    placeName?: string | null;
+    placeCountry?: string | null;
+    placeCountryCode?: string | null;
+    placeBoundingBoxCoordinates?: unknown | null;
+    placeCentroid?: unknown | null;
+    createdAt?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface TwitterUser {
@@ -118,7 +120,7 @@ interface TwitterUser {
     verifiedSinceDatetime?: string | null;
     usernameChanges?: string[] | null;
     lastUsernameChangeDatetime?: string | null;
-    createdAt?: string | null;
+    createdAt?: string | number | null;
     modifiedAt?: string | null;
     aggRelevance?: number | null;
     relevantTweetsCount?: number | null;
@@ -237,9 +239,9 @@ interface InstagramPost {
     location?: string | null;
     genAiChatWithAiCtaInfo?: string | null;
     hasHighRiskGenAiInformTreatment?: boolean | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface InstagramUser {
@@ -281,9 +283,9 @@ interface InstagramComment {
     status?: string | null;
     isSpam?: boolean | null;
     hasTranslation?: boolean | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 
@@ -372,9 +374,12 @@ interface RedditPost {
     postHint?: string | null;
     domain?: string | null;
     crosspostParent?: string | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    selftextHtml?: string | null;
+    editedAt?: string | null;
+    removal?: Record<string, unknown> | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface RedditUser {
@@ -402,9 +407,9 @@ interface RedditUser {
     profileDescription?: string | null;
     profileBannerUrl?: string | null;
     profileTitle?: string | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     aggRelevance?: number | null;
     relevantPostsCount?: number | null;
     relevantPostsUpvotesSum?: number | null;
@@ -430,9 +435,14 @@ interface RedditComment {
     collapsed?: boolean | null;
     edited?: boolean | null;
     distinguished?: string | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    rank?: number | null;
+    topLevelRank?: number | null;
+    collapsedReasonCode?: string | null;
+    collapsedReason?: string | null;
+    removal?: Record<string, unknown> | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface RedditSubreddit {
@@ -444,6 +454,7 @@ interface RedditSubreddit {
     subscribersCount?: number | null;
     activeUserCount?: number | null;
     subredditType?: string | null;
+    submissionType?: string | null;
     over18?: boolean | null;
     lang?: string | null;
     url?: string | null;
@@ -452,9 +463,9 @@ interface RedditSubreddit {
     bannerImg?: string | null;
     headerImg?: string | null;
     communityIcon?: string | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     aggRelevance?: number | null;
     relevantPostsCount?: number | null;
     relevantPostsUpvotesSum?: number | null;
@@ -497,6 +508,10 @@ declare class RedditNamespace extends BaseNamespace {
         endDate?: string;
         subreddit?: string;
     }): Promise<PaginatedResult<RedditComment>>;
+    getCommentById(commentId: string, options?: {
+        fields?: string[];
+        forceLatest?: boolean;
+    }): Promise<RedditComment>;
     getUser(username: string, options?: {
         fields?: string[];
         forceLatest?: boolean;
@@ -551,9 +566,9 @@ interface TiktokPost {
     duration?: number | null;
     videoUrl?: string[] | null;
     transcriptsJson?: Record<string, string> | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface TiktokUser {
@@ -571,7 +586,7 @@ interface TiktokUser {
     postCount?: number | null;
     language?: string | null;
     region?: string | null;
-    createdAt?: string | null;
+    createdAt?: string | number | null;
     usernameModifyTime?: string | null;
     aggRelevance?: number | null;
     relevantPostsCount?: number | null;
@@ -588,9 +603,9 @@ interface TiktokComment {
     username?: string | null;
     text?: string | null;
     likeCount?: number | null;
-    createdAt?: string | null;
-    createdAtTimestamp?: number | null;
-    createdAtDate?: string | null;
+    createdAt?: string | number | null;
+    createdAtTimestamp?: string | number | null;
+    createdAtDate?: string | number | null;
     [key: string]: unknown;
 }
 interface TiktokSound {
@@ -817,7 +832,7 @@ declare class OperationCancelledError extends XpozError {
     constructor(operationId: string);
 }
 
-declare const VERSION = "0.6.9";
+declare const VERSION = "0.6.11";
 
 declare function checkForUpdates(): Promise<void>;
 

package/dist/index.js

@@ -248,7 +248,7 @@ function coerce(value) {
 }
 
 // src/version.ts
-var VERSION = "0.6.9";
+var VERSION = "0.6.11";
 
 // src/mcp/transport.ts
 var USER_AGENT = `xpoz-ts-sdk/${VERSION}`;
@@ -572,6 +572,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";
@@ -930,6 +931,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);

package/package.json

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