late-sdk 0.0.122 → 0.0.124

data/openapi.yaml

@@ -100,7 +100,7 @@ x-documentation:
     | Twitter/X | Yes | - | Yes | Yes |
     | Instagram | Yes | Yes | Yes | Yes |
     | Facebook | Yes | Stories | Yes | Yes |
-    | LinkedIn | Yes | - | Yes | - |
+    | LinkedIn | Yes | - | Partial | - |
     | TikTok | Yes | - | Yes | - |
     | YouTube | Yes | Shorts | Yes | Yes |
     | Pinterest | Yes | - | Yes | - |
@@ -111,6 +111,8 @@ x-documentation:
     | Telegram | Yes | - | - | - |
     | Snapchat | Yes | - | - | - |
 
+    > **LinkedIn Analytics Note:** For personal LinkedIn accounts, analytics are only available for posts published through Zernio. This is a LinkedIn API limitation: the `memberCreatorPostAnalytics` endpoint only returns metrics for posts authored by the authenticated user. Company/organization page analytics are not affected and work for all posts.
+
     ## Rate Limits
 
     | Plan | Requests/min | Posts/month |
@@ -1985,11 +1987,31 @@ components:
 
     TikTokPlatformData:
       type: object
-      description: Photo carousels up to 35 images. Video titles up to 2200 chars, photo titles truncated to 90 chars. privacyLevel must match creator_info options. Both camelCase and snake_case accepted.
+      description: |
+        Photo carousels up to 35 images. Video titles up to 2200 chars, photo titles truncated to 90 chars.
+        privacyLevel must match creator_info options. Both camelCase and snake_case accepted.
+
+        **Creator Inbox (draft mode):** Set `draft: true` to send content to the TikTok Creator Inbox
+        instead of publishing immediately. The creator receives an inbox notification and completes
+        the post using TikTok's editing flow. This maps to TikTok's `post_mode: "MEDIA_UPLOAD"` internally.
+
+        **Important:** The field `publish_type` is NOT supported. Use `draft: true` for Creator Inbox flow.
+
+        **Photo drafts** use the `/v2/post/publish/content/init/` endpoint with `post_mode: "MEDIA_UPLOAD"`.
+        **Video drafts** use the dedicated `/v2/post/publish/inbox/video/init/` endpoint.
+
+        When `draft: true`, the `video.upload` scope is required. When `draft` is false or omitted
+        (direct post), the `video.publish` scope is required. For Creator Inbox, TikTok app version
+        must be 31.8 or higher.
       properties:
         draft:
           type: boolean
-          description: When true, sends the post to the TikTok Creator Inbox as a draft instead of publishing immediately.
+          description: |
+            When true, sends the post to the TikTok Creator Inbox as a draft instead of publishing
+            immediately. The creator receives an inbox notification to complete posting via TikTok's
+            editing flow. Maps to TikTok API `post_mode: "MEDIA_UPLOAD"` (photos) or the dedicated
+            inbox endpoint (videos). When false or omitted, publishes directly via `post_mode: "DIRECT_POST"`.
+            Note: `publish_type` is not a supported field. Use this field instead.
         privacyLevel:
           type: string
           description: One of the values returned by the TikTok creator info API for the account
@@ -2186,7 +2208,9 @@ components:
       type: object
       properties:
         _id: { type: string }
-        platform: { type: string }
+        platform:
+          type: string
+          enum: [tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, whatsapp, linkedinads, metaads, pinterestads, tiktokads, xads, googleads]
         profileId:
           oneOf:
             - type: string
@@ -2204,11 +2228,29 @@ components:
           type: string
           format: date-time
           description: Last time follower count was updated (only included if user has analytics add-on)
+        parentAccountId:
+          type: string
+          nullable: true
+          description: |
+            Reference to the parent posting SocialAccount. Set for ads accounts that share
+            or derive from a posting account's OAuth token. null for standalone ads (Google Ads)
+            and all posting accounts.
+        enabled:
+          type: boolean
+          description: |
+            Whether the user explicitly activated this account. false means the account was
+            created as a side effect (e.g., posting account auto-created when user connected
+            ads first). Posting UI and scheduler ignore accounts with enabled: false.
         adsStatus:
           type: string
           enum: [connected, not_connected, not_available]
+          deprecated: true
           description: |
