upload-post 2.0.4 → 2.1.2

package/.github/workflows/publish.yml

@@ -46,10 +46,6 @@ jobs:
             echo "🚀 New version detected: $REMOTE → $LOCAL"
           fi
 
-      - name: Update npm to latest
-        if: steps.version_check.outputs.new == 'true' || github.event_name == 'workflow_dispatch'
-        run: npm install -g npm@latest && npm --version
-
       - name: Install dependencies
         if: steps.version_check.outputs.new == 'true' || github.event_name == 'workflow_dispatch'
         run: npm ci
@@ -61,7 +57,11 @@ jobs:
       - name: Publish to npm (dry-run)
         if: ${{ inputs.dry_run == true }}
         run: npm publish --access public --dry-run
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Publish to npm
         if: (steps.version_check.outputs.new == 'true' && inputs.dry_run != true) || github.event_name == 'release'
-        run: npm publish --access public --provenance
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -123,6 +123,13 @@ const status = await client.getStatus('request_id_from_upload');
 console.log(status);
 ```
 
+For scheduled or queued posts, check the status using the job_id:
+
+```javascript
+const status = await client.getJobStatus('job_id_from_scheduled_post');
+console.log(status);
+```
+
 ### Get Upload History
 
 ```javascript
@@ -267,6 +274,7 @@ const boards = await client.getPinterestBoards('my-profile');
 ### Threads
 - `threadsLongTextAsPost` - Post long text as single post (vs thread)
 - `threadsThreadMediaLayout` - Comma-separated list of how many media items to include in each Threads post. Each value must be 1-10, and the total must equal the number of files. Example: '5,5' splits 10 items into 2 posts with 5 each. If omitted and more than 10 items are provided, auto-chunks into groups of 10.
+- `threadsTopicTag` - Topic tag for the Threads post (1-50 characters, no periods or ampersands). One tag per post. Helps increase reach.
 
 ### Reddit
 - `redditSubreddit` - Subreddit name (without r/)
@@ -286,6 +294,7 @@ These options work across all upload methods:
 | `scheduledDate` | ISO date for scheduling |
 | `timezone` | Timezone for scheduled date |
 | `addToQueue` | Add to posting queue |
+| `maxPostsPerSlot` | Max posts per queue slot (overrides profile setting) |
 | `asyncUpload` | Process asynchronously (default: true) |
 
 ## TypeScript Support
