upload-post 2.8.1 → 2.10.0

package/README.md

@@ -39,6 +39,38 @@ console.log(response);
 - ✅ **Analytics** - Get engagement metrics
 - ✅ **Full TypeScript Support**
 
+## Using this from an AI agent? Use the MCP server instead
+
+If you are wiring Upload-Post into ChatGPT, Claude, Cursor, Claude Code or any
+other MCP-compatible agent, you do not need to write a client on top of this
+SDK. The official **[Model Context Protocol server](https://github.com/Upload-Post/upload-post-mcp)**
+already wraps the whole API as 50 tools the agent can call directly.
+
+```jsonc
+// Hosted (OAuth or API key) — nothing to install
+{
+  "mcpServers": {
+    "upload-post": { "url": "https://mcp.upload-post.com/mcp" }
+  }
+}
+```
+
+```jsonc
+// Local stdio, built on this SDK
+{
+  "mcpServers": {
+    "upload-post": {
+      "command": "npx",
+      "args": ["-y", "@upload-post/mcp"],
+      "env": { "UPLOAD_POST_API_KEY": "YOUR_API_KEY" }
+    }
+  }
+}
+```
+
+See the [MCP integration guide](https://docs.upload-post.com/guides/mcp-server-integration).
+Keep using this SDK when you are writing your own application code.
+
 ## API Reference
 
 ### Upload Video
@@ -170,9 +202,16 @@ const jwt = await client.generateJwt('my-profile', {
   redirectUrl: 'https://yourapp.com/callback',
   platforms: ['tiktok', 'instagram'],
   // Optional: force the connection page language for this profile.
-  // Supported: 'en' | 'es' | 'de' | 'fr' | 'pt'. When omitted, the page
-  // auto-detects the visitor's browser language and falls back to English.
+  // Supported: 'en' | 'es' | 'de' | 'fr' | 'pt' | 'pl' | 'tr'. When omitted, the
+  // page auto-detects the visitor's browser language and falls back to English.
   language: 'es',
+  // Optional: override individual connection-page strings. Flat object of i18n
+  // dot-path keys to strings. Max 100 entries, keys ^[a-zA-Z0-9_.]+$, values
+  // up to 300 chars. Echoed back in the `profile` object of validateJwt.
+  uiLabels: {
+    'connect.title': 'Link your accounts',
+    'connect.subtitle': 'Publish everywhere from one place',
+  },
 });
 ```
 
@@ -183,6 +222,34 @@ const analytics = await client.getAnalytics('my-profile', {
   platforms: ['instagram', 'tiktok'],
 });
 console.log(analytics);
+
+// Instagram returns two audience breakdowns with the same shape
+// ({ age, gender, country, city }):
+console.log(analytics.analytics.instagram.follower_demographics);
+console.log(analytics.analytics.instagram.engaged_audience_demographics);
+```
+
+### Cached Post Analytics
+
+Replays per-post metrics already fetched, instead of calling the platforms again. Only contains posts previously fetched through a live per-post endpoint; there is no background refresh, so captured_at is the last time that post was read live. Not subject to the live
+calls, so it is not subject to the live post-analytics rate limit
+(100 requests / 5 minutes). Use it to page through a profile's post history.
+
+```javascript
+let cursor;
+do {
+  const page = await client.getCachedPostAnalytics('my-profile', {
+    platform: 'youtube',   // optional: instagram, tiktok, youtube, facebook, linkedin, threads, pinterest, reddit
+    limit: 50,             // default 50, max 200
+    since: '2026-06-01',   // defaults to 30 days ago
+    until: '2026-07-01',   // defaults to today
+    cursor,
+  });
+  for (const post of page.posts) {
+    console.log(post.platform, post.post_id, post.metrics);
+  }
+  cursor = page.next_cursor;
+} while (cursor);
 ```
 
 ### Get Media
@@ -201,6 +268,22 @@ await client.getMedia('linkedin', 'my-profile', { pageUrn: 'me' });
 await client.getMedia('linkedin', 'my-profile', { pageUrn: '12345' });
 ```
 
+The response carries a `pagination` object — `{ limit, next_cursor, has_more }`,
+with `next_cursor: null` and `has_more: false` on the last page:
+
+```javascript
+let cursor;
+do {
+  const page = await client.getMedia('instagram', 'my-profile', { limit: 50, cursor });
+  console.log(page.media.length);
+  cursor = page.pagination.next_cursor;
+} while (cursor);
+```
+
+`limit` defaults to 25 and is clamped to 1-100, with per-platform caps of 20 for
+TikTok and 50 for YouTube. **LinkedIn, Discord and Telegram do not support
+cursors** — they accept `limit` only, and passing a `cursor` returns HTTP 400.
+
 ### Helper Methods
 
 ```javascript
@@ -212,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)
@@ -227,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
@@ -350,6 +524,22 @@ await client.uploadText({
 
 Also available: `gbpTopicType: 'EVENT'` with `gbpEventTitle` / `gbpEventStartDate` / `gbpEventStartTime` / `gbpEventEndDate` / `gbpEventEndTime`, a call-to-action via `gbpCtaType` + `gbpCtaUrl`, and `gbpMediaUrl` / `gbpMediaFormat`.
 
+### Gallery photos
+
+Set `gbpPostType` to publish straight into the location's photo gallery instead of creating a Local Post:
+
+```javascript
+await client.uploadPhotos(['storefront.jpg'], {
+  user: 'myprofile',
+  platforms: ['google_business'],
+  gbpLocationId: locations[0].name,
+  gbpPostType: 'GALLERY',        // MEDIA | PHOTO | GALLERY
+  gbpMediaCategory: 'EXTERIOR',  // defaults to ADDITIONAL
+});
+```
+
+Omitting `gbpPostType` (or sending any other value) keeps the existing Local Post behaviour. `gbpMediaCategory` accepts `COVER`, `PROFILE`, `LOGO`, `EXTERIOR`, `INTERIOR`, `PRODUCT`, `AT_WORK`, `FOOD_AND_DRINK`, `MENU`, `COMMON_AREA`, `ROOMS`, `TEAMS` and `ADDITIONAL`.
+
 ## Retrying an upload safely
 
 An upload that times out may still have been accepted by the API. Retrying it without an idempotency key publishes the post a second time.
@@ -407,6 +597,7 @@ try {
 - [Upload-Post Website](https://www.upload-post.com)
 - [API Documentation](https://docs.upload-post.com)
 - [Dashboard](https://app.upload-post.com)
+- [MCP Server](https://www.upload-post.com/mcp) — connect ChatGPT, Claude, Cursor and any AI agent ([source](https://github.com/Upload-Post/upload-post-mcp), [npm](https://www.npmjs.com/package/@upload-post/mcp))
 
 ## License
 

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 ====================
@@ -358,9 +415,28 @@ declare module 'upload-post' {
 
   // ==================== Combined Upload Options ====================
 
+  export type GoogleBusinessMediaCategory =
+    | 'COVER'
+    | 'PROFILE'
+    | 'LOGO'
+    | 'EXTERIOR'
+    | 'INTERIOR'
+    | 'PRODUCT'
+    | 'AT_WORK'
+    | 'FOOD_AND_DRINK'
+    | 'MENU'
+    | 'COMMON_AREA'
+    | 'ROOMS'
+    | 'TEAMS'
+    | 'ADDITIONAL';
+
   export interface GoogleBusinessOptions {
     /** Google Business location id, e.g. "accounts/123/locations/456". Required when the account has more than one location; the API auto-selects only for single-location accounts. List them with getGoogleBusinessLocations(). */
     gbpLocationId?: string;
+    /** Publish to the location's gallery instead of creating a Local Post. Omitting it (or sending any other value) keeps the Local Post behaviour. */
+    gbpPostType?: 'MEDIA' | 'PHOTO' | 'GALLERY';
+    /** Gallery category for the uploaded photo. Only used with gbpPostType. Defaults to ADDITIONAL. */
+    gbpMediaCategory?: GoogleBusinessMediaCategory;
     /** Post type. Defaults to STANDARD. */
     gbpTopicType?: 'STANDARD' | 'EVENT' | 'OFFER';
     /** Media URL attached to the post */
@@ -496,9 +572,31 @@ declare module 'upload-post' {
     [key: string]: any;
   }
 
+  /**
+   * Instagram audience breakdown. Each key maps a bucket (age range, gender,
+   * country code, city name) to a follower/engager count.
+   */
+  export interface DemographicsBreakdown {
+    age?: Record<string, number>;
+    gender?: Record<string, number>;
+    country?: Record<string, number>;
+    city?: Record<string, number>;
+  }
+
+  export interface InstagramAnalytics {
+    /** Breakdown of the account's followers. */
+    follower_demographics?: DemographicsBreakdown;
+    /** Breakdown of the accounts that engaged with the profile's content. Same shape as follower_demographics. */
+    engaged_audience_demographics?: DemographicsBreakdown;
+    [key: string]: any;
+  }
+
   export interface AnalyticsResponse {
     success: boolean;
-    analytics?: any;
+    analytics?: {
+      instagram?: InstagramAnalytics;
+      [platform: string]: any;
+    };
     [key: string]: any;
   }
 
@@ -539,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 ====================
 
   /**
@@ -654,6 +826,48 @@ declare module 'upload-post' {
       }>;
     }>;
 
+    /**
+     * Replay per-post metrics already fetched, instead of querying
+     * the platforms live. Not subject to the live post-analytics rate limit
+     * (100 requests / 5 minutes), so it is the right call for paging through a
+     * profile's whole post history.
+     *
+     * @param user - Profile username
+     * @param options - Query options
+     */
+    getCachedPostAnalytics(user: string, options?: {
+      platform?: 'instagram' | 'tiktok' | 'youtube' | 'facebook' | 'linkedin' | 'threads' | 'pinterest' | 'reddit';
+      /** Posts per page. Default 50, max 200. */
+      limit?: number;
+      /** Opaque cursor from a previous response's next_cursor. */
+      cursor?: string;
+      /** Start date, YYYY-MM-DD. Defaults to 30 days ago. */
+      since?: string;
+      /** End date, YYYY-MM-DD. Defaults to today. */
+      until?: string;
+    }): Promise<{
+      success: boolean;
+      profile_username: string;
+      platform: string | null;
+      since: string;
+      until: string;
+      source: 'snapshot_cache';
+      posts: Array<{
+        post_id: string;
+        platform: string;
+        profile_username: string;
+        date: string;
+        captured_at: string;
+        metrics: Record<string, number>;
+        post_url?: string | null;
+        media_type?: string | null;
+        upload_timestamp?: string | null;
+      }>;
+      limit: number;
+      next_cursor: string | null;
+      has_more: boolean;
+    }>;
+
     /**
      * Get available metrics configuration for all supported platforms
      */
@@ -667,11 +881,13 @@ declare module 'upload-post' {
      * Get recent media from a connected social account.
      *
      * @param options.pageUrn - LinkedIn only. Numeric org ID, full org URN, or "me" to force the personal profile.
+     * @param options.limit - Items per page. Default 25, clamped to 1-100. Per-platform caps: TikTok 20, YouTube 50, everything else 100.
+     * @param options.cursor - Opaque cursor from a previous response's `pagination.next_cursor`. LinkedIn, Discord and Telegram do not support cursors: passing one there returns HTTP 400.
      */
     getMedia(
       platform: 'instagram' | 'tiktok' | 'youtube' | 'linkedin' | 'facebook' | 'x' | 'threads' | 'pinterest' | 'bluesky' | 'reddit' | string,
       user: string,
-      options?: { pageUrn?: string }
+      options?: { pageUrn?: string; limit?: number; cursor?: string }
     ): Promise<{
       success: boolean;
       media: Array<{
@@ -683,6 +899,12 @@ declare module 'upload-post' {
         timestamp: string | null;
         thumbnail_url: string | null;
       }>;
+      pagination?: {
+        limit: number;
+        /** null on the last page. */
+        next_cursor: string | null;
+        has_more: boolean;
+      };
     }>;
 
     // Scheduled Posts
@@ -736,14 +958,32 @@ declare module 'upload-post' {
       readonlyCalendar?: boolean;
       connectTitle?: string;
       connectDescription?: string;
-      language?: 'en' | 'es' | 'de' | 'fr' | 'pt';
+      language?: 'en' | 'es' | 'de' | 'fr' | 'pt' | 'pl' | 'tr';
+      /**
+       * Flat map of i18n dot-path keys to replacement strings, e.g.
+       * `{ 'connect.title': 'Link your accounts' }`. Max 100 entries; keys must
+       * match `^[a-zA-Z0-9_.]+$` and values are strings of up to 300 characters.
+       * Returned back in the `profile` object of validateJwt.
+       */
+      uiLabels?: Record<string, string>;
     }): Promise<JwtResponse>;
 
     /**
      * Validate a JWT token
      * @param jwt - JWT token to validate
      */
-    validateJwt(jwt: string): Promise<{ success: boolean; valid?: boolean }>;
+    validateJwt(jwt: string): Promise<{
+      success: boolean;
+      valid?: boolean;
+      profile?: {
+        username?: string;
+        language?: 'en' | 'es' | 'de' | 'fr' | 'pt' | 'pl' | 'tr';
+        /** The ui_labels sent to generateJwt, echoed back for the connection page. */
+        ui_labels?: Record<string, string>;
+        [key: string]: any;
+      };
+      [key: string]: any;
+    }>;
 
     /**
      * Get user preferences (including calendar settings)
@@ -939,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));
     }
   }
 
@@ -348,10 +377,16 @@ export class UploadPost {
    *
    * gbpLocationId is required for accounts with more than one location; the API
    * only auto-selects when exactly one location exists.
+   *
+   * gbpPostType switches the call from the default Local Post to a gallery
+   * photo upload (MEDIA / PHOTO / GALLERY). Any other value, or omitting it,
+   * keeps the Local Post behaviour.
    * @private
    */
   _addGoogleBusinessParams(form, options) {
     if (options.gbpLocationId) form.append('gbp_location_id', options.gbpLocationId);
+    if (options.gbpPostType) form.append('gbp_post_type', String(options.gbpPostType).toUpperCase());
+    if (options.gbpMediaCategory) form.append('gbp_media_category', String(options.gbpMediaCategory).toUpperCase());
     if (options.gbpTopicType) form.append('gbp_topic_type', String(options.gbpTopicType).toUpperCase());
     if (options.gbpMediaUrl) form.append('gbp_media_url', options.gbpMediaUrl);
     if (options.gbpMediaFormat) form.append('gbp_media_format', String(options.gbpMediaFormat).toUpperCase());
@@ -395,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
@@ -404,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
@@ -515,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
@@ -814,6 +878,33 @@ export class UploadPost {
     });
   }
 
+  /**
+   * Replay per-post metrics already fetched, instead of querying the
+   * platforms live.
+   *
+   * Because it never calls the platform APIs it is not subject to the live
+   * post-analytics rate limit (100 requests / 5 minutes), which makes it the
+   * right method for paging through a profile's whole post history.
+   *
+   * @param {string} user - Profile username
+   * @param {Object} [options] - Query options
+   * @param {string} [options.platform] - Filter by platform (instagram, tiktok, youtube, facebook, linkedin, threads, pinterest, reddit)
+   * @param {number} [options.limit=50] - Posts per page (max 200)
+   * @param {string} [options.cursor] - Opaque cursor from a previous response's next_cursor
+   * @param {string} [options.since] - Start date in YYYY-MM-DD format (defaults to 30 days ago)
+   * @param {string} [options.until] - End date in YYYY-MM-DD format (defaults to today)
+   * @returns {Promise<Object>} Cached post metrics with next_cursor and has_more
+   */
+  async getCachedPostAnalytics(user, options = {}) {
+    const params = { user };
+    if (options.platform) params.platform = options.platform;
+    if (options.limit !== undefined) params.limit = options.limit;
+    if (options.cursor) params.cursor = options.cursor;
+    if (options.since) params.since = options.since;
+    if (options.until) params.until = options.until;
+    return this._request('/uploadposts/post-analytics/cached', 'GET', params);
+  }
+
   /**
    * Get available metrics configuration for all supported platforms
    *
@@ -840,11 +931,16 @@ export class UploadPost {
    * @param {string} user - Profile username
    * @param {Object} [options]
    * @param {string} [options.pageUrn] - LinkedIn only. Numeric org ID, full URN, or "me" to force the personal profile.
-   * @returns {Promise<Object>}
+   * @param {number} [options.limit=25] - Items per page, clamped to 1-100. Per-platform caps: TikTok 20, YouTube 50, everything else 100.
+   * @param {string} [options.cursor] - Opaque cursor from a previous response's `pagination.next_cursor`.
+   *   LinkedIn, Discord and Telegram do not support cursors: passing one there returns HTTP 400.
+   * @returns {Promise<Object>} `{ success, media, pagination: { limit, next_cursor, has_more } }`
    */
   async getMedia(platform, user, options = {}) {
     const params = { platform, user };
     if (options.pageUrn) params.page_urn = options.pageUrn;
+    if (options.limit !== undefined) params.limit = options.limit;
+    if (options.cursor) params.cursor = options.cursor;
     return this._request('/uploadposts/media', 'GET', params);
   }
 
@@ -930,7 +1026,8 @@ export class UploadPost {
    * @param {boolean} [options.readonlyCalendar] - Show only a read-only calendar (no editing, no account connection)
    * @param {string} [options.connectTitle] - Custom title for the connection page
    * @param {string} [options.connectDescription] - Custom description for the connection page
-   * @param {('en'|'es'|'de'|'fr'|'pt')} [options.language] - Force the connection page language for this profile. When omitted, the page auto-detects the visitor's browser language and falls back to English.
+   * @param {('en'|'es'|'de'|'fr'|'pt'|'pl'|'tr')} [options.language] - Force the connection page language for this profile. When omitted, the page auto-detects the visitor's browser language and falls back to English.
+   * @param {Object.<string, string>} [options.uiLabels] - Flat map of i18n dot-path keys to replacement strings, e.g. `{ 'connect.title': 'Link your accounts' }`. Max 100 entries; keys must match `^[a-zA-Z0-9_.]+$` and values are strings of up to 300 characters. Returned back in the `profile` object of validateJwt.
    * @returns {Promise<Object>} JWT and connection URL
    */
   async generateJwt(username, options = {}) {
@@ -944,6 +1041,7 @@ export class UploadPost {
     if (options.connectTitle) body.connect_title = options.connectTitle;
     if (options.connectDescription) body.connect_description = options.connectDescription;
     if (options.language) body.language = options.language;
+    if (options.uiLabels) body.ui_labels = options.uiLabels;
     return this._request('/uploadposts/users/generate-jwt', 'POST', body);
   }
 
@@ -1202,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.8.1",
+  "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",
@@ -26,7 +26,10 @@
     "x",
     "api-client",
     "social-media-api",
-    "upload-post"
+    "upload-post",
+    "mcp",
+    "model-context-protocol",
+    "ai-agent"
   ],
   "repository": {
     "type": "git",