@zernio/node 0.2.146 → 0.2.148

package/dist/index.d.mts

@@ -1822,7 +1822,7 @@ type ErrorResponse = {
     };
 };
 /**
- * Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.
+ * Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Carousel posts (carouselCards) render a 2-5 card multi-link post, images only, mutually exclusive with story/reel. Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.
  *
  */
 type FacebookPlatformData = {
@@ -1847,6 +1847,29 @@ type FacebookPlatformData = {
      */
     pageId?: string;
     geoRestriction?: GeoRestriction;
+    /**
+     * Renders the post as a multi-link carousel (organic Page post). When set, mediaItems must be provided with the same length and all items must be images (no videos). Each cards[i] adds the click-through link and headline for the image at mediaItems[i]. Mutually exclusive with contentType=story|reel. Facebook display truncates name at ~35 chars and description at ~30 chars; longer strings are accepted but get truncated on render.
+     *
+     */
+    carouselCards?: Array<{
+        /**
+         * Per-card click destination (required).
+         */
+        link: string;
+        /**
+         * Per-card headline (optional, ~35-char display).
+         */
+        name?: string;
+        /**
+         * Per-card subhead (optional, ~30-char display).
+         */
+        description?: string;
+    }>;
+    /**
+     * Optional top-level "See more" destination shown on the carousel end card. Defaults to the first card's link when omitted. Only used together with carouselCards.
+     *
+     */
+    carouselLink?: string;
 };
 /**
  * Set to 'story' for Page Stories (24h ephemeral) or 'reel' for Reels (short vertical video). Defaults to feed post if omitted.
@@ -6141,6 +6164,13 @@ type CreatePostData = {
          */
         queueId?: string;
     };
