upload-post 2.0.4 → 2.1.0

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;
 
@@ -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
     /**

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);
+        }
+      }
+    }
   }
 
   /**
@@ -175,9 +195,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 +281,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);
+    }
   }
 
   /**
@@ -352,6 +379,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 +387,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 +461,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 +511,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 +537,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 +547,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 +587,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 +605,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 +625,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 +652,73 @@ 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 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 ====================
 
   /**
@@ -755,6 +860,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.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",