@xpoz/xpoz 0.6.8 → 0.6.10

package/README.md

@@ -30,7 +30,7 @@ The SDK wraps Xpoz's [MCP](https://modelcontextprotocol.io) server, abstracting
 
 ## Features
 
-- **40 data methods** across Twitter, Instagram, Reddit, and TikTok
+- **42 data methods** across Twitter, Instagram, Reddit, and TikTok
 - **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
@@ -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
@@ -229,12 +233,12 @@ The following methods accept both `responseType` and `limit`:
 - `twitter.getPostsByAuthor()`, `twitter.searchPosts()`, `twitter.getUsersByKeywords()`
 - `instagram.getPostsByUser()`, `instagram.searchPosts()`, `instagram.getUsersByKeywords()`
 - `reddit.searchPosts()`
-- `tiktok.getPostsByUser()`, `tiktok.searchPosts()`, `tiktok.getUsersByKeywords()`, `tiktok.getPostsByHashtags()`, `tiktok.getUsersByHashtags()`
+- `tiktok.getPostsByUser()`, `tiktok.searchPosts()`, `tiktok.getUsersByKeywords()`, `tiktok.getPostsByHashtags()`, `tiktok.getUsersByHashtags()`, `tiktok.getPostsBySound()`
 
 These methods accept `limit` only:
 
 - `twitter.searchUsers()`, `instagram.searchUsers()`, `reddit.searchUsers()`, `reddit.searchSubreddits()`
-- `tiktok.searchUsers()`
+- `tiktok.searchUsers()`, `tiktok.searchSounds()`
 
 ## Query Syntax
 
@@ -691,6 +695,26 @@ const users = await client.tiktok.getUsersByHashtags(["sustainable_fashion"], {
 });
 ```
 
+#### `searchSounds(keyword, options?) -> Promise<TiktokSound[]>`
+
+Search sound/music objects by keyword (title or artist). Pass the returned `id` to `getPostsBySound`.
+
+```typescript
+const sounds = await client.tiktok.searchSounds("dance monkey");
+const soundId = sounds[0].id;
+```
+
+#### `getPostsBySound(soundId, options?) -> Promise<PaginatedResult<TiktokPost>>`
+
+Find posts that use a specific sound via the indexed `music_id` column. Pass a single numeric `soundId` from `searchSounds`.
+
+```typescript
+const results = await client.tiktok.getPostsBySound("7016548364456789012", {
+  responseType: ResponseType.Fast,
+  limit: 50,
+});
+```
+
 #### `getComments(postId, options?) -> Promise<PaginatedResult<TiktokComment>>`
 
 ```typescript
@@ -743,6 +767,32 @@ console.log(`Removed ${result.removedCount} items`);
 
 ---
 
+### Account — `client.account`
+
+Read-only account, plan, and usage information for the authenticated user.
+
+#### `getAccountDetails() -> Promise<AccountDetails>`
+
+Returns the plan (name + feature limits), billing (period + next renewal; `billing` is `null` on the Free plan), and current usage (remaining subscription/extra credits, extra tracked items).
+
+```typescript
+const details = await client.account.getAccountDetails();
+console.log(details.plan.name, details.usage.subscriptionCreditsRemaining);
+```
+
+#### `getCreditsUsageHistory(range?, granularity?) -> Promise<CreditsUsageHistory>`
+
+Returns time-series usage for credits and export rows. `range` is one of `"today"`, `"7d"`, `"current_month"` (default), `"lifetime"`; `granularity` is `"hour"` or `"day"` (default). For current remaining balances, use `getAccountDetails()`.
+
+```typescript
+const history = await client.account.getCreditsUsageHistory("7d", "day");
+for (const bucket of history.credits) {
+  console.log(bucket.bucket, bucket.totalUsed);
+}
+```
+
+---
+
 ## Type Models
 
 All fields are optional and typed as their respective TypeScript types. Unknown fields are preserved on the object.
@@ -962,6 +1012,80 @@ All fields are optional and typed as their respective TypeScript types. Unknown
 | `createdAt`     | `string` | Creation timestamp       |
 | `createdAtDate` | `string` | Creation date (YYYY-MM-DD) |
 