-            Ads connection status for this account.
+            **Deprecated.** With the new ads account model, ads accounts are separate SocialAccount
+            documents. Check for accounts with ads platform values (metaads, linkedinads, pinterestads,
+            tiktokads, xads, googleads) instead.
+
+            Legacy behavior:
             - `connected`: Ads are ready to use (same-token platforms like Meta/LinkedIn, or separate ads token is present).
             - `not_connected`: Platform supports ads but requires a separate ads OAuth. Use `GET /v1/connect/{platform}/ads` to connect.
             - `not_available`: Platform does not support ads (e.g., YouTube, Reddit, Bluesky).
@@ -3325,6 +3367,8 @@ paths:
         Returns analytics for posts. With postId, returns a single post. Without it, returns a paginated list with overview stats.
         Accepts both Zernio Post IDs and External Post IDs (auto-resolved). fromDate defaults to 90 days ago if omitted, max range 366 days.
         Single post lookups may return 202 (sync pending) or 424 (all platforms failed). For follower stats, use /v1/accounts/follower-stats.
+
+        **LinkedIn personal accounts:** Analytics are only available for posts published through Zernio. LinkedIn's API only returns metrics for posts authored by the authenticated user. Organization/company page analytics work for all posts.
       parameters:
         - name: postId
           in: query
@@ -5394,7 +5438,12 @@ paths:
                       - "Don't miss our essential guide!"
                       - "Our most popular guide, updated!"
               tiktokPhotoCarousel:
-                summary: TikTok photo carousel with draft mode
+                summary: TikTok photo carousel (Creator Inbox draft)
+                description: |
+                  Sends photos to TikTok Creator Inbox as a draft. The creator receives an inbox
+                  notification and completes the post via TikTok's editing flow. Uses draft: true
+                  which maps to TikTok API post_mode MEDIA_UPLOAD. Note: publish_type is not a
+                  supported field; use draft instead.
                 value:
                   content: "Check out these photos!"
                   mediaItems:
@@ -5409,6 +5458,30 @@ paths:
                     draft: true
                     privacyLevel: "PUBLIC_TO_EVERYONE"
                     allowComment: true
+                    photoCoverIndex: 0
+                    autoAddMusic: false
+                    contentPreviewConfirmed: true
+                    expressConsentGiven: true
+              tiktokPhotoDirect:
+                summary: TikTok photo carousel (direct publish)
+                description: |
+                  Publishes photos directly to TikTok. With draft omitted or false, the post is
+                  published immediately via TikTok API post_mode DIRECT_POST.
+                value:
+                  content: "Check out these photos!"
+                  mediaItems:
+                    - type: image
+                      url: "https://example.com/photo1.jpg"
+                    - type: image
+                      url: "https://example.com/photo2.jpg"
+                  platforms:
+                    - platform: tiktok
+                      accountId: "64e1f0a9e2b5af0012ab34cd"
+                  tiktokSettings:
+                    privacyLevel: "PUBLIC_TO_EVERYONE"
+                    allowComment: true
+                    photoCoverIndex: 0
+                    autoAddMusic: false
                     contentPreviewConfirmed: true
                     expressConsentGiven: true
               tiktokVideo:
@@ -5429,6 +5502,25 @@ paths:
                     commercialContentType: "none"
                     contentPreviewConfirmed: true
                     expressConsentGiven: true
+              tiktokVideoDraft:
+                summary: TikTok video post (Creator Inbox draft)
+                description: |
+                  Sends a video to TikTok Creator Inbox as a draft. Video drafts use a dedicated
+                  TikTok endpoint (/v2/post/publish/inbox/video/init/) that only accepts source_info,
+                  so post_info fields (privacyLevel, allowComment, etc.) are set by the creator
+                  during TikTok's editing flow.
+                value:
+                  content: "New video draft!"
+                  mediaItems:
+                    - type: video
+                      url: "https://example.com/video.mp4"
+                  platforms:
+                    - platform: tiktok
+                      accountId: "64e1f0a9e2b5af0012ab34cd"
+                  tiktokSettings:
+                    draft: true
+                    contentPreviewConfirmed: true
+                    expressConsentGiven: true
               multiPlatform:
                 summary: Multi-platform post (Twitter + LinkedIn)
                 value:
@@ -6636,32 +6728,27 @@ paths:
       operationId: disconnectAds
       tags: [Accounts]
       summary: Disconnect ads from an account
+      deprecated: true
       description: |
