upload-post 2.9.0 → 2.10.0

package/README.md

@@ -295,8 +295,80 @@ 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');
+```
+
+## TikTok music, location, cover and drafts
+
+> **Capabilities.** These options are available on connections that declare the
+> matching capability — `music`, `location`, `cover_image`, `draft` — in the
+> `capabilities` array of the TikTok account returned by `listUsers()`
+> (other values you may see there: `cover_timestamp`, `photo_privacy`,
+> `video_privacy`, `inbox_fallback`, `profile_analytics`)
+> (`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.
+
+```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 +382,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

package/index.d.ts

@@ -114,7 +114,12 @@ declare module 'upload-post' {
   // ==================== 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 +137,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 +173,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 +637,80 @@ 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;
+  }
+
   // ==================== Client Class ====================
 
   /**
@@ -1048,6 +1179,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

@@ -152,25 +152,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 +430,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 +439,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 +567,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
@@ -1242,6 +1300,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,6 +1,6 @@
 {
   "name": "upload-post",
-  "version": "2.9.0",
+  "version": "2.10.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",