+    headers?: {
+        /**
+         * Optional client-generated request identifier for safe retry (idempotency). When two requests carry the same value, the second is treated as a retry of the first and returns the original post (HTTP 200) instead of creating a duplicate. Window is ~5 minutes from the first request. Generate a UUID per logical call. SDKs do this automatically; HTTP clients should set it themselves or omit it. See the operation description for the full idempotency contract.
+         *
+         */
+        'x-request-id'?: string;
+    };
 };
 type CreatePostResponse = (PostCreateResponse);
 type CreatePostError = ({

package/dist/index.d.ts

@@ -1822,7 +1822,7 @@ type ErrorResponse = {
     };
 };
 /**
- * Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.
+ * Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Carousel posts (carouselCards) render a 2-5 card multi-link post, images only, mutually exclusive with story/reel. Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.
  *
  */
 type FacebookPlatformData = {
@@ -1847,6 +1847,29 @@ type FacebookPlatformData = {
      */
     pageId?: string;
     geoRestriction?: GeoRestriction;
+    /**
+     * Renders the post as a multi-link carousel (organic Page post). When set, mediaItems must be provided with the same length and all items must be images (no videos). Each cards[i] adds the click-through link and headline for the image at mediaItems[i]. Mutually exclusive with contentType=story|reel. Facebook display truncates name at ~35 chars and description at ~30 chars; longer strings are accepted but get truncated on render.
+     *
+     */
+    carouselCards?: Array<{
+        /**
+         * Per-card click destination (required).
+         */
+        link: string;
+        /**
+         * Per-card headline (optional, ~35-char display).
+         */
+        name?: string;
+        /**
+         * Per-card subhead (optional, ~30-char display).
+         */
+        description?: string;
+    }>;
+    /**
+     * Optional top-level "See more" destination shown on the carousel end card. Defaults to the first card's link when omitted. Only used together with carouselCards.
+     *
+     */
+    carouselLink?: string;
 };
 /**
  * Set to 'story' for Page Stories (24h ephemeral) or 'reel' for Reels (short vertical video). Defaults to feed post if omitted.
@@ -6141,6 +6164,13 @@ type CreatePostData = {
          */
         queueId?: string;
     };
+    headers?: {
+        /**
+         * Optional client-generated request identifier for safe retry (idempotency). When two requests carry the same value, the second is treated as a retry of the first and returns the original post (HTTP 200) instead of creating a duplicate. Window is ~5 minutes from the first request. Generate a UUID per logical call. SDKs do this automatically; HTTP clients should set it themselves or omit it. See the operation description for the full idempotency contract.
+         *
+         */
+        'x-request-id'?: string;
+    };
 };
 type CreatePostResponse = (PostCreateResponse);
 type CreatePostError = ({

package/package.json

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

package/src/generated/sdk.gen.ts

@@ -510,8 +510,24 @@ export const listPosts = <ThrowOnError extends boolean = false>(options?: Option
 
 /**
  * Create post
- * Create and optionally publish a post. Immediate posts (publishNow: true) include platformPostUrl in the response.
- * Content is optional when media is attached or all platforms have customContent. See each platform's schema for media constraints.
+ * Create and optionally publish a post. Immediate posts (`publishNow: true`) include `platformPostUrl` in the response.
+ * Content is optional when media is attached or all platforms have `customContent`. See each platform's schema for media constraints.
+ *
+ * ## Idempotency
+ *
+ * Two layers of duplicate-protection apply, so safe-to-retry callers (network blips, n8n / Zapier retries, etc.) don't accidentally double-post.
+ *
+ * **1. Same-request idempotency (5-minute window).**
+ * Pass an `x-request-id` header to mark a logical request. If a second request arrives with the same `x-request-id` while the first is in-flight (or within ~5 minutes of completion), we return **HTTP 200** with the original post in the `existingPost` field — no new post is created. The official Zernio SDKs auto-generate a unique `x-request-id` per call. If you're using a generic HTTP client (curl, n8n's HTTP node, Zapier, custom code), either:
+ * - Set a unique `x-request-id` per logical call (recommended — UUIDv4 is fine)
+ * - Or simply omit the header — we'll treat each request as new
+ *
+ * **Common pitfall**: if your workflow tool uses a single execution-level request ID and reuses it across multiple HTTP nodes (e.g. one ID for the whole run, shared across 6 different platform calls), every call after the first will look like a retry of the first and return its post. Generate a fresh ID per node.
+ *
+ * **2. Content-hash dedup (24-hour window).**
+ * Independently, we hash `(platform, accountId, content + media URLs)` and reject duplicates within 24 hours with **HTTP 409**. This catches genuine "same content posted twice to the same account" cases regardless of `x-request-id`. Returns `error`, `accountId`, `platform`, and `existingPostId` so you can find the original. To intentionally re-post identical content within 24h, change something (the caption, the media, the account) — the dedup is keyed on the full content fingerprint.
+ *
+ * Order: same-`x-request-id` retries (200) are checked first; if no idempotency match, the content-hash dedup (409) runs.
  *
  */
 export const createPost = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<CreatePostData, ThrowOnError>) => {

package/src/generated/types.gen.ts

@@ -1227,7 +1227,7 @@ export type ErrorResponse = {
 };
 
 /**
- * Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.
+ * Feed posts support up to 10 images (no mixed video+image). Stories require single media (24h, no captions). Reels require single vertical video (9:16, 3-60s). Carousel posts (carouselCards) render a 2-5 card multi-link post, images only, mutually exclusive with story/reel. Geo-restriction is a hard visibility restriction: users outside the specified countries cannot see the post. Not supported for stories.
  *
  */
 export type FacebookPlatformData = {
@@ -1252,6 +1252,29 @@ export type FacebookPlatformData = {
      */
     pageId?: string;
     geoRestriction?: GeoRestriction;
+    /**
+     * Renders the post as a multi-link carousel (organic Page post). When set, mediaItems must be provided with the same length and all items must be images (no videos). Each cards[i] adds the click-through link and headline for the image at mediaItems[i]. Mutually exclusive with contentType=story|reel. Facebook display truncates name at ~35 chars and description at ~30 chars; longer strings are accepted but get truncated on render.
+     *
+     */
+    carouselCards?: Array<{
+        /**
+         * Per-card click destination (required).
+         */
+        link: string;
+        /**
+         * Per-card headline (optional, ~35-char display).
+         */
+        name?: string;
+        /**
+         * Per-card subhead (optional, ~30-char display).
+         */
+        description?: string;
+    }>;
+    /**
+     * Optional top-level "See more" destination shown on the carousel end card. Defaults to the first card's link when omitted. Only used together with carouselCards.
+     *
+     */
+    carouselLink?: string;
 };
 
 /**
@@ -5797,6 +5820,13 @@ export type CreatePostData = {
          */
         queueId?: string;
     };
+    headers?: {
+        /**
+         * Optional client-generated request identifier for safe retry (idempotency). When two requests carry the same value, the second is treated as a retry of the first and returns the original post (HTTP 200) instead of creating a duplicate. Window is ~5 minutes from the first request. Generate a UUID per logical call. SDKs do this automatically; HTTP clients should set it themselves or omit it. See the operation description for the full idempotency contract.
+         *
+         */
+        'x-request-id'?: string;
+    };
 };
 
 export type CreatePostResponse = (PostCreateResponse);