upload-post 2.8.1 → 2.9.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
@@ -350,6 +433,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 +506,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

@@ -358,9 +358,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 +515,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;
   }
 
@@ -654,6 +695,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 +750,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 +768,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 +827,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)

package/index.js

@@ -348,10 +348,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());
@@ -814,6 +820,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 +873,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 +968,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 +983,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);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "upload-post",
-  "version": "2.8.1",
+  "version": "2.9.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",