-        Disconnects ads from a social account without removing the posting connection.
+        **Deprecated.** Ads accounts are now standalone SocialAccount documents. Use `DELETE /v1/accounts/{accountId}` instead, passing the ads account's own ID.
 
-        **Same-token platforms** (metaads, linkedinads, pinterestads): Sets an `adsOptOut` flag. The posting account and OAuth token are preserved. Reconnecting ads clears the flag.
-
-        **Separate-token platforms** (tiktokads, xads): Clears the ads-specific metadata (marketing API tokens). The posting account stays intact.
-
-        **Standalone platforms** (googleads): Do not use this endpoint. Use `DELETE /v1/accounts/{accountId}` instead, since Google Ads accounts are standalone.
+        This endpoint is kept for backward compatibility. It soft-deletes the ads SocialAccount identified by `accountId` (which must be an ads account, not a posting account). The parent posting account is left untouched.
       parameters:
         - name: accountId
           in: path
           required: true
           schema: { type: string }
-          description: The SocialAccount ID (parent posting account for same-token/separate-token platforms)
+          description: The ads SocialAccount ID to disconnect
       requestBody:
-        required: true
         content:
           application/json:
             schema:
               type: object
-              required: [adsPlatform]
               properties:
                 adsPlatform:
                   type: string
                   enum: [metaads, linkedinads, pinterestads, tiktokads, xads]
-                  description: The ads platform to disconnect
+                  description: The ads platform (optional, used for logging only)
             example:
               adsPlatform: "tiktokads"
       security:
@@ -7249,15 +7336,15 @@ paths:
       tags: [Connect]
       summary: Connect ads for a platform
       description: |
-        Unified ads connection endpoint. Handles all platforms through a single route:
+        Unified ads connection endpoint. Creates a dedicated ads SocialAccount for the specified platform.
 
-        **Same-token platforms** (facebook, instagram, linkedin, pinterest): If a posting account already exists, returns `alreadyConnected: true` immediately (no extra OAuth needed). If not, starts the normal OAuth flow, and the resulting account supports both posting and ads.
+        **Same-token platforms** (facebook, instagram, linkedin, pinterest): Creates an ads SocialAccount (`metaads`, `linkedinads`, `pinterestads`) with a copied OAuth token from the parent posting account. If the ads account already exists, returns `alreadyConnected: true`. No extra OAuth needed.
 
-        **Separate-token platforms** (tiktok, twitter): Requires an existing posting account (`accountId` param). If ads are already connected, returns `alreadyConnected: true`. Otherwise, starts the platform-specific marketing API OAuth flow.
+        **Separate-token platforms** (tiktok, twitter): Starts the platform-specific marketing API OAuth flow and creates an ads SocialAccount (`tiktokads`, `xads`) with its own token. Requires an existing posting account (`accountId` param). If the ads account already exists, returns `alreadyConnected: true`.
 
-        **Ads-only platforms** (googleads): If a Google Ads account exists, returns `alreadyConnected: true`. Otherwise, starts the Google Ads OAuth flow.
+        **Standalone platforms** (googleads): Starts the Google Ads OAuth flow and creates a standalone ads SocialAccount (`googleads`) with no parent. If the account already exists, returns `alreadyConnected: true`.
 
-        Use the `adsStatus` field from `GET /v1/accounts` to check which accounts need ads connection.
+        Ads accounts appear as regular SocialAccount documents with ads platform values (e.g., `metaads`, `tiktokads`) in `GET /v1/accounts`.
       parameters:
         - name: platform
           in: path
@@ -7274,7 +7361,7 @@ paths:
         - name: accountId
           in: query
           schema: { type: string }
-          description: Existing SocialAccount ID. Required for separate-token platforms (tiktok, twitter). Ignored for same-token and ads-only platforms.
+          description: Existing SocialAccount ID. Required for separate-token platforms (tiktok, twitter). Ignored for same-token and standalone platforms.
         - name: redirect_url
           in: query
           schema: { type: string, format: uri }
@@ -9809,7 +9896,7 @@ paths:
       operationId: getLinkedInAggregateAnalytics
       tags: [Analytics]
       summary: Get LinkedIn aggregate stats