+### TiktokSound
+
+| Field              | Type      | Description                       |
+| ------------------ | --------- | --------------------------------- |
+| `id`               | `string`  | Sound/music ID                    |
+| `title`            | `string`  | Sound title                       |
+| `author`           | `string`  | Sound artist/author               |
+| `album`            | `string`  | Album name                        |
+| `duration`         | `number`  | Duration in seconds               |
+| `userCount`        | `number`  | Number of posts using the sound   |
+| `isOriginal`       | `boolean` | Whether the sound is original     |
+| `isCommerceMusic`  | `boolean` | Whether the sound is commercial   |
+| `isOriginalSound`  | `boolean` | Whether it is an original sound   |
+
+### AccountDetails
+
+Returned by `getAccountDetails()`.
+
+| Field     | Type                                  | Description                          |
+| --------- | ------------------------------------- | ------------------------------------ |
+| `plan`    | `{ name: string; features: PlanFeatures }` | Plan name and feature limits    |
+| `billing` | `AccountBilling \| null`              | Billing info (`null` on Free plan)   |
+| `usage`   | `AccountUsage`                        | Current usage balances               |
+
+### PlanFeatures
+
+| Field                    | Type                   | Description                     |
+| ------------------------ | ---------------------- | ------------------------------- |
+| `credits`                | `number`               | Subscription credits per period |
+| `creditResetFrequency`   | `CreditResetFrequency` | `"monthly"` or `"never"`        |
+| `extraCreditPrice`       | `number`               | Price per extra credit          |
+| `trackedItems`           | `number`               | Tracked-item allowance          |
+| `csvRowExportLimit`      | `number`               | CSV row export limit            |
+| `extraCsvRowPrice`       | `number`               | Price per extra CSV row         |
+| `extraTrackedItemPrice`  | `number`               | Price per extra tracked item    |
+| `maxRowsPerExport`       | `number`               | Max rows per single export      |
+
+### AccountBilling
+
+| Field             | Type            | Description               |
+| ----------------- | --------------- | ------------------------- |
+| `billingPeriod`   | `BillingPeriod` | `"monthly"` or `"annual"` |
+| `nextRenewalDate` | `string \| null` | Next renewal date         |
+
+### AccountUsage
+
+| Field                          | Type     | Description                    |
+| ------------------------------ | -------- | ------------------------------ |
+| `subscriptionCreditsRemaining` | `number` | Subscription credits remaining |
+| `extraCreditsRemaining`        | `number` | Extra credits remaining        |
+| `extraTrackedItems`            | `number` | Extra tracked items purchased  |
+
+### CreditsUsageHistory
+
+Returned by `getCreditsUsageHistory()`.
+
+| Field         | Type                   | Description                         |
+| ------------- | ---------------------- | ----------------------------------- |
+| `range`       | `string`               | Requested range                     |
+| `granularity` | `string`               | Requested granularity               |
+| `generatedAt` | `string`               | Timestamp the report was generated  |
+| `credits`     | `UsageHistoryBucket[]` | Credit usage buckets over time      |
+| `exportRows`  | `UsageHistoryBucket[]` | Export-rows usage buckets over time |
+
+### UsageHistoryBucket
+
+| Field              | Type     | Description                           |
+| ------------------ | -------- | ------------------------------------- |
+| `bucket`           | `string` | Bucket timestamp (hour or day)        |
+| `subscriptionUsed` | `number` | Subscription units used in the bucket |
+| `extraUsed`        | `number` | Extra units used in the bucket        |
+| `totalUsed`        | `number` | Total units used in the bucket        |
+| `extraPurchased`   | `number` | Extra units purchased in the bucket   |
+
 ### TrackedItem
 
 | Field      | Type                   | Description                                              |

package/dist/index.cjs

@@ -298,7 +298,7 @@ function coerce(value) {
 }
 
 // src/version.ts
-var VERSION = "0.6.8";
+var VERSION = "0.6.10";
 
 // src/mcp/transport.ts
 var USER_AGENT = `xpoz-ts-sdk/${VERSION}`;
@@ -637,10 +637,13 @@ var GET_TIKTOK_USER = "getTiktokUser";
 var SEARCH_TIKTOK_USERS = "searchTiktokUsers";
 var GET_TIKTOK_USERS_BY_KEYWORDS = "getTiktokUsersByKeywords";
 var GET_TIKTOK_USERS_BY_HASHTAGS = "getTiktokUsersByHashtags";
+var SEARCH_TIKTOK_SOUNDS = "searchTiktokSounds";
+var GET_TIKTOK_POSTS_BY_SOUND = "getTiktokPostsBySound";
 var GET_TRACKED_ITEMS = "getTrackedItems";
 var ADD_TRACKED_ITEMS = "addTrackedItems";
 var REMOVE_TRACKED_ITEMS = "removeTrackedItems";
 var GET_ACCOUNT_DETAILS = "getAccountDetails";
