@zernio/node 0.2.1520 → 0.2.1522

package/dist/index.d.mts

@@ -18874,13 +18874,17 @@ type TikTokPlatformData = {
      */
     mediaType?: 'video' | 'photo';
     /**
-     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when videoCoverImageUrl is provided.
+     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when the videoCoverImageUrl image becomes the cover, and used when Zernio skips that image (see videoCoverImageUrl).
      */
     videoCoverTimestampMs?: number;
     /**
      * Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). Any downloadable URL works: we rehost it ourselves. Overrides videoCoverTimestampMs when provided.
      *
-     * The image is stitched as a single frame at the start of the video to serve as the cover. Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
+     * The image is stitched as a single frame at the start of the video to serve as the cover.
+     *
+     * When the image shape is far from the video shape (it would fill less than half of the frame, for example a landscape cover on a vertical video), or the stitch fails, Zernio skips the image and TikTok uses videoCoverTimestampMs.
+     *
+     * Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
      *
      */
     videoCoverImageUrl?: string;
@@ -25985,6 +25989,10 @@ type ValidatePostResponse = (({
     errors?: Array<{
         platform?: string;
         error?: string;
+        /**
+         * Present on media errors. MEDIA_UNDECODABLE means the bytes at the URL are not a valid image, video or PDF.
+         */
+        code?: 'MEDIA_UNDECODABLE';
     }>;
     warnings?: Array<{
         platform?: string;
@@ -26007,13 +26015,39 @@ type ValidateMediaResponse = ({
      * Error message if valid is false
      */
     error?: string;
+    /**
+     * Stable reason when valid is false. MEDIA_UNDECODABLE: the bytes are not a valid image, video or PDF. MEDIA_URL_UNREACHABLE: HTTP error, timeout or network failure. MEDIA_URL_NOT_ALLOWED: not a public HTTP(S) URL.
+     */
+    code?: 'MEDIA_UNDECODABLE' | 'MEDIA_URL_UNREACHABLE' | 'MEDIA_URL_NOT_ALLOWED';
+    /**
+     * Content-Type header the server sent (may disagree with the detected format)
+     */
     contentType?: string;
     /**
      * File size in bytes
      */
     size?: (number) | null;
     sizeFormatted?: string;
-    type?: 'image' | 'video' | 'unknown';
+    /**
+     * Detected from the file bytes
+     */
+    type?: 'image' | 'video' | 'document';
+    /**
+     * Detected format (jpeg, png, webp, gif, heif, mp4, mov, webm, pdf, ...)
+     */
+    format?: string;
+    /**
+     * Image width in pixels (images only)
+     */
+    width?: number;
+    /**
+     * Image height in pixels (images only)
+     */
+    height?: number;
+    /**
+     * How deeply the content was verified. decoded: every pixel decoded. header: file signature and header verified (videos, PDFs, HEIC/AVIF, images over 32 MB).
+     */
+    inspection?: 'decoded' | 'header';
     /**
      * Per-platform size limit comparison (only present when size and type are known)
      */

package/dist/index.d.ts

@@ -18874,13 +18874,17 @@ type TikTokPlatformData = {
      */
     mediaType?: 'video' | 'photo';
     /**
-     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when videoCoverImageUrl is provided.
+     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when the videoCoverImageUrl image becomes the cover, and used when Zernio skips that image (see videoCoverImageUrl).
      */
     videoCoverTimestampMs?: number;
     /**
      * Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). Any downloadable URL works: we rehost it ourselves. Overrides videoCoverTimestampMs when provided.
      *
-     * The image is stitched as a single frame at the start of the video to serve as the cover. Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
+     * The image is stitched as a single frame at the start of the video to serve as the cover.
+     *
+     * When the image shape is far from the video shape (it would fill less than half of the frame, for example a landscape cover on a vertical video), or the stitch fails, Zernio skips the image and TikTok uses videoCoverTimestampMs.
+     *
+     * Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
      *
      */
     videoCoverImageUrl?: string;
@@ -25985,6 +25989,10 @@ type ValidatePostResponse = (({
     errors?: Array<{
         platform?: string;
         error?: string;
+        /**
+         * Present on media errors. MEDIA_UNDECODABLE means the bytes at the URL are not a valid image, video or PDF.
+         */
+        code?: 'MEDIA_UNDECODABLE';
     }>;
     warnings?: Array<{
         platform?: string;
@@ -26007,13 +26015,39 @@ type ValidateMediaResponse = ({
      * Error message if valid is false
      */
     error?: string;
+    /**
+     * Stable reason when valid is false. MEDIA_UNDECODABLE: the bytes are not a valid image, video or PDF. MEDIA_URL_UNREACHABLE: HTTP error, timeout or network failure. MEDIA_URL_NOT_ALLOWED: not a public HTTP(S) URL.
+     */
+    code?: 'MEDIA_UNDECODABLE' | 'MEDIA_URL_UNREACHABLE' | 'MEDIA_URL_NOT_ALLOWED';
+    /**
+     * Content-Type header the server sent (may disagree with the detected format)
+     */
     contentType?: string;
     /**
      * File size in bytes
      */
     size?: (number) | null;
     sizeFormatted?: string;
-    type?: 'image' | 'video' | 'unknown';
+    /**
+     * Detected from the file bytes
+     */
+    type?: 'image' | 'video' | 'document';
+    /**
+     * Detected format (jpeg, png, webp, gif, heif, mp4, mov, webm, pdf, ...)
+     */
+    format?: string;
+    /**
+     * Image width in pixels (images only)
+     */
+    width?: number;
+    /**
+     * Image height in pixels (images only)
+     */
+    height?: number;
+    /**
+     * How deeply the content was verified. decoded: every pixel decoded. header: file signature and header verified (videos, PDFs, HEIC/AVIF, images over 32 MB).
+     */
+    inspection?: 'decoded' | 'header';
     /**
      * Per-platform size limit comparison (only present when size and type are known)
      */

package/dist/index.js

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(index_exports);
 // package.json
 var package_default = {
   name: "@zernio/node",
-  version: "0.2.1520",
+  version: "0.2.1522",
   description: "The official Node.js library for the Zernio API",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/dist/index.mjs

@@ -5,7 +5,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 // package.json
 var package_default = {
   name: "@zernio/node",
-  version: "0.2.1520",
+  version: "0.2.1522",
   description: "The official Node.js library for the Zernio API",
   main: "dist/index.js",
   module: "dist/index.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zernio/node",
-  "version": "0.2.1520",
+  "version": "0.2.1522",
   "description": "The official Node.js library for the Zernio API",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/generated/sdk.gen.ts

@@ -43,7 +43,9 @@ export const validatePostLength = <ThrowOnError extends boolean = false>(options
  * Validate post content
  * Dry-run the full post validation pipeline without publishing. Catches issues like missing media for Instagram/TikTok/YouTube, hashtag limits, invalid thread formats, Facebook Reel requirements, and character limit violations.
  *
- * Accepts the same body as POST /v1/posts. Does NOT validate accounts, process media, or track usage. Account lookups are limit-only: a twitter accountId is resolved, scoped to the caller, only to pick the 280 vs 25000 character limit. Missing, foreign, or invalid ids fall back to 280 and never error.
+ * Accepts the same body as POST /v1/posts. Does NOT validate accounts, transform media, or track usage. Account lookups are limit-only: a twitter accountId is resolved, scoped to the caller, only to pick the 280 vs 25000 character limit. Missing, foreign, or invalid ids fall back to 280 and never error.
+ *
+ * Every image, gif and video URL in `mediaItems` and `customMedia` is fetched and checked: a file that is not a real image, video or PDF (wrong bytes, truncated, corrupt) is an error with code `MEDIA_UNDECODABLE`. Images are checked at header level (the full file is decoded only when the header is not enough); use POST /v1/tools/validate/media for a full pixel decode. A URL our servers cannot fetch is reported as a warning, not an error, because the platform may still reach it.
  *
  * Returns errors for failures and warnings for near-limit content (>90% of character limit).
  *
@@ -57,9 +59,9 @@ export const validatePost = <ThrowOnError extends boolean = false>(options: Opti
 
 /**
  * Validate media URL
- * Check if a media URL is accessible and return metadata (content type, file size) plus per-platform size limit comparisons.
+ * Check that a media URL is reachable and that its bytes are a real image, video or PDF, then return metadata (detected format, file size, dimensions) plus per-platform size limit comparisons.
  *
- * Performs a HEAD request (with GET fallback) to detect content type and size. Rejects private/localhost URLs for SSRF protection.
+ * `valid: true` means the content was verified, not just the extension or Content-Type. Images up to 32 MB are fully decoded (`inspection: decoded`); videos, PDFs and larger images are verified by their file signature and header (`inspection: header`). The type and format come from the bytes, not the Content-Type header. Corrupt, truncated or non-media files return `valid: false` with code `MEDIA_UNDECODABLE`. Rejects private/localhost URLs for SSRF protection.
  *
  * Platform limits are sourced from each platform's actual upload constraints.
  *

package/src/generated/types.gen.ts

@@ -17288,13 +17288,17 @@ export type TikTokPlatformData = {
      */
     mediaType?: 'video' | 'photo';
     /**
-     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when videoCoverImageUrl is provided.
+     * Optional for video posts. Timestamp in milliseconds to select which frame to use as thumbnail (defaults to 1000ms/1 second). Ignored when the videoCoverImageUrl image becomes the cover, and used when Zernio skips that image (see videoCoverImageUrl).
      */
     videoCoverTimestampMs?: number;
     /**
      * Optional for video posts. URL of a custom thumbnail image (JPG, PNG, or WebP, max 20MB). Any downloadable URL works: we rehost it ourselves. Overrides videoCoverTimestampMs when provided.
      *
-     * The image is stitched as a single frame at the start of the video to serve as the cover. Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
+     * The image is stitched as a single frame at the start of the video to serve as the cover.
+     *
+     * When the image shape is far from the video shape (it would fill less than half of the frame, for example a landscape cover on a vertical video), or the stitch fails, Zernio skips the image and TikTok uses videoCoverTimestampMs.
+     *
+     * Accounts connected through the TikTok for Business app instead hand it to TikTok as the cover, with no stitching, falling back to videoCoverTimestampMs without it.
      *
      */
     videoCoverImageUrl?: string;
@@ -24712,6 +24716,10 @@ export type ValidatePostResponse = (({
     errors?: Array<{
         platform?: string;
         error?: string;
+        /**
+         * Present on media errors. MEDIA_UNDECODABLE means the bytes at the URL are not a valid image, video or PDF.
+         */
+        code?: 'MEDIA_UNDECODABLE';
     }>;
     warnings?: Array<{
         platform?: string;
@@ -24737,13 +24745,39 @@ export type ValidateMediaResponse = ({
      * Error message if valid is false
      */
     error?: string;
+    /**
+     * Stable reason when valid is false. MEDIA_UNDECODABLE: the bytes are not a valid image, video or PDF. MEDIA_URL_UNREACHABLE: HTTP error, timeout or network failure. MEDIA_URL_NOT_ALLOWED: not a public HTTP(S) URL.
+     */
+    code?: 'MEDIA_UNDECODABLE' | 'MEDIA_URL_UNREACHABLE' | 'MEDIA_URL_NOT_ALLOWED';
+    /**
+     * Content-Type header the server sent (may disagree with the detected format)
+     */
     contentType?: string;
     /**
      * File size in bytes
      */
     size?: (number) | null;
     sizeFormatted?: string;
-    type?: 'image' | 'video' | 'unknown';
+    /**
+     * Detected from the file bytes
+     */
+    type?: 'image' | 'video' | 'document';
+    /**
+     * Detected format (jpeg, png, webp, gif, heif, mp4, mov, webm, pdf, ...)
+     */
+    format?: string;
+    /**
+     * Image width in pixels (images only)
+     */
+    width?: number;
+    /**
+     * Image height in pixels (images only)
+     */
+    height?: number;
+    /**
+     * How deeply the content was verified. decoded: every pixel decoded. header: file signature and header verified (videos, PDFs, HEIC/AVIF, images over 32 MB).
+     */
+    inspection?: 'decoded' | 'header';
     /**
      * Per-platform size limit comparison (only present when size and type are known)
      */