-      description: Returns aggregate analytics across all posts for a LinkedIn personal account. Org accounts should use /v1/analytics instead. Requires r_member_postAnalytics scope.
+      description: Returns aggregate analytics across all posts for a LinkedIn personal account. Only includes posts published through Zernio (LinkedIn API limitation). Org accounts should use /v1/analytics instead. Requires r_member_postAnalytics scope.
       parameters:
         - name: accountId
           in: path

data/spec/api/accounts_api_spec.rb

@@ -46,10 +46,10 @@ describe 'AccountsApi' do
 
   # unit tests for disconnect_ads
   # Disconnect ads from an account
-  # Disconnects ads from a social account without removing the posting connection.  **Same-token platforms** (metaads, linkedinads, pinterestads): Sets an `adsOptOut` flag. The posting account and OAuth token are preserved. Reconnecting ads clears the flag.  **Separate-token platforms** (tiktokads, xads): Clears the ads-specific metadata (marketing API tokens). The posting account stays intact.  **Standalone platforms** (googleads): Do not use this endpoint. Use `DELETE /v1/accounts/{accountId}` instead, since Google Ads accounts are standalone. 
-  # @param account_id The SocialAccount ID (parent posting account for same-token/separate-token platforms)
-  # @param disconnect_ads_request 
+  # **Deprecated.** Ads accounts are now standalone SocialAccount documents. Use `DELETE /v1/accounts/{accountId}` instead, passing the ads account's own ID.  This endpoint is kept for backward compatibility. It soft-deletes the ads SocialAccount identified by `accountId` (which must be an ads account, not a posting account). The parent posting account is left untouched. 
+  # @param account_id The ads SocialAccount ID to disconnect
   # @param [Hash] opts the optional parameters
+  # @option opts [DisconnectAdsRequest] :disconnect_ads_request 
   # @return [DeleteAccountGroup200Response]
   describe 'disconnect_ads test' do
     it 'should work' do

data/spec/api/analytics_api_spec.rb

@@ -34,7 +34,7 @@ describe 'AnalyticsApi' do
 
   # unit tests for get_analytics
   # Get post analytics
-  # Returns analytics for posts. With postId, returns a single post. Without it, returns a paginated list with overview stats. Accepts both Zernio Post IDs and External Post IDs (auto-resolved). fromDate defaults to 90 days ago if omitted, max range 366 days. Single post lookups may return 202 (sync pending) or 424 (all platforms failed). For follower stats, use /v1/accounts/follower-stats. 
+  # Returns analytics for posts. With postId, returns a single post. Without it, returns a paginated list with overview stats. Accepts both Zernio Post IDs and External Post IDs (auto-resolved). fromDate defaults to 90 days ago if omitted, max range 366 days. Single post lookups may return 202 (sync pending) or 424 (all platforms failed). For follower stats, use /v1/accounts/follower-stats.  **LinkedIn personal accounts:** Analytics are only available for posts published through Zernio. LinkedIn's API only returns metrics for posts authored by the authenticated user. Organization/company page analytics work for all posts. 
   # @param [Hash] opts the optional parameters
   # @option opts [String] :post_id Returns analytics for a single post. Accepts both Zernio Post IDs and External Post IDs. Zernio IDs are auto-resolved to External Post analytics.
   # @option opts [String] :platform Filter by platform (default \"all\")
@@ -178,7 +178,7 @@ describe 'AnalyticsApi' do
 
   # unit tests for get_linked_in_aggregate_analytics
   # Get LinkedIn aggregate stats
-  # Returns aggregate analytics across all posts for a LinkedIn personal account. Org accounts should use /v1/analytics instead. Requires r_member_postAnalytics scope.
+  # Returns aggregate analytics across all posts for a LinkedIn personal account. Only includes posts published through Zernio (LinkedIn API limitation). Org accounts should use /v1/analytics instead. Requires r_member_postAnalytics scope.
   # @param account_id The ID of the LinkedIn personal account
   # @param [Hash] opts the optional parameters
   # @option opts [String] :aggregation TOTAL (default, lifetime totals) or DAILY (time series). MEMBERS_REACHED not available with DAILY.

data/spec/api/connect_api_spec.rb

@@ -46,11 +46,11 @@ describe 'ConnectApi' do
 
   # unit tests for connect_ads
   # Connect ads for a platform
