upload-post 2.9.0 → 2.12.0

package/README.md

@@ -37,6 +37,8 @@ console.log(response);
 - ✅ **Posting Queue** - Add posts to your configured queue
 - ✅ **First Comments** - Auto-post first comment after publishing
 - ✅ **Analytics** - Get engagement metrics
+- ✅ **Audience** - Who follows a profile, per platform
+- ✅ **Suggestions** - Hashtags and searches to post about, per platform
 - ✅ **Full TypeScript Support**
 
 ## Using this from an AI agent? Use the MCP server instead
@@ -295,8 +297,268 @@ const liPages = await client.getLinkedinPages('my-profile');
 
 // Get Pinterest boards for a profile
 const boards = await client.getPinterestBoards('my-profile');
+
+// TikTok: trending Commercial Music Library tracks
+const music = await client.getTiktokTrendingMusic('my-profile', {
+  genre: 'POP',
+  countryCode: 'ES',
+  dateRange: '7DAY', // 1DAY, 7DAY, 30DAY, 90DAY
+});
+
+// TikTok: find a track by song or artist
+const found = await client.searchTiktokMusic('my-profile', {
+  q: 'bad bunny',
+  countryCode: 'ES',
+});
+
+// TikTok: search locations to tag
+const locations = await client.getTiktokLocations('my-profile', 'Madrid');
 ```
 
+### Comments
+
+The same methods cover every platform that has comments — Instagram, Facebook,
+YouTube, LinkedIn and TikTok. There is no per-network method: the endpoint
+answers one question and `platform` says who to ask.
+
+```javascript
+// Read the comments on a post
+const { comments } = await client.getPostComments({
+  user: 'my-profile',
+  platform: 'tiktok',
+  postId: '7412345678901234567', // TikTok has no post-URL lookup, pass the video id
+  limit: 20,
+});
+
+// Read the replies hanging from one of them — same question, one more parameter
+const { comments: replies } = await client.getPostComments({
+  user: 'my-profile',
+  platform: 'tiktok',
+  postId: '7412345678901234567',
+  commentId: comments[0].id,
+});
+
+// Comment on the post, or reply to a comment
+await client.createComment({
+  user: 'my-profile',
+  platform: 'tiktok',
+  postId: '7412345678901234567',
+  message: 'Thanks for watching!',
+});
+
+await client.createComment({
+  user: 'my-profile',
+  platform: 'tiktok',
+  commentId: comments[0].id,
+  message: 'Glad you liked it',
+});
+
+// Delete one
+await client.deleteComment({
+  user: 'my-profile',
+  platform: 'tiktok',
+  commentId: comments[0].id,
+});
+```
+
+You can also have the first comment posted for you right after publishing, with
+`firstComment` for every platform or `tiktokFirstComment` for TikTok alone.
+
+On TikTok all of this needs the `comments` capability, which the account grants
+when it connects — see
+[What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
+
+#### Moderating a comment: hide, like, pin
+
+`commentAction()` does the three and undoes them, on any platform that supports
+it. Each action carries its own inverse, and `postId` is only sent when the
+platform needs it:
+
+```javascript
+await client.commentAction({
+  user: 'my-profile',
+  platform: 'tiktok',
+  action: 'hide',
+  commentId: '7412345678909999999',
+  postId: '7412345678901234567',
+});
+
+await client.commentAction({
+  user: 'my-profile',
+  platform: 'tiktok',
+  action: 'like',
+  commentId: '7412345678909999999',
+});
+
+await client.commentAction({
+  user: 'my-profile',
+  platform: 'tiktok',
+  action: 'unpin',
+  commentId: '7412345678909999999',
+  postId: '7412345678901234567',
+});
+```
+
+| `action` | Undo | `postId` |
+| --- | --- | --- |
+| `hide` | `unhide` | required |
+| `like` | `unlike` | not sent |
+| `pin` | `unpin` | required |
+
+### Audience
+
+Where the analytics methods answer *how did my posts do*, `getAudience()`
+answers *who is following me*. One endpoint, one `platform` parameter, like
+every other question in the API.
+
+```javascript
+const audience = await client.getAudience({
+  user: 'my-profile',
+  platform: 'tiktok',
+  startDate: '2026-07-01',
+  endDate: '2026-07-30',
+});
+
+console.log(audience.range);              // the window actually used
+console.log(audience.audience.countries); // and .cities, .ages, .genders
+console.log(audience.activity_by_hour);   // [{ hour: '14', followers_online: 1494 }, ...]
+console.log(audience.followers_daily);    // [{ date, total, new, lost }, ...]
+console.log(audience.profile_actions);    // bio link, address, email, phone, leads
+console.log(audience.bio_description);
+```
+
+The window is clamped on the server: at most 60 days, and `endDate` always
+before today. A wider window is trimmed to what the platform accepts instead of
+failing.
+
+Ask for a `benchmarkCategory` and the same call also returns how the account
+compares with the average of that category. The accepted categories come back in
+`benchmark_categories` on every response, so a picker needs no second call:
+
+```javascript
+const { benchmark_categories } = await client.getAudience({
+  user: 'my-profile', platform: 'tiktok',
+});
+
+const { benchmark } = await client.getAudience({
+  user: 'my-profile',
+  platform: 'tiktok',
+  benchmarkCategory: 'SOFTWARE_AND_APPS',
+});
+console.log(benchmark.average_engagement_rate, benchmark.average_video_views);
+```
+
+### Suggestions
+
+`getSuggestions()` answers *what is worth posting about*: the hashtags or the
+searches a platform suggests around a keyword. One endpoint for both, told apart
+by `type`.
+
+```javascript
+const { hashtags } = await client.getSuggestions({
+  user: 'my-profile',
+  platform: 'tiktok',
+  type: 'hashtags',
+  q: 'pilates',
+  countryCode: 'ES',
+  language: 'es',
+});
+console.log(hashtags); // [{ name, view_count }, ...]
+
+const { keywords } = await client.getSuggestions({
+  user: 'my-profile',
+  platform: 'tiktok',
+  type: 'keywords',
+  q: 'pilates',
+});
+```
+
+Per-post numbers stay in `getPostAnalytics()`. On TikTok that response carries
+more than the usual counters: `retention` (the curve, second by second),
+`impression_sources` (For You, search, profile...), `audience_types` (followers
+vs non-followers), `new_followers`, `reach` and the watch times.
+
+Asking a platform a question it cannot answer fails with
+`platform_not_supported` and the list of the ones that can.
+
+## What a TikTok connection can do (`capabilities`)
+
+Not every TikTok connection can do the same things. `listUsers()`
+(`GET /api/uploadposts/users`) returns a `capabilities` array on each profile's
+TikTok account; check it before offering a feature.
+
+| Capability | What it unlocks |
+| --- | --- |
+| `music` | `tiktokMusicId` and the volume/trim fields, plus `getTiktokTrendingMusic()` and `searchTiktokMusic()` |
+| `location` | `tiktokLocationId` / `tiktokLocationName`, plus `getTiktokLocations()` |
+| `cover_image` | `tiktokCoverImageUrl` |
+| `cover_timestamp` | `tiktokCoverTimestamp` |
+| `draft` | `tiktokUploadToDraft` |
+| `video_privacy` | `tiktokPrivacyLevel` on video |
+| `photo_privacy` | `tiktokPrivacyLevel` on photo posts |
+| `profile_analytics` | `getAudience()` and `getSuggestions({ type: 'hashtags' })` with `platform: 'tiktok'` |
+| `comments` | Comments on TikTok: `getPostComments()` (top-level and replies), `createComment()`, `deleteComment()`, `commentAction()` and `tiktokFirstComment` |
+| `trend_search` | `getSuggestions({ type: 'keywords' })` with `platform: 'tiktok'` |
+
+> **`comments` and `trend_search` need the account to be reconnected.** TikTok
+> grants them at connect time, so an account linked before they existed keeps
+> working for everything else but will not list them — reconnect it from Manage
+> Users to enable them.
+
+If a connection lacks a capability the upload field is simply ignored: the post
+still publishes and the response carries a per-field `warnings` entry. The
+methods above answer with an error asking for a reconnection.
+
+## TikTok music, location, cover and drafts
+
+> Needs the `music`, `location`, `cover_image` or `draft` capability — see
+> [What a TikTok connection can do](#what-a-tiktok-connection-can-do-capabilities).
+
+```javascript
+// 1. Pick a track and a place
+const { tracks } = await client.getTiktokTrendingMusic('my-profile', { countryCode: 'ES' });
+// ...or find one by name. TikTok has no music search endpoint, so this searches
+// the trending charts Upload-Post caches, not TikTok's whole catalogue.
+// const { tracks } = await client.searchTiktokMusic('my-profile', { q: 'bossa', countryCode: 'ES' });
+const { locations } = await client.getTiktokLocations('my-profile', 'Madrid');
+
+// 2. Publish with them
+await client.upload('./video.mp4', {
+  title: 'Shot in Madrid',
+  user: 'my-profile',
+  platforms: ['tiktok'],
+
+  tiktokMusicId: tracks[0].id,
+  tiktokMusicVolume: 70,            // 0-100, defaults to 50 when music is set
+  tiktokMusicStart: 0,              // ms
+  tiktokMusicEnd: 15000,            // ms
+  tiktokOriginalSoundVolume: 30,    // 0-100, defaults to 50 so the original audio is not muted
+
+  tiktokLocationId: locations[0].location_id,
+  tiktokLocationName: locations[0].location_name, // required together with the id
+
+  tiktokCoverImageUrl: 'https://example.com/cover.jpg',
+  tiktokIsAiGenerated: false,
+  tiktokUploadToDraft: false,       // true sends it to drafts and ignores the rest
+});
+```
+
+### Options
+
+| Option | Type | Notes |
+| --- | --- | --- |
+| `tiktokMusicId` | string | The track `id` from `getTiktokTrendingMusic()` or `searchTiktokMusic()` (not `commercial_music_id`) |
+| `tiktokMusicVolume` | number | 0-100. Defaults to 50 when music is set |
+| `tiktokMusicStart` | number | Music start offset in ms |
+| `tiktokMusicEnd` | number | Music end offset in ms |
+| `tiktokOriginalSoundVolume` | number | 0-100. Defaults to 50 when music is set, so the original audio is not muted |
+| `tiktokLocationId` | string | `location_id` from `getTiktokLocations()` |
+| `tiktokLocationName` | string | Required whenever `tiktokLocationId` is set |
+| `tiktokCoverImageUrl` | string | Custom cover image URL |
+| `tiktokIsAiGenerated` | boolean | AI-generated content disclosure |
+| `tiktokUploadToDraft` | boolean | Publish to drafts; TikTok ignores the rest of the post settings |
+| `tiktokPhotoCoverIndex` | number | Cover photo index for photo posts (0-based) |
+
 ## Platform-Specific Options
 
 ### TikTok (Video)
@@ -310,10 +572,29 @@ const boards = await client.getPinterestBoards('my-profile');
 - `brandContentToggle` - Branded content toggle
 - `brandOrganicToggle` - Brand organic toggle
 
+> **Which privacy levels are available is decided by TikTok per account.** A
+> private account, for example, is offered `FOLLOWER_OF_CREATOR`,
+> `MUTUAL_FOLLOW_FRIENDS` and `SELF_ONLY` and has no `PUBLIC_TO_EVERYONE`.
+> Asking for one the account does not have fails with
+> `error_code: "tiktok_privacy_unavailable"` and an error listing the ones it
+> does have. Omit `tiktokPrivacyLevel` on video and TikTok keeps the account's
+> own default; on **photo** posts it defaults to `PUBLIC_TO_EVERYONE`.
+
+See [TikTok music, location, cover and drafts](#tiktok-music-location-cover-and-drafts)
+for those options.
+
 ### TikTok (Photos)
 - `tiktokAutoAddMusic` - Auto add music
 - `tiktokPhotoCoverIndex` - Index of photo for cover (0-based)
 - `tiktokDisableComment` - Disable comments
+- `tiktokPrivacyLevel` - PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY (same field and same per-account limits as video)
+- `tiktokMusicId` - Commercial Music Library track id (see `getTiktokTrendingMusic`)
+- `tiktokLocationId` / `tiktokLocationName` - Location tag, both required together
+- `tiktokIsAiGenerated` - AI-generated content disclosure
+
+> TikTok's photo contract takes the music track id alone: `tiktokMusicVolume`,
+> `tiktokMusicStart`, `tiktokMusicEnd`, `tiktokOriginalSoundVolume`,
+> `tiktokCoverImageUrl` and `tiktokUploadToDraft` are video-only.
 
 ### Instagram
 - `instagramMediaType` - REELS, STORIES, IMAGE
@@ -393,6 +674,7 @@ These options work across all upload methods:
 | `user` | Profile name (required) |
 | `platforms` | Target platforms array (required) |
 | `firstComment` | First comment to post |
+| `tiktokFirstComment` | First comment for TikTok only (needs the `comments` capability) |
 | `altText` | Alt text for accessibility |
 | `scheduledDate` | ISO date for scheduling |
 | `timezone` | Timezone for scheduled date |

package/index.d.ts

@@ -109,12 +109,22 @@ declare module 'upload-post' {
     youtubeFirstComment?: string;
     redditFirstComment?: string;
     blueskyFirstComment?: string;
+    /**
+     * Needs the `comments` capability on the connection: without it the post
+     * still publishes and the response carries a warning instead of the comment.
+     */
+    tiktokFirstComment?: string;
   }
 
   // ==================== TikTok Options ====================
 
   export interface TikTokVideoOptions {
-    /** Privacy setting */
+    /**
+     * Privacy setting. TikTok decides per account which levels are available (a
+     * private account has no `PUBLIC_TO_EVERYONE`); asking for another one fails
+     * with `error_code: "tiktok_privacy_unavailable"` listing the allowed ones.
+     * Omit it to keep the account's own default.
+     */
     tiktokPrivacyLevel?: TikTokPrivacyLevel;
     /** Disable duet */
     tiktokDisableDuet?: boolean;
@@ -132,6 +142,35 @@ declare module 'upload-post' {
     brandContentToggle?: boolean;
     /** Brand organic toggle */
     brandOrganicToggle?: boolean;
+
+    // ---- Music, location, cover and draft ----
+    // Available on connections that declare the matching capability (`music`,
+    // `location`, `cover_image`, `draft`) — see `capabilities` on the TikTok
+    // account returned by listUsers() / GET /api/uploadposts/users. If your
+    // connection does not have it, the field is ignored, the post still
+    // publishes, and the response includes a per-field `warnings` entry —
+    // reconnect the TikTok account to enable it.
+
+    /** Commercial Music Library track id (see getTiktokTrendingMusic) */
+    tiktokMusicId?: string;
+    /** Music volume, 0-100. Defaults to 50 when music is set */
+    tiktokMusicVolume?: number;
+    /** Music start offset in ms */
+    tiktokMusicStart?: number;
+    /** Music end offset in ms */
+    tiktokMusicEnd?: number;
+    /** Original video audio volume, 0-100. Defaults to 50 when music is set, so the original audio is not muted */
+    tiktokOriginalSoundVolume?: number;
+    /** Location id to tag (see getTiktokLocations) */
+    tiktokLocationId?: string;
+    /** Location name. Required whenever tiktokLocationId is set */
+    tiktokLocationName?: string;
+    /** Custom cover image URL */
+    tiktokCoverImageUrl?: string;
+    /** AI-generated content disclosure */
+    tiktokIsAiGenerated?: boolean;
+    /** Publish to drafts. When true TikTok ignores the rest of the post settings */
+    tiktokUploadToDraft?: boolean;
   }
 
   export interface TikTokPhotoOptions {
@@ -139,16 +178,39 @@ declare module 'upload-post' {
     tiktokAutoAddMusic?: boolean;
     /** Disable comments */
     tiktokDisableComment?: boolean;
-    /** Index of photo for cover (0-based) */
+    /** Index of photo for cover (0-based). Sent as `photo_cover_index` */
     tiktokPhotoCoverIndex?: number;
-    /** Privacy level, e.g. PUBLIC_TO_EVERYONE, SELF_ONLY, MUTUAL_FOLLOW_FRIENDS */
-    tiktokPrivacyLevel?: string;
+    /**
+     * Privacy setting. TikTok REQUIRES one on photo posts, so it defaults to
+     * `PUBLIC_TO_EVERYONE`. Which values the account may use is decided by TikTok
+     * (a private account has no `PUBLIC_TO_EVERYONE`); asking for another one
+     * fails with `error_code: "tiktok_privacy_unavailable"` listing the allowed
+     * ones.
+     */
+    tiktokPrivacyLevel?: TikTokPrivacyLevel;
     /** Post mode, e.g. DIRECT_POST or MEDIA_UPLOAD (inbox) */
     tiktokPostMode?: string;
     /** Branded content toggle */
     brandContentToggle?: boolean;
     /** Brand organic toggle */
     brandOrganicToggle?: boolean;
+
+    // ---- Music, location and AI disclosure ----
+    // Photo posts accept the track id, the location pair and the AI disclosure —
+    // not the volume/trim, cover-image or draft fields, which are video-only.
+    // Available on connections that declare the matching capability (`music`,
+    // `location`) — see `capabilities` on the TikTok account returned by
+    // listUsers(). Without it the field is ignored, the post still publishes, and
+    // the response includes a per-field `warnings` entry.
+
+    /** Commercial Music Library track id (see getTiktokTrendingMusic) */
+    tiktokMusicId?: string;
+    /** Location id to tag (see getTiktokLocations) */
+    tiktokLocationId?: string;
+    /** Location name. Required whenever tiktokLocationId is set */
+    tiktokLocationName?: string;
+    /** AI-generated content disclosure */
+    tiktokIsAiGenerated?: boolean;
   }
 
   // ==================== Instagram Options ====================
@@ -580,6 +642,156 @@ declare module 'upload-post' {
     [key: string]: any;
   }
 
+  /** Trending window accepted by the TikTok Commercial Music Library. */
+  export type TikTokMusicDateRange = '1DAY' | '7DAY' | '30DAY' | '90DAY';
+
+  export interface TikTokMusicTrack {
+    /** Pass this as `tiktokMusicId` on an upload. */
+    id: string;
+    /**
+     * TikTok's catalogue id for the same track, returned for reference only.
+     * Do NOT send it as `tiktokMusicId`: TikTok rejects it on public posts.
+     */
+    commercial_music_id?: string;
+    title?: string;
+    artist?: string;
+    /** Track duration in seconds. */
+    duration?: number;
+    genres?: string[];
+    /** Artwork image URL. */
+    cover_url?: string;
+    /** Audio preview URL. */
+    preview_url?: string;
+    rank?: number;
+    [key: string]: any;
+  }
+
+  export interface TikTokTrendingMusicResponse {
+    success: boolean;
+    tracks?: TikTokMusicTrack[];
+    [key: string]: any;
+  }
+
+  export interface TikTokMusicSearchResponse {
+    success: boolean;
+    /** Matches, ranked by relevance; same shape as the trending endpoint. */
+    tracks?: TikTokMusicTrack[];
+    /** How many tracks matched before `limit` was applied. */
+    total?: number;
+    query?: string;
+    /** What the search actually ran against. */
+    catalog?: {
+      /** Number of tracks in the searched corpus. */
+      tracks_indexed?: number;
+      /** Genre charts currently loaded for this country and period. */
+      genres_indexed?: string[];
+      /** False when this request had to load a chart from TikTok. */
+      cached?: boolean;
+    };
+    [key: string]: any;
+  }
+
+  export interface TikTokLocation {
+    location_id: string;
+    location_name?: string;
+    location_address?: string;
+    [key: string]: any;
+  }
+
+  export interface TikTokLocationsResponse {
+    success: boolean;
+    locations?: TikTokLocation[];
+    [key: string]: any;
+  }
+
+  export interface TikTokPublishingSettingsResponse {
+    success: boolean;
+    /** The privacy levels THIS account may use — a subset of the four. */
+    privacy_level_options?: TikTokPrivacyLevel[];
+    /** Longest video the account can publish, in seconds. */
+    max_video_post_duration_sec?: number;
+    comment_disabled?: boolean;
+    duet_disabled?: boolean;
+    stitch_disabled?: boolean;
+    [key: string]: any;
+  }
+
+  // ==================== Audience, Suggestions and Comment Actions ====================
+
+  /** One row of an audience breakdown: a bucket and its share. */
+  export interface AudienceSlice {
+    name?: string;
+    value?: number;
+    percentage?: number;
+    [key: string]: any;
+  }
+
+  /** Category averages returned when `benchmarkCategory` is asked for. */
+  export interface AudienceBenchmark {
+    category?: string;
+    average_comments?: number;
+    average_engagement_rate?: number;
+    average_follower_count?: number;
+    average_follower_growth?: number;
+    average_likes?: number;
+    average_shares?: number;
+    average_video_count?: number;
+    average_video_views?: number;
+    [key: string]: any;
+  }
+
+  export interface AudienceResponse {
+    success: boolean;
+    platform?: string;
+    /** The window actually used after the 60-day / not-today clamps. */
+    range?: { start_date?: string; end_date?: string };
+    audience?: {
+      countries?: AudienceSlice[];
+      cities?: AudienceSlice[];
+      ages?: AudienceSlice[];
+      genders?: AudienceSlice[];
+    };
+    /** Followers online per hour of the day, e.g. `{ hour: '14', followers_online: 1494 }`. */
+    activity_by_hour?: Array<{ hour?: string; followers_online?: number; [key: string]: any }>;
+    /** Follower count per day inside the window. */
+    followers_daily?: Array<{ date?: string; total?: number; new?: number; lost?: number; [key: string]: any }>;
+    /** Taps on the profile: bio link, address, app download, email, phone, leads. */
+    profile_actions?: Record<string, number>;
+    bio_description?: string | null;
+    /** Every category `benchmarkCategory` accepts, so a picker needs no extra call. */
+    benchmark_categories?: string[];
+    /** Only when a `benchmarkCategory` was asked for. */
+    benchmark?: AudienceBenchmark;
+    [key: string]: any;
+  }
+
+  /** Which kind of suggestion `getSuggestions` asks for. */
+  export type SuggestionType = 'hashtags' | 'keywords';
+
+  export interface SuggestionsResponse {
+    success: boolean;
+    platform?: string;
+    type?: SuggestionType;
+    query?: string | null;
+    /** With `type: 'hashtags'`. */
+    hashtags?: Array<{ name?: string; view_count?: number; [key: string]: any }>;
+    /** With `type: 'keywords'`. */
+    keywords?: Array<Record<string, any>>;
+    [key: string]: any;
+  }
+
+  /** What `commentAction` does to a comment. Each action carries its own inverse. */
+  export type CommentActionValue = 'hide' | 'unhide' | 'like' | 'unlike' | 'pin' | 'unpin';
+
+  export interface CommentActionResponse {
+    success: boolean;
+    platform?: string;
+    action?: CommentActionValue;
+    comment_id?: string;
+    result?: Record<string, any>;
+    [key: string]: any;
+  }
+
   // ==================== Client Class ====================
 
   /**
@@ -675,7 +887,15 @@ declare module 'upload-post' {
     }>;
 
     /**
-     * Get analytics for a specific post across all platforms
+     * Get analytics for a specific post across all platforms.
+     *
+     * `post_metrics` carries whatever the platform reports, so it is not the
+     * same shape everywhere: TikTok adds `retention` (the curve, second by
+     * second), `impression_sources` (For You, search, profile...),
+     * `audience_types` (followers vs non-followers), `new_followers`, `reach`
+     * and the watch times (`average_time_watched`, `total_time_watched`,
+     * `full_video_watched_rate`) on top of the usual counters.
+     *
      * @param requestId - The request_id from the upload
      */
     getPostAnalytics(requestId: string): Promise<{
@@ -685,7 +905,8 @@ declare module 'upload-post' {
         success: boolean;
         platform_post_id?: string;
         post_url?: string;
-        post_metrics?: Record<string, number>;
+        /** Counters plus, on TikTok, retention / impression_sources / audience_types and watch times. */
+        post_metrics?: Record<string, any>;
         post_metrics_source?: string;
         post_metrics_error?: string;
         profile_snapshot_at_post_date?: Record<string, number>;
@@ -737,6 +958,47 @@ declare module 'upload-post' {
       has_more: boolean;
     }>;
 
+    /**
+     * Get who the audience is: where they are, how old they are, when they are
+     * online and what they tap on the profile.
+     *
+     * One endpoint for every platform, chosen with `platform`; a platform that
+     * cannot answer it returns `platform_not_supported` with the list of the
+     * ones that can. The window is clamped server-side to at most 60 days
+     * ending before today.
+     *
+     * @param options - Query options
+     */
+    getAudience(options: {
+      user: string;
+      platform: 'tiktok';
+      /** Window start, ISO `YYYY-MM-DD`. */
+      startDate?: string;
+      /** Window end, ISO `YYYY-MM-DD`. Always clamped to before today. */
+      endDate?: string;
+      /** Compare the account against this category's averages. */
+      benchmarkCategory?: string;
+    }): Promise<AudienceResponse>;
+
+    /**
+     * Get what to write about: the hashtags or the searches a platform
+     * suggests around a keyword.
+     *
+     * One endpoint for both questions, told apart by `type`, and one endpoint
+     * for every platform, chosen with `platform`.
+     *
+     * @param options - Query options
+     */
+    getSuggestions(options: {
+      user: string;
+      platform: 'tiktok';
+      type: SuggestionType;
+      /** Keyword to get suggestions around. */
+      q?: string;
+      countryCode?: string;
+      language?: string;
+    }): Promise<SuggestionsResponse>;
+
     /**
      * Get available metrics configuration for all supported platforms
      */
@@ -888,17 +1150,23 @@ declare module 'upload-post' {
      */
     testNotifications(): Promise<{ success: boolean; [key: string]: any }>;
 
-    // Instagram Comments
+    // Comments
 
     /**
-     * Get comments on a post
+     * Get comments on a post, or the replies hanging from one of them.
+     *
+     * Pass `commentId` to read that comment's replies instead of the post's
+     * top-level comments.
+     *
      * @param options - Query options
      */
     getPostComments(options: {
       user: string;
-      platform?: 'instagram' | 'facebook' | 'youtube' | 'linkedin';
+      platform?: 'instagram' | 'facebook' | 'youtube' | 'linkedin' | 'tiktok';
       postId?: string;
       postUrl?: string;
+      /** Read the replies to this comment instead of the post's top-level comments. */
+      commentId?: string;
       limit?: number;
       after?: string;
     }): Promise<{
@@ -955,7 +1223,7 @@ declare module 'upload-post' {
      */
     createComment(options: {
       user: string;
-      platform: 'instagram' | 'facebook' | 'youtube' | 'linkedin';
+      platform: 'instagram' | 'facebook' | 'youtube' | 'linkedin' | 'tiktok';
       message: string;
       postId?: string;
       postUrl?: string;
@@ -973,7 +1241,7 @@ declare module 'upload-post' {
      */
     deleteComment(options: {
       user: string;
-      platform: 'instagram' | 'facebook' | 'youtube' | 'linkedin';
+      platform: 'instagram' | 'facebook' | 'youtube' | 'linkedin' | 'tiktok';
       commentId: string;
       /** Post identifier (the post URN for LinkedIn) */
       postId?: string;
@@ -983,6 +1251,24 @@ declare module 'upload-post' {
       error?: string;
     }>;
 
+    /**
+     * Moderate a comment: hide, like or pin it — and undo any of the three.
+     *
+     * One method for every platform, chosen with `platform`. `postId` is
+     * required for hide/unhide and pin/unpin; like/unlike take the comment
+     * alone and never send it.
+     *
+     * @param options - Action options
+     */
+    commentAction(options: {
+      user: string;
+      platform: 'tiktok';
+      commentId: string;
+      action: CommentActionValue;
+      /** Required for hide/unhide and pin/unpin; never sent for like/unlike. */
+      postId?: string;
+    }): Promise<CommentActionResponse>;
+
     // Post Management
     /**
      * Retry a failed post. Provide requestId or jobId.
@@ -1048,6 +1334,76 @@ declare module 'upload-post' {
      * @param profile - Profile username
      */
     getGoogleBusinessLocations(profile?: string): Promise<Record<string, unknown>>;
+
+    /**
+     * Get trending tracks from the TikTok Commercial Music Library.
+     *
+     * Available on connections that declare the `music` capability (see
+     * `capabilities` on the TikTok account returned by listUsers() /
+     * GET /api/uploadposts/users). Pass the returned `id` as `tiktokMusicId`
+     * on an upload (NOT `commercial_music_id` — TikTok rejects that one on
+     * public posts).
+     *
+     * @param profile - Profile username
+     * @param options - Query options
+     */
+    getTiktokTrendingMusic(
+      profile: string,
+      options?: {
+        genre?: string;
+        countryCode?: string;
+        dateRange?: TikTokMusicDateRange;
+      }
+    ): Promise<TikTokTrendingMusicResponse>;
+
+    /**
+     * Search the TikTok Commercial Music Library by song title or artist.
+     *
+     * TikTok has no music search endpoint, so this searches the trending charts
+     * Upload-Post caches (per genre / country / period), not TikTok's whole
+     * catalogue. Matching is case- and accent-insensitive and every word must
+     * match. Returns the same track objects as getTiktokTrendingMusic().
+     *
+     * @param profile - Profile username
+     * @param options - Query options
+     */
+    searchTiktokMusic(
+      profile: string,
+      options?: {
+        q?: string;
+        genre?: string;
+        countryCode?: string;
+        dateRange?: TikTokMusicDateRange;
+        limit?: number;
+      }
+    ): Promise<TikTokMusicSearchResponse>;
+
+    /**
+     * Search TikTok locations (places) to tag on a post.
+     *
+     * Available on connections that declare the `location` capability (see
+     * `capabilities` on the TikTok account returned by listUsers() /
+     * GET /api/uploadposts/users). TikTok requires both the id and the name, so
+     * pass `location_id` as `tiktokLocationId` and `location_name` as
+     * `tiktokLocationName`.
+     *
+     * @param profile - Profile username
+     * @param query - Search query (max 100 characters)
+     */
+    getTiktokLocations(profile: string, query: string): Promise<TikTokLocationsResponse>;
+
+    /**
+     * Get what the connected TikTok account is allowed to publish.
+     *
+     * The point of this call is `privacy_level_options`: TikTok narrows the four
+     * privacy values per account (a private account has no `PUBLIC_TO_EVERYONE`),
+     * and sending one the account does not have fails the upload with
+     * `error_code: "tiktok_privacy_unavailable"`. Ask here to offer only the
+     * values that will work, instead of the full enum.
+     *
+     * @param profile - Profile username
+     */
+    getTiktokPublishingSettings(profile: string): Promise<TikTokPublishingSettingsResponse>;
   }
 
   export default UploadPost;

package/index.js

@@ -128,6 +128,10 @@ export class UploadPost {
     if (options.redditFirstComment) form.append('reddit_first_comment', options.redditFirstComment);
     if (options.blueskyFirstComment) form.append('bluesky_first_comment', options.blueskyFirstComment);
     if (options.linkedinFirstComment) form.append('linkedin_first_comment', options.linkedinFirstComment);
+    // TikTok takes a first comment like everyone else. It needs the `comments`
+    // capability on the connection: without it the post still publishes and the
+    // response carries a warning instead of the comment.
+    if (options.tiktokFirstComment) form.append('tiktok_first_comment', options.tiktokFirstComment);
 
     if (options.firstCommentMedia) {
       const mediaItems = Array.isArray(options.firstCommentMedia) ? options.firstCommentMedia : [options.firstCommentMedia];
@@ -152,25 +156,54 @@ export class UploadPost {
    * @private
    */
   _addTiktokParams(form, options, isVideo = true) {
-    if (options.tiktokDisableComment !== undefined) form.append('disable_comment', String(options.tiktokDisableComment));
-    if (options.brandContentToggle !== undefined) form.append('brand_content_toggle', String(options.brandContentToggle));
-    if (options.brandOrganicToggle !== undefined) form.append('brand_organic_toggle', String(options.brandOrganicToggle));
-
-    // Shared by TikTok video AND photo uploads: the backend reads privacy_level and
-    // post_mode for both /upload and /upload_photos. Gating them behind isVideo made
-    // photo carousels always publish as PUBLIC_TO_EVERYONE / DIRECT_POST.
-    if (options.tiktokPrivacyLevel) form.append('privacy_level', options.tiktokPrivacyLevel);
-    if (options.tiktokPostMode) form.append('post_mode', options.tiktokPostMode);
-
-    if (isVideo) {
-      if (options.tiktokDisableDuet !== undefined) form.append('disable_duet', String(options.tiktokDisableDuet));
-      if (options.tiktokDisableStitch !== undefined) form.append('disable_stitch', String(options.tiktokDisableStitch));
-      if (options.tiktokCoverTimestamp !== undefined) form.append('cover_timestamp', options.tiktokCoverTimestamp);
-      if (options.tiktokIsAigc !== undefined) form.append('is_aigc', String(options.tiktokIsAigc));
-    } else {
-      // Photo-specific
-      if (options.tiktokAutoAddMusic !== undefined) form.append('auto_add_music', String(options.tiktokAutoAddMusic));
-      if (options.tiktokPhotoCoverIndex !== undefined) form.append('photo_cover_index', options.tiktokPhotoCoverIndex);
+    // [form field, option key, "flag" when the value is a boolean/number sent as
+    // soon as it is defined, "text" when an empty value means "not set"].
+    //
+    // The shared block is shared on purpose: the backend reads privacy_level and
+    // post_mode on both /upload and /upload_photos, and TikTok's photo endpoint
+    // also accepts the music track id, the location pair and is_ai_generated.
+    // Gating them behind isVideo made photo carousels always publish as
+    // PUBLIC_TO_EVERYONE / DIRECT_POST and unable to carry music or a location.
+    //
+    // The music/location/cover/draft fields need the matching capability on the
+    // connection (see `capabilities` on the TikTok account returned by
+    // listUsers() / GET /api/uploadposts/users). Without it the field is ignored,
+    // the post still publishes, and the response carries a per-field `warnings`
+    // entry.
+    const shared = [
+      ['disable_comment', 'tiktokDisableComment', 'flag'],
+      ['brand_content_toggle', 'brandContentToggle', 'flag'],
+      ['brand_organic_toggle', 'brandOrganicToggle', 'flag'],
+      ['privacy_level', 'tiktokPrivacyLevel', 'text'],
+      ['post_mode', 'tiktokPostMode', 'text'],
+      ['tiktok_music_id', 'tiktokMusicId', 'text'],
+      ['tiktok_location_id', 'tiktokLocationId', 'text'],
+      ['tiktok_location_name', 'tiktokLocationName', 'text'],
+      ['tiktok_is_ai_generated', 'tiktokIsAiGenerated', 'flag'],
+    ];
+    // Video-only: TikTok's photo contract takes the track id alone, with no
+    // volume or trim, and has no custom cover or draft switch.
+    const videoOnly = [
+      ['disable_duet', 'tiktokDisableDuet', 'flag'],
+      ['disable_stitch', 'tiktokDisableStitch', 'flag'],
+      ['cover_timestamp', 'tiktokCoverTimestamp', 'flag'],
+      ['is_aigc', 'tiktokIsAigc', 'flag'],
+      ['tiktok_music_volume', 'tiktokMusicVolume', 'flag'],
+      ['tiktok_music_start', 'tiktokMusicStart', 'flag'],
+      ['tiktok_music_end', 'tiktokMusicEnd', 'flag'],
+      ['tiktok_original_sound_volume', 'tiktokOriginalSoundVolume', 'flag'],
+      ['tiktok_cover_image_url', 'tiktokCoverImageUrl', 'text'],
+      ['tiktok_upload_to_draft', 'tiktokUploadToDraft', 'flag'],
+    ];
+    const photoOnly = [
+      ['auto_add_music', 'tiktokAutoAddMusic', 'flag'],
+      ['photo_cover_index', 'tiktokPhotoCoverIndex', 'flag'],
+    ];
+
+    for (const [field, key, kind] of shared.concat(isVideo ? videoOnly : photoOnly)) {
+      const value = options[key];
+      if (kind === 'flag' ? value === undefined : !value) continue;
+      form.append(field, String(value));
     }
   }
 
@@ -401,7 +434,7 @@ export class UploadPost {
    * @param {boolean} [options.asyncUpload=true] - Process upload asynchronously
    * 
    * TikTok options:
-   * @param {string} [options.tiktokPrivacyLevel] - PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY
+   * @param {string} [options.tiktokPrivacyLevel] - PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY. TikTok decides per account which of these are available (a private account has no PUBLIC_TO_EVERYONE); asking for another one fails with error_code tiktok_privacy_unavailable listing the allowed ones. Omit it to keep the account's own default.
    * @param {boolean} [options.tiktokDisableDuet] - Disable duet
    * @param {boolean} [options.tiktokDisableComment] - Disable comments
    * @param {boolean} [options.tiktokDisableStitch] - Disable stitch
@@ -410,7 +443,24 @@ export class UploadPost {
    * @param {string} [options.tiktokPostMode] - DIRECT_POST or MEDIA_UPLOAD
    * @param {boolean} [options.brandContentToggle] - Branded content toggle
    * @param {boolean} [options.brandOrganicToggle] - Brand organic toggle
-   * 
+   *
+   * TikTok music, location, cover and draft options. Available on connections that
+   * declare the matching `capabilities` (music, location, cover_image, draft) on the
+   * TikTok account returned by listUsers() / GET /api/uploadposts/users. If your
+   * connection does not have it, the field is ignored, the post still publishes, and
+   * the response includes a per-field `warnings` entry — reconnect the TikTok account
+   * to enable it.
+   * @param {string} [options.tiktokMusicId] - Commercial Music Library track id (see getTiktokTrendingMusic)
+   * @param {number} [options.tiktokMusicVolume] - Music volume 0-100 (defaults to 50 when music is set)
+   * @param {number} [options.tiktokMusicStart] - Music start offset in ms
+   * @param {number} [options.tiktokMusicEnd] - Music end offset in ms
+   * @param {number} [options.tiktokOriginalSoundVolume] - Original video audio volume 0-100 (defaults to 50 when music is set, so the original audio is not muted)
+   * @param {string} [options.tiktokLocationId] - Location id (see getTiktokLocations)
+   * @param {string} [options.tiktokLocationName] - Location name, required whenever tiktokLocationId is set
+   * @param {string} [options.tiktokCoverImageUrl] - Custom cover image URL
+   * @param {boolean} [options.tiktokIsAiGenerated] - AI-generated content disclosure
+   * @param {boolean} [options.tiktokUploadToDraft] - Publish to drafts. When true TikTok ignores the rest of the post settings
+   *
    * Instagram options:
    * @param {string} [options.instagramMediaType] - REELS or STORIES
    * @param {boolean} [options.instagramShareToFeed] - Share to feed
@@ -521,10 +571,22 @@ export class UploadPost {
    * TikTok options:
    * @param {boolean} [options.tiktokAutoAddMusic] - Auto add music
    * @param {boolean} [options.tiktokDisableComment] - Disable comments
-   * @param {number} [options.tiktokPhotoCoverIndex] - Index of photo for cover (0-based)
+   * @param {number} [options.tiktokPhotoCoverIndex] - Index of photo for cover (0-based). Sent as `photo_cover_index`
+   * @param {string} [options.tiktokPrivacyLevel] - PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR, SELF_ONLY. TikTok requires one on photo posts, so it defaults to PUBLIC_TO_EVERYONE; asking for one the account does not have fails with error_code tiktok_privacy_unavailable listing the allowed ones.
    * @param {boolean} [options.brandContentToggle] - Branded content toggle
    * @param {boolean} [options.brandOrganicToggle] - Brand organic toggle
-   * 
+   *
+   * TikTok music, location and AI disclosure on photo posts. TikTok's photo contract
+   * takes the track id alone — no volume/trim, no custom cover, no draft (those are
+   * video-only). Available on connections that declare the matching `capabilities`
+   * (music, location) on the TikTok account returned by listUsers(); otherwise the
+   * field is ignored, the post still publishes, and the response includes a
+   * per-field `warnings` entry.
+   * @param {string} [options.tiktokMusicId] - Commercial Music Library track id (see getTiktokTrendingMusic)
+   * @param {string} [options.tiktokLocationId] - Location id (see getTiktokLocations)
+   * @param {string} [options.tiktokLocationName] - Location name, required whenever tiktokLocationId is set
+   * @param {boolean} [options.tiktokIsAiGenerated] - AI-generated content disclosure
+   *
    * Instagram options:
    * @param {string} [options.instagramMediaType] - IMAGE or STORIES
    * @param {string} [options.instagramCollaborators] - Comma-separated collaborator usernames
@@ -797,6 +859,13 @@ export class UploadPost {
   /**
    * Get analytics for a specific post across all platforms it was published to
    *
+   * `post_metrics` carries whatever the platform reports, so it is not the same
+   * shape everywhere: on TikTok it also brings `retention` (the curve, second
+   * by second), `impression_sources` (For You, search, profile...),
+   * `audience_types` (followers vs non-followers), `new_followers`, `reach` and
+   * the watch times (`average_time_watched`, `total_time_watched`,
+   * `full_video_watched_rate`).
+   *
    * @param {string} requestId - The request_id from the upload
    * @returns {Promise<Object>} Post analytics with per-platform metrics
    */
@@ -847,6 +916,73 @@ export class UploadPost {
     return this._request('/uploadposts/post-analytics/cached', 'GET', params);
   }
 
+  /**
+   * Get who the audience is: where they are, how old they are, when they are
+   * online and what they tap on the profile.
+   *
+   * Where the post-analytics methods answer *how did my posts do*, this one
+   * answers *who is following me*. It is one endpoint for every platform,
+   * chosen with `platform` — a platform that cannot answer it comes back with
+   * `platform_not_supported` and the list of the ones that can.
+   *
+   * The window is clamped server-side: at most 60 days, and `endDate` always
+   * before today. A wider window is trimmed rather than rejected.
+   *
+   * Pass `benchmarkCategory` to also get the averages of that category next to
+   * the account's own numbers; the accepted values come back in
+   * `benchmark_categories` on every response, so a picker needs no extra call.
+   *
+   * @param {Object} options - Query options
+   * @param {string} options.user - Profile username
+   * @param {string} options.platform - Platform to ask (tiktok)
+   * @param {string} [options.startDate] - Window start, ISO `YYYY-MM-DD`
+   * @param {string} [options.endDate] - Window end, ISO `YYYY-MM-DD`
+   * @param {string} [options.benchmarkCategory] - Category to compare the account
+   *   against, e.g. `SOFTWARE_AND_APPS`
+   * @returns {Promise<Object>} `range`, `audience` (countries, cities, ages, genders),
+   *   `activity_by_hour`, `followers_daily`, `profile_actions`, `bio_description`,
+   *   `benchmark_categories` and, with a category, `benchmark`
+   */
+  async getAudience(options = {}) {
+    const params = { user: options.user, platform: options.platform };
+    if (options.startDate) params.start_date = options.startDate;
+    if (options.endDate) params.end_date = options.endDate;
+    if (options.benchmarkCategory) params.benchmark_category = options.benchmarkCategory;
+    return this._request('/uploadposts/audience', 'GET', params);
+  }
+
+  /**
+   * Get what to write about: the hashtags or the searches a platform suggests
+   * around a keyword.
+   *
+   * One endpoint for both questions, told apart by `type`:
+   *
+   *   type        answers
+   *   hashtags    `{ hashtags: [{ name, view_count }] }`
+   *   keywords    `{ keywords: [...] }`
+   *
+   * Chosen with `platform`, like every other question in the API — a platform
+   * that cannot answer it comes back with `platform_not_supported` and the list
+   * of the ones that can.
+   *
+   * @param {Object} options - Query options
+   * @param {string} options.user - Profile username
+   * @param {string} options.platform - Platform to ask (tiktok)
+   * @param {('hashtags'|'keywords')} options.type - Which suggestions you want
+   * @param {string} [options.q] - Keyword to get suggestions around
+   * @param {string} [options.countryCode] - ISO country code to bias the suggestions
+   * @param {string} [options.language] - Language code to bias the suggestions
+   * @returns {Promise<Object>} `{ success, platform, type, hashtags }` or
+   *   `{ success, platform, type, keywords }`
+   */
+  async getSuggestions(options = {}) {
+    const params = { user: options.user, platform: options.platform, type: options.type };
+    if (options.q) params.q = options.q;
+    if (options.countryCode) params.country_code = options.countryCode;
+    if (options.language) params.language = options.language;
+    return this._request('/uploadposts/suggestions', 'GET', params);
+  }
+
   /**
    * Get available metrics configuration for all supported platforms
    *
@@ -1056,16 +1192,28 @@ export class UploadPost {
     return this._request('/uploadposts/users/notifications/test', 'POST', {});
   }
 
-  // ==================== Instagram Comments ====================
+  // ==================== Comments ====================
 
   /**
-   * Get comments on a post
+   * Get comments on a post, or the replies hanging from one of them
+   *
+   * Pass `commentId` to read the replies to that comment instead of the
+   * post's top-level comments. It is the same question — *what was said
+   * here* — so it is the same endpoint with one more parameter, not a
+   * separate method per platform.
+   *
+   * On TikTok this needs the `comments` capability on the connection (see
+   * `capabilities` on the TikTok account returned by listUsers()). TikTok grants
+   * it at connect time, so an account connected earlier has to be reconnected.
    *
    * @param {Object} options - Query options
    * @param {string} options.user - Profile username
-   * @param {string} [options.platform='instagram'] - Platform (instagram, facebook, youtube, linkedin)
-   * @param {string} [options.postId] - Native post/media ID (provide postId or postUrl)
+   * @param {string} [options.platform='instagram'] - Platform (instagram, facebook, youtube, linkedin, tiktok)
+   * @param {string} [options.postId] - Native post/media ID (provide postId or postUrl).
+   *   Required on TikTok, which has no post URL lookup.
    * @param {string} [options.postUrl] - Full post URL (provide postId or postUrl)
+   * @param {string} [options.commentId] - Read the replies to this comment instead
+   *   of the post's top-level comments
    * @param {number} [options.limit] - Max number of comments to return
    * @param {string} [options.after] - Pagination cursor for the next page
    * @returns {Promise<Object>} Comments data
@@ -1078,6 +1226,7 @@ export class UploadPost {
     const params = { platform: options.platform || 'instagram', user: options.user };
     if (options.postId) params.post_id = options.postId;
     if (options.postUrl) params.post_url = options.postUrl;
+    if (options.commentId) params.comment_id = options.commentId;
     if (options.limit !== undefined) params.limit = options.limit;
     if (options.after) params.after = options.after;
     return this._request('/uploadposts/comments', 'GET', params);
@@ -1129,9 +1278,13 @@ export class UploadPost {
    * One of postId, postUrl, or commentId is required. Pass commentId to reply
    * to an existing comment; pass postId/postUrl to comment on the post itself.
    *
+   * On TikTok this needs the `comments` capability on the connection (see
+   * `capabilities` on the TikTok account returned by listUsers()). TikTok grants
+   * it at connect time, so an account connected earlier has to be reconnected.
+   *
    * @param {Object} options - Comment options
    * @param {string} options.user - Profile username
-   * @param {string} options.platform - Platform (instagram, facebook, youtube, linkedin)
+   * @param {string} options.platform - Platform (instagram, facebook, youtube, linkedin, tiktok)
    * @param {string} options.message - Comment text
    * @param {string} [options.postId] - Native post/media ID to comment on
    * @param {string} [options.postUrl] - Full post URL to comment on
@@ -1153,9 +1306,13 @@ export class UploadPost {
   /**
    * Delete a comment on a post
    *
+   * On TikTok this needs the `comments` capability on the connection (see
+   * `capabilities` on the TikTok account returned by listUsers()). TikTok grants
+   * it at connect time, so an account connected earlier has to be reconnected.
+   *
    * @param {Object} options - Delete options
    * @param {string} options.user - Profile username
-   * @param {string} options.platform - Platform (instagram, facebook, youtube, linkedin)
+   * @param {string} options.platform - Platform (instagram, facebook, youtube, linkedin, tiktok)
    * @param {string} options.commentId - Comment ID to delete
    * @param {string} [options.postId] - Post identifier (the post URN for LinkedIn)
    * @returns {Promise<Object>} Deletion result
@@ -1170,6 +1327,43 @@ export class UploadPost {
     return this._request('/uploadposts/comments/delete', 'DELETE', body);
   }
 
+  /**
+   * Moderate a comment: hide, like or pin it — and undo any of the three
+   *
+   * One method for every platform, because it is one question: *do this to
+   * that comment*. Each action carries its own inverse:
+   *
+   *   action              post_id
+   *   hide / unhide       required
+   *   like / unlike       not sent (the platform likes the comment on its own)
+   *   pin / unpin         required
+   *
+   * On TikTok this needs the `comments` capability on the connection (see
+   * `capabilities` on the TikTok account returned by listUsers()). TikTok grants
+   * it at connect time, so an account connected earlier has to be reconnected.
+   *
+   * @param {Object} options - Action options
+   * @param {string} options.user - Profile username
+   * @param {string} options.platform - Platform (tiktok)
+   * @param {string} options.commentId - Comment to act on
+   * @param {('hide'|'unhide'|'like'|'unlike'|'pin'|'unpin')} options.action - What to do
+   * @param {string} [options.postId] - Native post ID. Required for hide/unhide and
+   *   pin/unpin; never sent for like/unlike.
+   * @returns {Promise<Object>} `{ success, platform, action, comment_id, result }`
+   */
+  async commentAction(options) {
+    const body = {
+      platform: options.platform,
+      user: options.user,
+      comment_id: options.commentId,
+      action: options.action
+    };
+    // Liking takes the comment alone; hiding and pinning need the post too.
+    const likes = options.action === 'like' || options.action === 'unlike';
+    if (!likes && options.postId) body.post_id = options.postId;
+    return this._request('/uploadposts/comments/action', 'POST', body);
+  }
+
   // ==================== Post Management ====================
 
   /**
@@ -1242,6 +1436,102 @@ export class UploadPost {
     return this._request('/uploadposts/pinterest/boards', 'GET', params);
   }
 
+  /**
+   * Catalogue filters shared by the trending and search endpoints, so both
+   * address the same cached chart slice.
+   * @private
+   */
+  _tiktokMusicParams(profile, options = {}) {
+    const params = { profile };
+    if (options.genre) params.genre = options.genre;
+    if (options.countryCode) params.country_code = options.countryCode;
+    if (options.dateRange) params.date_range = options.dateRange;
+    return params;
+  }
+
+  /**
+   * Get trending tracks from the TikTok Commercial Music Library.
+   *
+   * Available on connections that declare the `music` capability (see
+   * `capabilities` on the TikTok account returned by listUsers() /
+   * GET /api/uploadposts/users). The returned `id` is what you pass as
+   * `tiktokMusicId` on an upload — not `commercial_music_id`, which TikTok
+   * rejects on public posts.
+   *
+   * @param {string} profile - Profile username
+   * @param {Object} [options] - Query options
+   * @param {string} [options.genre] - Genre filter (e.g. ALL, POP). Defaults to ALL upstream.
+   * @param {string} [options.countryCode] - ISO country code. Defaults to US upstream.
+   * @param {('1DAY'|'7DAY'|'30DAY'|'90DAY')} [options.dateRange] - Trending window. Defaults to 7DAY upstream.
+   * @returns {Promise<Object>} Trending tracks
+   */
+  async getTiktokTrendingMusic(profile, options = {}) {
+    return this._request('/uploadposts/tiktok/music/trending', 'GET',
+      this._tiktokMusicParams(profile, options));
+  }
+
+  /**
+   * Search the TikTok Commercial Music Library by song title or artist.
+   *
+   * TikTok itself has no music search endpoint — its only catalogue read is the
+   * trending chart for a genre/country/period. Upload-Post caches those charts
+   * and matches your text against them, so this searches the trending charts,
+   * not TikTok's whole catalogue. Matching is case- and accent-insensitive and
+   * every word must match.
+   *
+   * Returns the same track objects as getTiktokTrendingMusic(), so the `id` is
+   * again what you pass as `tiktokMusicId` on an upload.
+   *
+   * @param {string} profile - Profile username
+   * @param {Object} [options] - Query options
+   * @param {string} [options.q] - Text matched against titles and artists (max 80 chars). Omit for the chart in trending order.
+   * @param {string} [options.genre] - Genre filter (e.g. ALL, POP). Defaults to ALL upstream.
+   * @param {string} [options.countryCode] - ISO country code choosing which chart is searched. Defaults to US upstream.
+   * @param {('1DAY'|'7DAY'|'30DAY'|'90DAY')} [options.dateRange] - Chart window. Defaults to 7DAY upstream.
+   * @param {number} [options.limit] - Maximum tracks to return (capped at 100 upstream).
+   * @returns {Promise<Object>} Matching tracks plus a `catalog` block describing the corpus searched
+   */
+  async searchTiktokMusic(profile, options = {}) {
+    const params = this._tiktokMusicParams(profile, options);
+    if (options.q) params.q = options.q;
+    if (options.limit !== undefined && options.limit !== null) params.limit = options.limit;
+    return this._request('/uploadposts/tiktok/music/search', 'GET', params);
+  }
+
+  /**
+   * Search TikTok locations (places) to tag on a post.
+   *
+   * Available on connections that declare the `location` capability (see
+   * `capabilities` on the TikTok account returned by listUsers() /
+   * GET /api/uploadposts/users). Pass the returned `location_id` as
+   * `tiktokLocationId` and `location_name` as `tiktokLocationName` on an upload;
+   * TikTok requires both together.
+   *
+   * @param {string} profile - Profile username
+   * @param {string} query - Search query (max 100 characters)
+   * @returns {Promise<Object>} Matching locations (up to 20)
+   */
+  async getTiktokLocations(profile, query) {
+    return this._request('/uploadposts/tiktok/locations', 'GET', { profile, q: query });
+  }
+
+  /**
+   * Get what the connected TikTok account is allowed to publish.
+   *
+   * The point of this call is `privacy_level_options`: TikTok narrows the four
+   * privacy values per account (a private account has no `PUBLIC_TO_EVERYONE`),
+   * and sending one the account does not have fails the upload with
+   * `error_code: "tiktok_privacy_unavailable"`. Ask here to offer only the
+   * values that will work, instead of the full enum.
+   *
+   * @param {string} profile - Profile username
+   * @returns {Promise<Object>} privacy_level_options, max_video_post_duration_sec
+   *   and the account's comment/duet/stitch switches
+   */
+  async getTiktokPublishingSettings(profile) {
+    return this._request('/uploadposts/tiktok/settings', 'GET', { profile });
+  }
+
   /**
    * Get Google Business Profile locations for a connected account
    *

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "upload-post",
-  "version": "2.9.0",
+  "version": "2.12.0",
   "description": "Official client library for Upload-Post API - Cross-platform social media upload for TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, and X (Twitter)",
   "main": "index.js",
   "types": "index.d.ts",
   "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node --test test/"
   },
   "license": "MIT",
   "keywords": [