@@ -327,3 +336,5 @@ try {
 ## License
 
 MIT
+
+<!-- deployed 2026-03-16 17:49 UTC -->

package/index.d.ts

@@ -2,13 +2,13 @@ declare module 'upload-post' {
   // ==================== Common Types ====================
 
   /** Supported platforms for video upload */
-  export type VideoPlatform = 'tiktok' | 'instagram' | 'youtube' | 'linkedin' | 'facebook' | 'pinterest' | 'threads' | 'bluesky' | 'x';
+  export type VideoPlatform = 'tiktok' | 'instagram' | 'youtube' | 'linkedin' | 'facebook' | 'pinterest' | 'threads' | 'bluesky' | 'x' | 'google_business';
 
   /** Supported platforms for photo upload */
-  export type PhotoPlatform = 'tiktok' | 'instagram' | 'linkedin' | 'facebook' | 'pinterest' | 'threads' | 'reddit' | 'bluesky' | 'x';
+  export type PhotoPlatform = 'tiktok' | 'instagram' | 'linkedin' | 'facebook' | 'pinterest' | 'threads' | 'reddit' | 'bluesky' | 'x' | 'google_business';
 
   /** Supported platforms for text upload */
-  export type TextPlatform = 'x' | 'linkedin' | 'facebook' | 'threads' | 'reddit' | 'bluesky';
+  export type TextPlatform = 'x' | 'linkedin' | 'facebook' | 'threads' | 'reddit' | 'bluesky' | 'google_business';
 
   /** TikTok privacy levels */
   export type TikTokPrivacyLevel = 'PUBLIC_TO_EVERYONE' | 'MUTUAL_FOLLOW_FRIENDS' | 'FOLLOWER_OF_CREATOR' | 'SELF_ONLY';
@@ -43,8 +43,8 @@ declare module 'upload-post' {
   // ==================== Common Options ====================
 
   export interface CommonUploadOptions {
-    /** Post title/caption */
-    title: string;
+    /** Post title/caption. Required for YouTube, Reddit, and text posts. Optional for TikTok, Instagram, Facebook, LinkedIn, X, Threads, Bluesky, Pinterest. */
+    title?: string;
     /** User identifier (profile name) */
     user: string;
     /** First comment to post after publishing */
@@ -57,6 +57,8 @@ declare module 'upload-post' {
     timezone?: string;
     /** Add to posting queue instead of immediate post */
     addToQueue?: boolean;
+    /** Maximum number of posts allowed per queue slot (overrides profile setting). Only used when addToQueue is true. */
+    maxPostsPerSlot?: number;
     /** Process upload asynchronously (default: true) */
     asyncUpload?: boolean;
 
@@ -134,8 +136,8 @@ declare module 'upload-post' {
     instagramShareToFeed?: boolean;
     /** Comma-separated collaborator usernames */
     instagramCollaborators?: string;
-    /** Custom cover URL */
-    instagramCoverUrl?: string;
+    /** Custom cover: URL string, file path, Buffer, or ReadableStream */
+    instagramCoverUrl?: string | Buffer | NodeJS.ReadableStream;
     /** Audio track name */
     instagramAudioName?: string;
     /** Comma-separated user tags */
@@ -343,12 +345,22 @@ declare module 'upload-post' {
     platforms: PhotoPlatform[];
   }
 
+  export interface LinkPreviewOptions {
+    /** Generic URL for link preview card (works for LinkedIn, Bluesky, Facebook). Platform-specific params take priority. */
+    linkUrl?: string;
+    /** URL for link preview card on LinkedIn */
+    linkedinLinkUrl?: string;
+    /** URL for external embed link preview on Bluesky */
+    blueskyLinkUrl?: string;
+  }
+
   export interface UploadTextOptions extends CommonUploadOptions,
     LinkedInOptions,
     FacebookTextOptions,
     XTextOptions,
     ThreadsOptions,
-    RedditOptions {
+    RedditOptions,
+    LinkPreviewOptions {
     /** Target platforms */
     platforms: TextPlatform[];
   }
@@ -370,6 +382,8 @@ declare module 'upload-post' {
     timezone?: string;
     /** Add to posting queue */
     addToQueue?: boolean;
+    /** Maximum number of posts allowed per queue slot (overrides profile setting). Only used when addToQueue is true. */
+    maxPostsPerSlot?: number;
     /** Process upload asynchronously */
     asyncUpload?: boolean;
   }
@@ -501,6 +515,12 @@ declare module 'upload-post' {
      */
     getStatus(requestId: string): Promise<StatusResponse>;
 
+    /**
+     * Get the status of a scheduled or queued upload by job ID
+     * @param jobId - The job_id from a scheduled or queued upload
+     */
+    getJobStatus(jobId: string): Promise<StatusResponse>;
+
     /**
      * Get upload history
      * @param options - Query options
@@ -512,7 +532,62 @@ declare module 'upload-post' {
      * @param profileUsername - Profile username
      * @param options - Query options
      */
-    getAnalytics(profileUsername: string, options?: { platforms?: string[] }): Promise<AnalyticsResponse>;
+    getAnalytics(profileUsername: string, options?: { platforms?: string[]; pageId?: string; pageUrn?: string }): Promise<AnalyticsResponse>;
+
+    /**
+     * Get total impressions for a profile from daily snapshots
+     * @param profileUsername - Profile username
+     * @param options - Query options
+     */
+    getTotalImpressions(profileUsername: string, options?: {
+      period?: 'last_day' | 'last_week' | 'last_month' | 'last_3months' | 'last_year';
+      startDate?: string;
+      endDate?: string;
+      date?: string;
+      platforms?: string[];
+      breakdown?: boolean;
+      metrics?: string[];
+    }): Promise<{
+      success: boolean;
+      profile_username: string;
+      start_date: string;
+      end_date: string;
+      total_impressions?: number;
+      metrics?: Record<string, number>;
+      per_platform?: Record<string, number | Record<string, number>>;
+      per_day?: Record<string, number | Record<string, number>>;
+      platforms_filter?: string[];
+    }>;
+
+    /**
+     * Get analytics for a specific post across all platforms
+     * @param requestId - The request_id from the upload
+     */
+    getPostAnalytics(requestId: string): Promise<{
+      success: boolean;
+      post: { request_id: string; profile_username: string; post_title: string; post_caption: string; media_type: string; upload_timestamp: string };
+      platforms: Record<string, {
+        success: boolean;
+        platform_post_id?: string;
+        post_url?: string;
+        post_metrics?: Record<string, number>;
+        post_metrics_source?: string;
+        post_metrics_error?: string;
+        profile_snapshot_at_post_date?: Record<string, number>;
+        profile_snapshot_latest?: Record<string, number>;
+        profile_snapshot_latest_date?: string;
+        error_message?: string;
+      }>;
+    }>;
+
+    /**
+     * Get available metrics configuration for all supported platforms
+     */
+    getPlatformMetrics(): Promise<Record<string, {
+      primary_impressions_field: string;
+      available_metrics: string[];
+      metric_labels: Record<string, string>;
+    }>>;
 
     // Scheduled Posts
     /**
@@ -573,6 +648,68 @@ declare module 'upload-post' {
      */
     validateJwt(jwt: string): Promise<{ success: boolean; valid?: boolean }>;
 
+    /**
+     * Get user preferences (including calendar settings)
+     */
+    getUserPreferences(): Promise<{ success: boolean; preferences?: { week_start_day?: number; [key: string]: any } }>;
+
+    /**
+     * Update user preferences (including calendar settings)
+     * @param options - Preferences options
+     */
+    updateUserPreferences(options?: { weekStartDay?: number }): Promise<{ success: boolean; preferences?: { week_start_day?: number; [key: string]: any } }>;
+
+    /**
+     * Get notification configuration (including webhook settings)
+     */
+    getNotificationConfig(): Promise<{ success: boolean; config?: { webhook_events?: string[]; webhook_url?: string; [key: string]: any } }>;
+
+    /**
+     * Update notification configuration (including webhook settings)
+     * @param options - Notification config options
+     */
+    updateNotificationConfig(options?: { webhookEvents?: string[]; webhookUrl?: string }): Promise<{ success: boolean; config?: { webhook_events?: string[]; webhook_url?: string; [key: string]: any } }>;
+
+    // Instagram Comments
+
+    /**
+     * Get comments on an Instagram post
+     * @param user - Profile username
+     * @param options - Query options
+     */
+    getPostComments(user: string, options?: { postId?: string; postUrl?: string }): Promise<{
+      success: boolean;
+      comments?: Array<{
+        id: string;
+        text: string;
+        timestamp: string;
+        user: { id: string; username: string };
+      }>;
+    }>;
+
+    /**
+     * Send a private reply (DM) to the author of an Instagram comment
+     * @param options - Reply options
+     */
+    replyToComment(options: { user: string; commentId: string; message: string }): Promise<{
+      success: boolean;
+      recipient_id?: string;
+      message_id?: string;
+      message?: string;
+      error?: string;
+    }>;
+
+    /**
+     * Post a public reply to an Instagram comment (visible under the original comment)
+     * @param options - Reply options
+     */
+    publicReplyToComment(options: { user: string; commentId: string; message: string }): Promise<{
+      success: boolean;
+      id?: string;
+      message?: string;
+      error?: string;
+    }>;
+
     // Helper Endpoints
     /**
      * Get Facebook pages for a profile

package/index.js

@@ -29,7 +29,8 @@ export class UploadPost {
       method,
       url: `${this.baseUrl}${endpoint}`,
       headers: {
-        'Authorization': `Apikey ${this.apiKey}`
+        'Authorization': `Apikey ${this.apiKey}`,
+        'X-Upload-Post-Source': 'npm',
       },
       maxContentLength: Infinity,
       maxBodyLength: Infinity
@@ -62,7 +63,7 @@ export class UploadPost {
    */
   _addCommonParams(form, options) {
     form.append('user', options.user);
-    form.append('title', options.title);
+    if (options.title) form.append('title', options.title);
 
     // Platforms
     const platforms = Array.isArray(options.platforms) ? options.platforms : [options.platforms];
@@ -74,6 +75,7 @@ export class UploadPost {
     if (options.scheduledDate) form.append('scheduled_date', options.scheduledDate);
     if (options.timezone) form.append('timezone', options.timezone);
     if (options.addToQueue !== undefined) form.append('add_to_queue', String(options.addToQueue));
+    if (options.maxPostsPerSlot !== undefined) form.append('max_posts_per_slot', String(options.maxPostsPerSlot));
     if (options.asyncUpload !== undefined) form.append('async_upload', String(options.asyncUpload));
 
     // Platform-specific title overrides
@@ -103,6 +105,24 @@ export class UploadPost {
     if (options.youtubeFirstComment) form.append('youtube_first_comment', options.youtubeFirstComment);
     if (options.redditFirstComment) form.append('reddit_first_comment', options.redditFirstComment);
     if (options.blueskyFirstComment) form.append('bluesky_first_comment', options.blueskyFirstComment);
+    if (options.linkedinFirstComment) form.append('linkedin_first_comment', options.linkedinFirstComment);
+
+    if (options.firstCommentMedia) {
+      const mediaItems = Array.isArray(options.firstCommentMedia) ? options.firstCommentMedia : [options.firstCommentMedia];
+      for (const mediaItem of mediaItems) {
+        if (typeof mediaItem === 'string') {
+          if (mediaItem.toLowerCase().startsWith('http://') || mediaItem.toLowerCase().startsWith('https://')) {
+            form.append('first_comment_media[]', mediaItem);
+          } else {
+            if (fs.existsSync(mediaItem)) {
+              form.append('first_comment_media[]', createReadStream(mediaItem));
+            }
+          }
+        } else {
+          form.append('first_comment_media[]', mediaItem);
+        }
+      }
+    }
   }
 
   /**
@@ -140,7 +160,16 @@ export class UploadPost {
 
     if (isVideo) {
       if (options.instagramShareToFeed !== undefined) form.append('share_to_feed', String(options.instagramShareToFeed));
-      if (options.instagramCoverUrl) form.append('cover_url', options.instagramCoverUrl);
+      if (options.instagramCoverUrl) {
+        const coverVal = options.instagramCoverUrl;
+        if (typeof coverVal === 'string' && (coverVal.toLowerCase().startsWith('http://') || coverVal.toLowerCase().startsWith('https://'))) {
+          form.append('cover_url', coverVal);
+        } else if (typeof coverVal === 'string') {
+          form.append('cover_image', createReadStream(coverVal));
+        } else {
+          form.append('cover_image', coverVal);
+        }
+      }
       if (options.instagramAudioName) form.append('audio_name', options.instagramAudioName);
       if (options.instagramThumbOffset) form.append('thumb_offset', options.instagramThumbOffset);
     }
@@ -175,9 +204,12 @@ export class UploadPost {
    * Add LinkedIn-specific parameters
    * @private
    */
-  _addLinkedinParams(form, options) {
+  _addLinkedinParams(form, options, isText = false) {
     if (options.linkedinVisibility) form.append('visibility', options.linkedinVisibility);
     if (options.targetLinkedinPageId) form.append('target_linkedin_page_id', options.targetLinkedinPageId);
+    if (isText && (options.linkedinLinkUrl || options.linkUrl)) {
+      form.append('linkedin_link_url', options.linkedinLinkUrl || options.linkUrl);
+    }
   }
 
   /**
@@ -258,15 +290,19 @@ export class UploadPost {
   _addThreadsParams(form, options) {
     if (options.threadsLongTextAsPost !== undefined) form.append('threads_long_text_as_post', String(options.threadsLongTextAsPost));
     if (options.threadsThreadMediaLayout) form.append('threads_thread_media_layout', options.threadsThreadMediaLayout);
+    if (options.threadsTopicTag) form.append('threads_topic_tag', options.threadsTopicTag);
   }
 
   /**
    * Add Reddit-specific parameters
    * @private
    */
-  _addRedditParams(form, options) {
+  _addRedditParams(form, options, isText = false) {
     if (options.redditSubreddit) form.append('subreddit', options.redditSubreddit);
     if (options.redditFlairId) form.append('flair_id', options.redditFlairId);
+    if (isText && (options.redditLinkUrl || options.linkUrl)) {
+      form.append('reddit_link_url', options.redditLinkUrl || options.linkUrl);
+    }
   }
 
   /**
@@ -299,7 +335,7 @@ export class UploadPost {
    * @param {string} [options.instagramMediaType] - REELS or STORIES
    * @param {boolean} [options.instagramShareToFeed] - Share to feed
    * @param {string} [options.instagramCollaborators] - Comma-separated collaborator usernames
-   * @param {string} [options.instagramCoverUrl] - Custom cover URL
+   * @param {string|Buffer|ReadableStream} [options.instagramCoverUrl] - Custom cover: URL string, file path, Buffer, or ReadableStream
    * @param {string} [options.instagramAudioName] - Audio track name
    * @param {string} [options.instagramUserTags] - Comma-separated user tags
    * @param {string} [options.instagramLocationId] - Location ID
@@ -352,6 +388,7 @@ export class UploadPost {
    * Threads options:
    * @param {boolean} [options.threadsLongTextAsPost] - Post long text as single post (vs thread)
    * @param {string} [options.threadsThreadMediaLayout] - Comma-separated list of how many media items per Threads post (e.g. "5,5")
+   * @param {string} [options.threadsTopicTag] - Topic tag for the Threads post (1-50 chars, no periods or ampersands)
    *
    * @returns {Promise<Object>} API response with request_id for async uploads
    */
@@ -359,7 +396,7 @@ export class UploadPost {
     const form = new FormData();
 
     // Handle video (file path or URL)
-    if (videoPathOrUrl.toLowerCase().startsWith('http://') || videoPathOrUrl.toLowerCase().startsWith('https://')) {
+    if (typeof videoPathOrUrl === 'string' && (videoPathOrUrl.toLowerCase().startsWith('http://') || videoPathOrUrl.toLowerCase().startsWith('https://'))) {
       form.append('video', videoPathOrUrl);
     } else {
       if (!fs.existsSync(videoPathOrUrl)) {
@@ -433,6 +470,7 @@ export class UploadPost {
    * Threads options:
    * @param {boolean} [options.threadsLongTextAsPost] - Post long text as single post
    * @param {string} [options.threadsThreadMediaLayout] - Comma-separated list of how many media items per Threads post (e.g. "5,5")
+   * @param {string} [options.threadsTopicTag] - Topic tag for the Threads post (1-50 chars, no periods or ampersands)
    *
    * Reddit options:
    * @param {string} [options.redditSubreddit] - Subreddit name (without r/)
@@ -482,13 +520,18 @@ export class UploadPost {
    * @param {string} [options.timezone] - Timezone for scheduled date
    * @param {boolean} [options.addToQueue] - Add to posting queue
    * @param {boolean} [options.asyncUpload=true] - Process upload asynchronously
-   * 
+   * @param {string} [options.linkUrl] - Generic URL for link preview card (works for LinkedIn, Bluesky, Facebook). Platform-specific params take priority.
+   *
    * LinkedIn options:
    * @param {string} [options.targetLinkedinPageId] - Page ID for organization posts
-   * 
+   * @param {string} [options.linkedinLinkUrl] - URL to attach as link preview on LinkedIn
+   *
+   * Bluesky options:
+   * @param {string} [options.blueskyLinkUrl] - URL to attach as external embed link preview on Bluesky
+   *
    * Facebook options:
    * @param {string} [options.facebookPageId] - Facebook Page ID
-   * @param {string} [options.facebookLinkUrl] - URL to attach as link preview
+   * @param {string} [options.facebookLinkUrl] - URL to attach as link preview on Facebook
    * 
    * X (Twitter) options:
    * @param {string} [options.xReplySettings] - Who can reply
@@ -503,6 +546,7 @@ export class UploadPost {
    * Threads options:
    * @param {boolean} [options.threadsLongTextAsPost] - Post long text as single post
    * @param {string} [options.threadsThreadMediaLayout] - Comma-separated list of how many media items per Threads post (e.g. "5,5")
+   * @param {string} [options.threadsTopicTag] - Topic tag for the Threads post (1-50 chars, no periods or ampersands)
    *
    * Reddit options:
    * @param {string} [options.redditSubreddit] - Subreddit name (without r/)
@@ -512,15 +556,21 @@ export class UploadPost {
    */
   async uploadText(options) {
     const form = new FormData();
-    
+
     this._addCommonParams(form, options);
-    
+
+    // Generic link_url support
+    if (options.linkUrl) form.append('link_url', options.linkUrl);
+
     const platforms = Array.isArray(options.platforms) ? options.platforms : [options.platforms];
-    if (platforms.includes('linkedin')) this._addLinkedinParams(form, options);
+    if (platforms.includes('linkedin')) this._addLinkedinParams(form, options, true);
     if (platforms.includes('facebook')) this._addFacebookParams(form, options, false, true);
     if (platforms.includes('x')) this._addXParams(form, options, true);
     if (platforms.includes('threads')) this._addThreadsParams(form, options);
-    if (platforms.includes('reddit')) this._addRedditParams(form, options);
+    if (platforms.includes('reddit')) this._addRedditParams(form, options, true);
+    if (platforms.includes('bluesky') && (options.blueskyLinkUrl || options.linkUrl)) {
+      form.append('bluesky_link_url', options.blueskyLinkUrl || options.linkUrl);
+    }
 
     return this._request('/upload_text', 'POST', form, true);
   }
@@ -546,7 +596,7 @@ export class UploadPost {
     const form = new FormData();
 
     // Handle document (file path or URL)
-    if (documentPathOrUrl.toLowerCase().startsWith('http://') || documentPathOrUrl.toLowerCase().startsWith('https://')) {
+    if (typeof documentPathOrUrl === 'string' && (documentPathOrUrl.toLowerCase().startsWith('http://') || documentPathOrUrl.toLowerCase().startsWith('https://'))) {
       form.append('document', documentPathOrUrl);
     } else {
       if (!fs.existsSync(documentPathOrUrl)) {
@@ -564,6 +614,7 @@ export class UploadPost {
     if (options.scheduledDate) form.append('scheduled_date', options.scheduledDate);
     if (options.timezone) form.append('timezone', options.timezone);
     if (options.addToQueue !== undefined) form.append('add_to_queue', String(options.addToQueue));
+    if (options.maxPostsPerSlot !== undefined) form.append('max_posts_per_slot', String(options.maxPostsPerSlot));
     if (options.asyncUpload !== undefined) form.append('async_upload', String(options.asyncUpload));
 
     this._addLinkedinParams(form, options);
@@ -583,6 +634,16 @@ export class UploadPost {
     return this._request('/uploadposts/status', 'GET', { request_id: requestId });
   }
 
+  /**
+   * Get the status of a scheduled or queued upload by job ID
+   *
+   * @param {string} jobId - The job_id from a scheduled or queued upload
+   * @returns {Promise<Object>} Upload status
+   */
+  async getJobStatus(jobId) {
+    return this._request('/uploadposts/status', 'GET', { job_id: jobId });
+  }
+
   /**
    * Get upload history
    * 
@@ -600,20 +661,89 @@ export class UploadPost {
 
   /**
    * Get analytics for a profile
-   * 
+   *
    * @param {string} profileUsername - Profile username
    * @param {Object} [options] - Query options
-   * @param {string[]} [options.platforms] - Filter by platforms (instagram, linkedin, facebook, x)
-   * @returns {Promise<Object>} Analytics data
+   * @param {string[]} [options.platforms] - Filter by platforms (instagram, linkedin, facebook, x, youtube, tiktok, threads, pinterest, reddit)
+   * @param {string} [options.pageId] - Facebook Page ID (required for Facebook analytics)
+   * @param {string} [options.pageUrn] - LinkedIn page URN (defaults to "me" for personal profile)
+   * @returns {Promise<Object>} Analytics data per platform
    */
   async getAnalytics(profileUsername, options = {}) {
     const params = {};
     if (options.platforms && options.platforms.length > 0) {
       params.platforms = options.platforms.join(',');
     }
+    if (options.pageId) params.page_id = options.pageId;
+    if (options.pageUrn) params.page_urn = options.pageUrn;
     return this._request(`/analytics/${encodeURIComponent(profileUsername)}`, 'GET', params);
   }
 
+  /**
+   * Get total impressions for a profile from daily snapshots
+   *
+   * @param {string} profileUsername - Profile username
+   * @param {Object} [options] - Query options
+   * @param {string} [options.period] - Period shortcut: last_day, last_week, last_month, last_3months, last_year
+   * @param {string} [options.startDate] - Start date in YYYY-MM-DD format
+   * @param {string} [options.endDate] - End date in YYYY-MM-DD format
+   * @param {string} [options.date] - Single date in YYYY-MM-DD format
+   * @param {string[]} [options.platforms] - Filter by platforms
+   * @param {boolean} [options.breakdown] - Include per-platform and per-day breakdown
+   * @param {string[]} [options.metrics] - Specific metrics to aggregate (e.g., ['likes', 'comments', 'shares'])
+   * @returns {Promise<Object>} Total impressions data
+   */
+  async getTotalImpressions(profileUsername, options = {}) {
+    const params = {};
+    if (options.period) params.period = options.period;
+    if (options.startDate) params.start_date = options.startDate;
+    if (options.endDate) params.end_date = options.endDate;
+    if (options.date) params.date = options.date;
+    if (options.platforms && options.platforms.length > 0) {
+      params.platform = options.platforms.join(',');
+    }
+    if (options.breakdown) params.breakdown = 'true';
+    if (options.metrics && options.metrics.length > 0) {
+      params.metrics = options.metrics.join(',');
+    }
+    return this._request(`/uploadposts/total-impressions/${encodeURIComponent(profileUsername)}`, 'GET', params);
+  }
+
+  /**
+   * Get analytics for a specific post across all platforms it was published to
+   *
+   * @param {string} requestId - The request_id from the upload
+   * @returns {Promise<Object>} Post analytics with per-platform metrics
+   */
+  async getPostAnalytics(requestId) {
+    return this._request(`/uploadposts/post-analytics/${encodeURIComponent(requestId)}`, 'GET');
+  }
+
+  /**
+   * Get analytics for any post (including organic posts) using its native platform ID
+   *
+   * @param {string} platformPostId - The native post ID on the platform (e.g., Instagram media ID)
+   * @param {string} platform - The platform to query (instagram, youtube, tiktok, facebook, linkedin, x, threads, pinterest, reddit)
+   * @param {string} user - The profile_username that owns the social account
+   * @returns {Promise<Object>} Post analytics with live per-post metrics from the platform API
+   */
+  async getPostAnalyticsByPlatformId(platformPostId, platform, user) {
+    return this._request('/uploadposts/post-analytics', 'GET', {
+      platform_post_id: platformPostId,
+      platform,
+      user,
+    });
+  }
+
+  /**
+   * Get available metrics configuration for all supported platforms
+   *
+   * @returns {Promise<Object>} Platform metrics config (primary fields, available metrics, labels)
+   */
+  async getPlatformMetrics() {
+    return this._request('/uploadposts/platform-metrics', 'GET');
+  }
+
   // ==================== Scheduled Posts ====================
 
   /**
@@ -721,6 +851,106 @@ export class UploadPost {
     return this._request('/uploadposts/users/validate-jwt', 'POST', { jwt });
   }
 
+  /**
+   * Get user preferences (including calendar settings)
+   *
+   * @returns {Promise<Object>} User preferences
+   */
+  async getUserPreferences() {
+    return this._request('/uploadposts/users/preferences', 'GET');
+  }
+
+  /**
+   * Update user preferences (including calendar settings)
+   *
+   * @param {Object} options - Preferences options
+   * @param {number} [options.weekStartDay] - Week start day (0=Sunday, 1=Monday)
+   * @returns {Promise<Object>} Updated preferences
+   */
+  async updateUserPreferences(options = {}) {
+    const body = {};
+    if (options.weekStartDay !== undefined) body.week_start_day = options.weekStartDay;
+    return this._request('/uploadposts/users/preferences', 'POST', body);
+  }
+
+  /**
+   * Get notification configuration (including webhook settings)
+   *
+   * @returns {Promise<Object>} Notification config
+   */
+  async getNotificationConfig() {
+    return this._request('/uploadposts/notification-config', 'GET');
+  }
+
+  /**
+   * Update notification configuration (including webhook settings)
+   *
+   * @param {Object} options - Notification config options
+   * @param {string[]} [options.webhookEvents] - Webhook event types to subscribe to (upload_completed, social_account_connected, social_account_disconnected, social_account_reauth_required)
+   * @param {string} [options.webhookUrl] - Webhook URL for notifications
+   * @returns {Promise<Object>} Updated notification config
+   */
+  async updateNotificationConfig(options = {}) {
+    const body = {};
+    if (options.webhookEvents) body.webhook_events = options.webhookEvents;
+    if (options.webhookUrl) body.webhook_url = options.webhookUrl;
+    return this._request('/uploadposts/notification-config', 'POST', body);
+  }
+
+  // ==================== Instagram Comments ====================
+
+  /**
+   * Get comments on an Instagram post
+   *
+   * @param {string} user - Profile username
+   * @param {Object} options - Query options
+   * @param {string} [options.postId] - Numeric media ID (provide postId or postUrl)
+   * @param {string} [options.postUrl] - Full Instagram post URL (provide postId or postUrl)
+   * @returns {Promise<Object>} Comments data
+   */
+  async getPostComments(user, options = {}) {
+    const params = { platform: 'instagram', user };
+    if (options.postId) params.post_id = options.postId;
+    if (options.postUrl) params.post_url = options.postUrl;
+    return this._request('/uploadposts/comments', 'GET', params);
+  }
+
+  /**
+   * Send a private reply (DM) to the author of an Instagram comment
+   *
+   * @param {Object} options - Reply options
+   * @param {string} options.user - Profile username
+   * @param {string} options.commentId - Comment ID from getPostComments
+   * @param {string} options.message - Reply message text
+   * @returns {Promise<Object>} Reply result
+   */
+  async replyToComment(options) {
+    return this._request('/uploadposts/comments/reply', 'POST', {
+      platform: 'instagram',
+      user: options.user,
+      comment_id: options.commentId,
+      message: options.message
+    });
+  }
+
+  /**
+   * Post a public reply to an Instagram comment (visible under the original comment)
+   *
+   * @param {Object} options - Reply options
+   * @param {string} options.user - Profile username
+   * @param {string} options.commentId - Comment ID from getPostComments
+   * @param {string} options.message - Reply message text
+   * @returns {Promise<Object>} Reply result with the new comment ID
+   */
+  async publicReplyToComment(options) {
+    return this._request('/uploadposts/comments/public-reply', 'POST', {
+      platform: 'instagram',
+      user: options.user,
+      comment_id: options.commentId,
+      message: options.message
+    });
+  }
+
   // ==================== Helper Endpoints ====================
 
   /**
@@ -755,6 +985,30 @@ export class UploadPost {
     const params = profile ? { profile } : {};
     return this._request('/uploadposts/pinterest/boards', 'GET', params);
   }
+
+  /**
+   * Get Google Business Profile locations for a connected account
+   *
+   * @param {string} [profile] - Profile username
+   * @returns {Promise<Object>} List of Google Business locations
+   */
+  async getGoogleBusinessLocations(profile) {
+    const params = profile ? { profile } : {};
+    return this._request('/uploadposts/google-business/locations', 'GET', params);
+  }
+
+  /**
+   * Select a specific Google Business Profile location for a profile
+   *
+   * @param {string} locationId - The location ID to select (e.g. "accounts/123/locations/456")
+   * @param {string} [profile] - Profile username
+   * @returns {Promise<Object>} Selection result with google_business_id and display_name
+   */
+  async selectGoogleBusinessLocation(locationId, profile) {
+    const data = { location_id: locationId };
+    if (profile) data.profile = profile;
+    return this._request('/uploadposts/google-business/locations/select', 'POST', data);
+  }
 }
 
 // Default export for CommonJS compatibility

package/package.json

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