+var GET_CREDITS_USAGE_HISTORY = "getCreditsUsageHistory";
 
 // src/namespaces/twitter.ts
 function parseTwitterPost(item) {
@@ -1063,6 +1066,9 @@ function parseUser4(item) {
 function parseComment3(item) {
   return item;
 }
+function parseSound(item) {
+  return item;
+}
 var TiktokNamespace = class extends BaseNamespace {
   async getPostsByIds(postIds, options = {}) {
     const args = this.buildArgs({ postIds, ...options });
@@ -1155,6 +1161,16 @@ var TiktokNamespace = class extends BaseNamespace {
       args
     );
   }
+  async searchSounds(keyword, options = {}) {
+    const args = this.buildArgs({ keyword, ...options });
+    const result = await this.callAndMaybePoll(SEARCH_TIKTOK_SOUNDS, args);
+    return (result["results"] ?? []).map(parseSound);
+  }
+  async getPostsBySound(soundId, options = {}) {
+    const args = this.buildArgs({ soundId, ...options });
+    const result = await this.callAndMaybePoll(GET_TIKTOK_POSTS_BY_SOUND, args);
+    return this.buildPaginatedResult(result, parsePost3, GET_TIKTOK_POSTS_BY_SOUND, args);
+  }
 };
 
 // src/namespaces/tracking.ts
@@ -1181,6 +1197,11 @@ var AccountNamespace = class extends BaseNamespace {
     const result = await this.callTool(GET_ACCOUNT_DETAILS, {});
     return result["data"];
   }
+  async getCreditsUsageHistory(range, granularity) {
+    const args = this.buildArgs({ range, granularity });
+    const result = await this.callTool(GET_CREDITS_USAGE_HISTORY, args);
+    return result["data"];
+  }
 };
 
 // src/versionCheck.ts

package/dist/index.d.cts

@@ -593,6 +593,18 @@ interface TiktokComment {
     createdAtDate?: string | null;
     [key: string]: unknown;
 }
+interface TiktokSound {
+    id?: string | null;
+    title?: string | null;
+    author?: string | null;
+    album?: string | null;
+    duration?: number | null;
+    userCount?: number | null;
+    isOriginal?: boolean | null;
+    isCommerceMusic?: boolean | null;
+    isOriginalSound?: boolean | null;
+    [key: string]: unknown;
+}
 
 declare class TiktokNamespace extends BaseNamespace {
     getPostsByIds(postIds: string[], options?: {
@@ -655,6 +667,18 @@ declare class TiktokNamespace extends BaseNamespace {
         responseType?: ResponseType;
         limit?: number;
     }): Promise<PaginatedResult<TiktokUser>>;
+    searchSounds(keyword: string, options?: {
+        limit?: number;
+        fields?: string[];
+    }): Promise<TiktokSound[]>;
+    getPostsBySound(soundId: string, options?: {
+        fields?: string[];
+        startDate?: string;
+        endDate?: string;
+        forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
+    }): Promise<PaginatedResult<TiktokPost>>;
 }
 
 declare enum TrackedItemType {
@@ -729,9 +753,24 @@ interface AccountDetails {
     billing: AccountBilling | null;
     usage: AccountUsage;
 }
+interface UsageHistoryBucket {
+    bucket: string;
+    subscriptionUsed: number;
+    extraUsed: number;
+    totalUsed: number;
+    extraPurchased: number;
+}
+interface CreditsUsageHistory {
+    range: string;
+    granularity: string;
+    generatedAt: string;
+    credits: UsageHistoryBucket[];
+    exportRows: UsageHistoryBucket[];
+}
 
 declare class AccountNamespace extends BaseNamespace {
     getAccountDetails(): Promise<AccountDetails>;
+    getCreditsUsageHistory(range?: string, granularity?: string): Promise<CreditsUsageHistory>;
 }
 
 declare class XpozClient {
@@ -778,8 +817,8 @@ declare class OperationCancelledError extends XpozError {
     constructor(operationId: string);
 }
 
-declare const VERSION = "0.6.8";
+declare const VERSION = "0.6.10";
 
 declare function checkForUpdates(): Promise<void>;
 
-export { type AccountBilling, type AccountDetails, type AccountUsage, type AddTrackedItemsResult, AuthenticationError, BillingPeriod, CreditResetFrequency, 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, VERSION, XpozClient, XpozConnectionError, XpozError, checkForUpdates };
+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 };

package/dist/index.d.ts

@@ -593,6 +593,18 @@ interface TiktokComment {
     createdAtDate?: string | null;
     [key: string]: unknown;
 }
+interface TiktokSound {
+    id?: string | null;
+    title?: string | null;
+    author?: string | null;
+    album?: string | null;
+    duration?: number | null;
+    userCount?: number | null;
+    isOriginal?: boolean | null;
+    isCommerceMusic?: boolean | null;
+    isOriginalSound?: boolean | null;
+    [key: string]: unknown;
+}
 
 declare class TiktokNamespace extends BaseNamespace {
     getPostsByIds(postIds: string[], options?: {
@@ -655,6 +667,18 @@ declare class TiktokNamespace extends BaseNamespace {
         responseType?: ResponseType;
         limit?: number;
     }): Promise<PaginatedResult<TiktokUser>>;
+    searchSounds(keyword: string, options?: {
+        limit?: number;
+        fields?: string[];
+    }): Promise<TiktokSound[]>;
+    getPostsBySound(soundId: string, options?: {
+        fields?: string[];
+        startDate?: string;
+        endDate?: string;
+        forceLatest?: boolean;
+        responseType?: ResponseType;
+        limit?: number;
+    }): Promise<PaginatedResult<TiktokPost>>;
 }
 
 declare enum TrackedItemType {
@@ -729,9 +753,24 @@ interface AccountDetails {
     billing: AccountBilling | null;
     usage: AccountUsage;
 }
+interface UsageHistoryBucket {
+    bucket: string;
+    subscriptionUsed: number;
+    extraUsed: number;
+    totalUsed: number;
+    extraPurchased: number;
+}
+interface CreditsUsageHistory {
+    range: string;
+    granularity: string;
+    generatedAt: string;
+    credits: UsageHistoryBucket[];
+    exportRows: UsageHistoryBucket[];
+}
 
 declare class AccountNamespace extends BaseNamespace {
     getAccountDetails(): Promise<AccountDetails>;
+    getCreditsUsageHistory(range?: string, granularity?: string): Promise<CreditsUsageHistory>;
 }
 
 declare class XpozClient {
@@ -778,8 +817,8 @@ declare class OperationCancelledError extends XpozError {
     constructor(operationId: string);
 }
 
-declare const VERSION = "0.6.8";
+declare const VERSION = "0.6.10";
 
 declare function checkForUpdates(): Promise<void>;
 
-export { type AccountBilling, type AccountDetails, type AccountUsage, type AddTrackedItemsResult, AuthenticationError, BillingPeriod, CreditResetFrequency, 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, VERSION, XpozClient, XpozConnectionError, XpozError, checkForUpdates };
+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 };

package/dist/index.js

@@ -248,7 +248,7 @@ function coerce(value) {
 }
 
 // src/version.ts
-var VERSION = "0.6.8";
+var VERSION = "0.6.10";
 
 // src/mcp/transport.ts
 var USER_AGENT = `xpoz-ts-sdk/${VERSION}`;
@@ -587,10 +587,13 @@ var GET_TIKTOK_USER = "getTiktokUser";
 var SEARCH_TIKTOK_USERS = "searchTiktokUsers";
 var GET_TIKTOK_USERS_BY_KEYWORDS = "getTiktokUsersByKeywords";
 var GET_TIKTOK_USERS_BY_HASHTAGS = "getTiktokUsersByHashtags";
+var SEARCH_TIKTOK_SOUNDS = "searchTiktokSounds";
+var GET_TIKTOK_POSTS_BY_SOUND = "getTiktokPostsBySound";
 var GET_TRACKED_ITEMS = "getTrackedItems";
 var ADD_TRACKED_ITEMS = "addTrackedItems";
 var REMOVE_TRACKED_ITEMS = "removeTrackedItems";
 var GET_ACCOUNT_DETAILS = "getAccountDetails";
+var GET_CREDITS_USAGE_HISTORY = "getCreditsUsageHistory";
 
 // src/namespaces/twitter.ts
 function parseTwitterPost(item) {
@@ -1013,6 +1016,9 @@ function parseUser4(item) {
 function parseComment3(item) {
   return item;
 }
+function parseSound(item) {
+  return item;
+}
 var TiktokNamespace = class extends BaseNamespace {
   async getPostsByIds(postIds, options = {}) {
     const args = this.buildArgs({ postIds, ...options });
@@ -1105,6 +1111,16 @@ var TiktokNamespace = class extends BaseNamespace {
       args
     );
   }
+  async searchSounds(keyword, options = {}) {
+    const args = this.buildArgs({ keyword, ...options });
+    const result = await this.callAndMaybePoll(SEARCH_TIKTOK_SOUNDS, args);
+    return (result["results"] ?? []).map(parseSound);
+  }
+  async getPostsBySound(soundId, options = {}) {
+    const args = this.buildArgs({ soundId, ...options });
+    const result = await this.callAndMaybePoll(GET_TIKTOK_POSTS_BY_SOUND, args);
+    return this.buildPaginatedResult(result, parsePost3, GET_TIKTOK_POSTS_BY_SOUND, args);
+  }
 };
 
 // src/namespaces/tracking.ts
@@ -1131,6 +1147,11 @@ var AccountNamespace = class extends BaseNamespace {
     const result = await this.callTool(GET_ACCOUNT_DETAILS, {});
     return result["data"];
   }
+  async getCreditsUsageHistory(range, granularity) {
+    const args = this.buildArgs({ range, granularity });
+    const result = await this.callTool(GET_CREDITS_USAGE_HISTORY, args);
+    return result["data"];
+  }
 };
 
 // src/versionCheck.ts

package/package.json

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