-  # Unified ads connection endpoint. Handles all platforms through a single route:  **Same-token platforms** (facebook, instagram, linkedin, pinterest): If a posting account already exists, returns `alreadyConnected: true` immediately (no extra OAuth needed). If not, starts the normal OAuth flow, and the resulting account supports both posting and ads.  **Separate-token platforms** (tiktok, twitter): Requires an existing posting account (`accountId` param). If ads are already connected, returns `alreadyConnected: true`. Otherwise, starts the platform-specific marketing API OAuth flow.  **Ads-only platforms** (googleads): If a Google Ads account exists, returns `alreadyConnected: true`. Otherwise, starts the Google Ads OAuth flow.  Use the `adsStatus` field from `GET /v1/accounts` to check which accounts need ads connection. 
+  # Unified ads connection endpoint. Creates a dedicated ads SocialAccount for the specified platform.  **Same-token platforms** (facebook, instagram, linkedin, pinterest): Creates an ads SocialAccount (`metaads`, `linkedinads`, `pinterestads`) with a copied OAuth token from the parent posting account. If the ads account already exists, returns `alreadyConnected: true`. No extra OAuth needed.  **Separate-token platforms** (tiktok, twitter): Starts the platform-specific marketing API OAuth flow and creates an ads SocialAccount (`tiktokads`, `xads`) with its own token. Requires an existing posting account (`accountId` param). If the ads account already exists, returns `alreadyConnected: true`.  **Standalone platforms** (googleads): Starts the Google Ads OAuth flow and creates a standalone ads SocialAccount (`googleads`) with no parent. If the account already exists, returns `alreadyConnected: true`.  Ads accounts appear as regular SocialAccount documents with ads platform values (e.g., `metaads`, `tiktokads`) in `GET /v1/accounts`. 
   # @param platform Platform to connect ads for. Only platforms with ads support are accepted.
   # @param profile_id Your Zernio profile ID
   # @param [Hash] opts the optional parameters
-  # @option opts [String] :account_id Existing SocialAccount ID. Required for separate-token platforms (tiktok, twitter). Ignored for same-token and ads-only platforms.
+  # @option opts [String] :account_id Existing SocialAccount ID. Required for separate-token platforms (tiktok, twitter). Ignored for same-token and standalone platforms.
   # @option opts [String] :redirect_url Custom redirect URL after OAuth completes (same-token platforms only)
   # @option opts [Boolean] :headless Enable headless mode (same-token platforms only)
   # @return [ConnectAds200Response]

data/spec/models/account_with_follower_stats_spec.rb

@@ -36,6 +36,10 @@ describe Late::AccountWithFollowerStats do
   describe 'test attribute "platform"' do
     it 'should work' do
       # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+      # validator = Petstore::EnumTest::EnumAttributeValidator.new('String', ["tiktok", "instagram", "facebook", "youtube", "linkedin", "twitter", "threads", "pinterest", "reddit", "bluesky", "googlebusiness", "telegram", "snapchat", "whatsapp", "linkedinads", "metaads", "pinterestads", "tiktokads", "xads", "googleads"])
+      # validator.allowable_values.each do |value|
+      #   expect { instance.platform = value }.not_to raise_error
+      # end
     end
   end
 
@@ -81,6 +85,18 @@ describe Late::AccountWithFollowerStats do
     end
   end
 
+  describe 'test attribute "parent_account_id"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "enabled"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
   describe 'test attribute "ads_status"' do
     it 'should work' do
       # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/

data/spec/models/social_account_spec.rb

@@ -36,6 +36,10 @@ describe Late::SocialAccount do
   describe 'test attribute "platform"' do
     it 'should work' do
       # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+      # validator = Petstore::EnumTest::EnumAttributeValidator.new('String', ["tiktok", "instagram", "facebook", "youtube", "linkedin", "twitter", "threads", "pinterest", "reddit", "bluesky", "googlebusiness", "telegram", "snapchat", "whatsapp", "linkedinads", "metaads", "pinterestads", "tiktokads", "xads", "googleads"])
+      # validator.allowable_values.each do |value|
+      #   expect { instance.platform = value }.not_to raise_error
+      # end
     end
   end
 
@@ -81,6 +85,18 @@ describe Late::SocialAccount do
     end
   end
 
+  describe 'test attribute "parent_account_id"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
+  describe 'test attribute "enabled"' do
+    it 'should work' do
+      # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/
+    end
+  end
+
   describe 'test attribute "ads_status"' do
     it 'should work' do
       # assertion here. ref: https://rspec.info/features/3-12/rspec-expectations/built-in-matchers/