upload-post 2.2.0 → 2.4.0

package/.github/workflows/publish.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      id-token: write
+      id-token: write   # mints the OIDC token npm trades for publish rights
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -27,9 +27,22 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '22'
+          node-version: '24'
           registry-url: 'https://registry.npmjs.org'
 
+      # Trusted publishing needs npm >= 11.5.1, which Node 24 already bundles.
+      # Do NOT `npm install -g npm@latest`: it leaves npm's own tree short of
+      # `sigstore`, and `--provenance` then dies on it.
+      - name: Check npm supports trusted publishing
+        run: |
+          NPM_VERSION=$(npm --version)
+          echo "npm $NPM_VERSION"
+          MIN=11.5.1
+          if [ "$(printf '%s\n%s\n' "$MIN" "$NPM_VERSION" | sort -V | head -1)" != "$MIN" ]; then
+            echo "::error::npm $NPM_VERSION is older than $MIN, which trusted publishing requires"
+            exit 1
+          fi
+
       - name: Check if version is new
         id: version_check
         run: |
@@ -54,14 +67,12 @@ jobs:
         if: steps.version_check.outputs.new == 'true' || github.event_name == 'workflow_dispatch'
         run: npm run build --if-present
 
+      # No NODE_AUTH_TOKEN: npm authenticates via the OIDC token, and the
+      # trusted publisher is configured on npmjs.com against this repo+workflow.
       - 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 }}
+        run: npm publish --provenance --access public --dry-run
 
       - name: Publish to npm
         if: (steps.version_check.outputs.new == 'true' && inputs.dry_run != true) || github.event_name == 'release'
-        run: npm publish --access public
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --provenance --access public

package/README.md

@@ -2,7 +2,7 @@
 
 Official Node.js client for the [Upload-Post API](https://www.upload-post.com) - Cross-platform social media upload.
 
-Upload videos, photos, text posts, and documents to **TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, and X (Twitter)** with a single API.
+Upload videos, photos, text posts, and documents to **TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, X (Twitter), Discord, and Telegram** with a single API.
 
 ## Installation
 
@@ -29,9 +29,9 @@ console.log(response);
 
 ## Features
 
-- ✅ **Video Upload** - TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Bluesky, X
-- ✅ **Photo Upload** - TikTok, Instagram, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, X
-- ✅ **Text Posts** - X, LinkedIn, Facebook, Threads, Reddit, Bluesky
+- ✅ **Video Upload** - TikTok, Instagram, YouTube, LinkedIn, Facebook, Pinterest, Threads, Bluesky, X, Discord, Telegram
+- ✅ **Photo Upload** - TikTok, Instagram, LinkedIn, Facebook, Pinterest, Threads, Reddit, Bluesky, X, Discord, Telegram
+- ✅ **Text Posts** - X, LinkedIn, Facebook, Threads, Reddit, Bluesky, Discord, Telegram
 - ✅ **Document Upload** - LinkedIn (PDF, PPT, PPTX, DOC, DOCX)
 - ✅ **Scheduling** - Schedule posts for later
 - ✅ **Posting Queue** - Add posts to your configured queue
@@ -169,6 +169,10 @@ await client.deleteUser('old-profile');
 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.
+  language: 'es',
 });
 ```
 
@@ -312,6 +316,32 @@ These options work across all upload methods:
 | `addToQueue` | Add to posting queue |
 | `maxPostsPerSlot` | Max posts per queue slot (overrides profile setting) |
 | `asyncUpload` | Process asynchronously (default: true) |
+| `autogenerate` | If true, AI generates native per-platform title/description from the media and fills any field left empty |
+| `autogenerateTitle` / `autogenerateDescription` | Generate only the title or only the description with AI |
+| `autogenerateLanguage` | Force the AI output language (ISO code); omit to auto-detect from the media |
+| `idempotencyKey` | Collapses duplicate uploads within 24h. Reuse the same value when retrying. Alias: `requestId` |
+
+## 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.
+
+Pass the same `idempotencyKey` on every attempt and the API returns the original job instead of creating a new one:
+
+```javascript
+import { randomUUID } from 'crypto';
+
+const idempotencyKey = randomUUID();   // generate ONCE, outside the retry loop
+
+for (let attempt = 0; attempt < 3; attempt++) {
+  try {
+    return await client.upload('video.mp4', { user, platforms: ['tiktok'], title, idempotencyKey });
+  } catch (err) {
+    if (attempt === 2) throw err;
+  }
+}
+```
+
+Generating the key inside the loop defeats the mechanism: each attempt would look like a new upload.
 
 ## TypeScript Support
 

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' | 'google_business';
+  export type VideoPlatform = 'tiktok' | 'instagram' | 'youtube' | 'linkedin' | 'facebook' | 'pinterest' | 'threads' | 'reddit' | 'bluesky' | 'x' | 'google_business' | 'discord' | 'telegram';
 
   /** Supported platforms for photo upload */
-  export type PhotoPlatform = 'tiktok' | 'instagram' | 'linkedin' | 'facebook' | 'pinterest' | 'threads' | 'reddit' | 'bluesky' | 'x' | 'google_business';
+  export type PhotoPlatform = 'tiktok' | 'instagram' | 'linkedin' | 'facebook' | 'pinterest' | 'threads' | 'reddit' | 'bluesky' | 'x' | 'google_business' | 'discord' | 'telegram';
 
   /** Supported platforms for text upload */
-  export type TextPlatform = 'x' | 'linkedin' | 'facebook' | 'threads' | 'reddit' | 'bluesky' | 'google_business';
+  export type TextPlatform = 'x' | 'linkedin' | 'facebook' | 'threads' | 'reddit' | 'bluesky' | 'google_business' | 'discord' | 'telegram';
 
   /** TikTok privacy levels */
   export type TikTokPrivacyLevel = 'PUBLIC_TO_EVERYONE' | 'MUTUAL_FOLLOW_FRIENDS' | 'FOLLOWER_OF_CREATOR' | 'SELF_ONLY';
@@ -45,6 +45,13 @@ declare module 'upload-post' {
   export interface CommonUploadOptions {
     /** Post title/caption. Required for YouTube, Reddit, and text posts. Optional for TikTok, Instagram, Facebook, LinkedIn, X, Threads, Bluesky, Pinterest. */
     title?: string;
+    /**
+     * Key the API uses to collapse duplicate uploads within a 24-hour window.
+     * Pass the same value when retrying a failed upload, otherwise the retry publishes a second post.
+     */
+    idempotencyKey?: string;
+    /** Alias for {@link CommonUploadOptions.idempotencyKey}. */
+    requestId?: string;
     /** User identifier (profile name) */
     user: string;
     /** First comment to post after publishing */
@@ -61,6 +68,14 @@ declare module 'upload-post' {
     maxPostsPerSlot?: number;
     /** Process upload asynchronously (default: true) */
     asyncUpload?: boolean;
+    /** If true, AI generates native per-platform title/description from the media and fills any field left empty */
+    autogenerate?: boolean;
+    /** Generate only the title with AI */
+    autogenerateTitle?: boolean;
+    /** Generate only the description with AI */
+    autogenerateDescription?: boolean;
+    /** Force the AI output language (ISO code); omit to auto-detect from the media */
+    autogenerateLanguage?: string;
 
     // Platform-specific title overrides
     blueskyTitle?: string;
@@ -192,6 +207,8 @@ declare module 'upload-post' {
     youtubeHasPaidProductPlacement?: boolean;
     /** Recording date (ISO 8601) */
     youtubeRecordingDate?: string;
+    /** Playlist ID(s) to add the uploaded video to — one ID, an array, or a comma-separated list */
+    youtubePlaylistId?: string | string[];
     /** Subtitle/caption files to upload. Each entry needs a language code and either a file path or URL. */
     youtubeSubtitles?: Array<{
       /** BCP-47 language code (e.g. "en", "es") */
@@ -317,6 +334,8 @@ declare module 'upload-post' {
     threadsLongTextAsPost?: boolean;
     /** Comma-separated list of how many media items per Threads post (e.g. "5,5"). Each value 1-10, total must equal file count. */
     threadsThreadMediaLayout?: string;
+    /** Topic tag for the Threads post */
+    threadsTopicTag?: string;
   }
 
   // ==================== Reddit Options ====================
@@ -482,7 +501,7 @@ declare module 'upload-post' {
    * Upload-Post API client
    * 
    * Supports uploading to: TikTok, Instagram, YouTube, LinkedIn, Facebook,
-   * Pinterest, Threads, Reddit, Bluesky, X (Twitter)
+   * Pinterest, Threads, Reddit, Bluesky, X (Twitter), Discord, Telegram
    */
   export class UploadPost {
     /**
@@ -673,6 +692,7 @@ declare module 'upload-post' {
       readonlyCalendar?: boolean;
       connectTitle?: string;
       connectDescription?: string;
+      language?: 'en' | 'es' | 'de' | 'fr' | 'pt';
     }): Promise<JwtResponse>;
 
     /**
@@ -761,6 +781,26 @@ declare module 'upload-post' {
      * @param profile - Profile username
      */
     getPinterestBoards(profile?: string): Promise<BoardsResponse>;
+
+    /**
+     * Get analytics for a post published outside Upload-Post, by its native platform ID
+     * @param platformPostId - The post ID assigned by the platform
+     * @param platform - Platform the post lives on
+     * @param user - Profile username that owns the connected account
+     */
+    getPostAnalyticsByPlatformId(platformPostId: string, platform: string, user: string): Promise<Record<string, unknown>>;
+
+    /**
+     * Get detailed Reddit posts with full media information
+     * @param profileUsername - Profile username
+     */
+    getRedditDetailedPosts(profileUsername: string): Promise<Record<string, unknown>>;
+
+    /**
+     * Get available Google Business locations for a profile
+     * @param profile - Profile username
+     */
+    getGoogleBusinessLocations(profile?: string): Promise<Record<string, unknown>>;
   }
 
   export default UploadPost;

package/index.js

@@ -8,8 +8,8 @@ const API_BASE_URL = 'https://api.upload-post.com/api';
 /**
  * Upload-Post API client
  * 
- * Supports uploading to: TikTok, Instagram, YouTube, LinkedIn, Facebook, 
- * Pinterest, Threads, Reddit, Bluesky, X (Twitter)
+ * Supports uploading to: TikTok, Instagram, YouTube, LinkedIn, Facebook,
+ * Pinterest, Threads, Reddit, Bluesky, X (Twitter), Discord, Telegram
  */
 export class UploadPost {
   /**
@@ -24,13 +24,14 @@ export class UploadPost {
    * Make an API request
    * @private
    */
-  async _request(endpoint, method = 'GET', data = null, isFormData = false) {
+  async _request(endpoint, method = 'GET', data = null, isFormData = false, extraHeaders = {}) {
     const config = {
       method,
       url: `${this.baseUrl}${endpoint}`,
       headers: {
         'Authorization': `Apikey ${this.apiKey}`,
         'X-Upload-Post-Source': 'npm',
+        ...extraHeaders,
       },
       maxContentLength: Infinity,
       maxBodyLength: Infinity
@@ -57,6 +58,16 @@ export class UploadPost {
     }
   }
 
+  /**
+   * The API collapses two uploads carrying the same key within 24 hours into a
+   * single post. Retrying an upload without one publishes it twice.
+   * @private
+   */
+  _idempotencyHeaders(options) {
+    const key = options.idempotencyKey || options.requestId;
+    return key ? { 'Idempotency-Key': String(key) } : {};
+  }
+
   /**
    * Add common upload parameters to form
    * @private
@@ -77,6 +88,11 @@ export class UploadPost {
     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));
+    // AI auto-generation of native per-platform copy from the media (fills blank fields)
+    if (options.autogenerate !== undefined) form.append('autogenerate', String(options.autogenerate));
+    if (options.autogenerateTitle !== undefined) form.append('autogenerate_title', String(options.autogenerateTitle));
+    if (options.autogenerateDescription !== undefined) form.append('autogenerate_description', String(options.autogenerateDescription));
+    if (options.autogenerateLanguage) form.append('autogenerate_language', String(options.autogenerateLanguage));
 
     // Platform-specific title overrides
     if (options.blueskyTitle) form.append('bluesky_title', options.blueskyTitle);
@@ -198,6 +214,12 @@ export class UploadPost {
     if (options.youtubeBlockedCountries) form.append('blockedCountries', options.youtubeBlockedCountries);
     if (options.youtubeHasPaidProductPlacement !== undefined) form.append('hasPaidProductPlacement', String(options.youtubeHasPaidProductPlacement));
     if (options.youtubeRecordingDate) form.append('recordingDate', options.youtubeRecordingDate);
+    if (options.youtubePlaylistId) {
+      const playlistIds = Array.isArray(options.youtubePlaylistId)
+        ? options.youtubePlaylistId.join(',')
+        : options.youtubePlaylistId;
+      form.append('youtube_playlist_id', playlistIds);
+    }
     if (options.youtubeSubtitles && Array.isArray(options.youtubeSubtitles)) {
       options.youtubeSubtitles.forEach((sub, idx) => {
         if (sub.language) {
@@ -330,7 +352,7 @@ export class UploadPost {
    * @param {Object} options - Upload options
    * @param {string} options.title - Video title/caption
    * @param {string} options.user - User identifier (profile name)
-   * @param {string[]} options.platforms - Target platforms (tiktok, instagram, youtube, linkedin, facebook, pinterest, threads, bluesky, x)
+   * @param {string[]} options.platforms - Target platforms (tiktok, instagram, youtube, linkedin, facebook, pinterest, threads, bluesky, x, discord, telegram)
    * @param {string} [options.description] - Video description
    * @param {string} [options.firstComment] - First comment to post
    * @param {string} [options.scheduledDate] - ISO date for scheduling (e.g., "2024-12-25T10:00:00Z")
@@ -434,8 +456,9 @@ export class UploadPost {
     if (platforms.includes('pinterest')) this._addPinterestParams(form, options, true);
     if (platforms.includes('x')) this._addXParams(form, options, false);
     if (platforms.includes('threads')) this._addThreadsParams(form, options);
+    if (platforms.includes('reddit')) this._addRedditParams(form, options);
 
-    return this._request('/upload', 'POST', form, true);
+    return this._request('/upload', 'POST', form, true, this._idempotencyHeaders(options));
   }
 
   /**
@@ -445,7 +468,7 @@ export class UploadPost {
    * @param {Object} options - Upload options
    * @param {string} options.title - Post title/caption
    * @param {string} options.user - User identifier (profile name)
-   * @param {string[]} options.platforms - Target platforms (tiktok, instagram, linkedin, facebook, x, threads, pinterest, reddit, bluesky)
+   * @param {string[]} options.platforms - Target platforms (tiktok, instagram, linkedin, facebook, x, threads, pinterest, reddit, bluesky, discord, telegram)
    * @param {string} [options.description] - Photo description
    * @param {string} [options.firstComment] - First comment to post
    * @param {string} [options.altText] - Alt text for accessibility
@@ -523,7 +546,7 @@ export class UploadPost {
     if (platforms.includes('threads')) this._addThreadsParams(form, options);
     if (platforms.includes('reddit')) this._addRedditParams(form, options);
 
-    return this._request('/upload_photos', 'POST', form, true);
+    return this._request('/upload_photos', 'POST', form, true, this._idempotencyHeaders(options));
   }
 
   /**
@@ -532,7 +555,7 @@ export class UploadPost {
    * @param {Object} options - Upload options
    * @param {string} options.title - Text content for the post
    * @param {string} options.user - User identifier (profile name)
-   * @param {string[]} options.platforms - Target platforms (x, linkedin, facebook, threads, reddit, bluesky)
+   * @param {string[]} options.platforms - Target platforms (x, linkedin, facebook, threads, reddit, bluesky, discord, telegram)
    * @param {string} [options.firstComment] - First comment to post
    * @param {string} [options.scheduledDate] - ISO date for scheduling
    * @param {string} [options.timezone] - Timezone for scheduled date
@@ -590,7 +613,7 @@ export class UploadPost {
       form.append('bluesky_link_url', options.blueskyLinkUrl || options.linkUrl);
     }
 
-    return this._request('/upload_text', 'POST', form, true);
+    return this._request('/upload_text', 'POST', form, true, this._idempotencyHeaders(options));
   }
 
   /**
@@ -634,10 +657,15 @@ export class UploadPost {
     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));
+    // AI auto-generation of native per-platform copy from the media (fills blank fields)
+    if (options.autogenerate !== undefined) form.append('autogenerate', String(options.autogenerate));
+    if (options.autogenerateTitle !== undefined) form.append('autogenerate_title', String(options.autogenerateTitle));
+    if (options.autogenerateDescription !== undefined) form.append('autogenerate_description', String(options.autogenerateDescription));
+    if (options.autogenerateLanguage) form.append('autogenerate_language', String(options.autogenerateLanguage));
 
     this._addLinkedinParams(form, options);
 
-    return this._request('/upload_document', 'POST', form, true);
+    return this._request('/upload_document', 'POST', form, true, this._idempotencyHeaders(options));
   }
 
   // ==================== Status & History ====================
@@ -762,6 +790,16 @@ export class UploadPost {
     return this._request('/uploadposts/platform-metrics', 'GET');
   }
 
+  /**
+   * Get detailed Reddit posts with full media information
+   *
+   * @param {string} profileUsername - Profile username
+   * @returns {Promise<Object>} Detailed Reddit posts
+   */
+  async getRedditDetailedPosts(profileUsername) {
+    return this._request('/uploadposts/reddit/detailed-posts/', 'GET', { profile_username: profileUsername });
+  }
+
   /**
    * Get recent media from a connected social account.
    *
@@ -811,7 +849,7 @@ export class UploadPost {
     const body = {};
     if (options.scheduledDate) body.scheduled_date = options.scheduledDate;
     if (options.timezone) body.timezone = options.timezone;
-    return this._request(`/uploadposts/schedule/${jobId}`, 'POST', body);
+    return this._request(`/uploadposts/schedule/${jobId}`, 'PATCH', body);
   }
 
   // ==================== User Management ====================
@@ -859,6 +897,7 @@ 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.
    * @returns {Promise<Object>} JWT and connection URL
    */
   async generateJwt(username, options = {}) {
@@ -871,6 +910,7 @@ export class UploadPost {
     if (options.readonlyCalendar !== undefined) body.readonly_calendar = options.readonlyCalendar;
     if (options.connectTitle) body.connect_title = options.connectTitle;
     if (options.connectDescription) body.connect_description = options.connectDescription;
+    if (options.language) body.language = options.language;
     return this._request('/uploadposts/users/generate-jwt', 'POST', body);
   }
 
@@ -881,7 +921,7 @@ export class UploadPost {
    * @returns {Promise<Object>} Validation result
    */
   async validateJwt(jwt) {
-    return this._request('/uploadposts/users/validate-jwt', 'POST', { jwt });
+    return this._request('/uploadposts/users/validate-jwt', 'GET', null, false, { Authorization: `Bearer ${jwt}` });
   }
 
   /**
@@ -912,7 +952,7 @@ export class UploadPost {
    * @returns {Promise<Object>} Notification config
    */
   async getNotificationConfig() {
-    return this._request('/uploadposts/notification-config', 'GET');
+    return this._request('/uploadposts/users/notifications', 'GET');
   }
 
   /**
@@ -927,7 +967,7 @@ export class UploadPost {
     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);
+    return this._request('/uploadposts/users/notifications', 'POST', body);
   }
 
   // ==================== Instagram Comments ====================

package/package.json

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