@zernio/node 0.2.145 → 0.2.147

package/dist/index.d.mts

@@ -6141,6 +6141,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 = ({
@@ -14129,6 +14136,10 @@ type GetAdsTimelineError = ({
 } | unknown);
 type GetAdData = {
     path: {
+        /**
+         * Zernio `_id` (hex), Meta `platformAdId` (numeric), or one of the creative's effective story/media IDs. See description for details.
+         *
+         */
         adId: string;
     };
 };

package/dist/index.d.ts

@@ -6141,6 +6141,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 = ({
@@ -14129,6 +14136,10 @@ type GetAdsTimelineError = ({
 } | unknown);
 type GetAdData = {
     path: {
+        /**
+         * Zernio `_id` (hex), Meta `platformAdId` (numeric), or one of the creative's effective story/media IDs. See description for details.
+         *
+         */
         adId: string;
     };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zernio/node",
-  "version": "0.2.145",
+  "version": "0.2.147",
   "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>) => {
@@ -3493,6 +3509,15 @@ export const getAdsTimeline = <ThrowOnError extends boolean = false>(options: Op
 /**
  * Get ad details
  * Returns an ad with its creative, targeting, status, and performance metrics.
+ *
+ * The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad:
+ * - the Zernio internal `_id` (24-char hex)
+ * - Meta's numeric `platformAdId` (the value shipped in `comment.received` webhooks as `comment.ad.id`)
+ * - the creative's `effective_object_story_id` (`{pageId}_{postId}` shape, Facebook side)
+ * - the creative's `effective_instagram_media_id` (Instagram side)
+ *
+ * Any of the four resolve to the same ad. Caller doesn't need a translation step.
+ *
  */
 export const getAd = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<GetAdData, ThrowOnError>) => {
     return (options?.client ?? client).get<GetAdResponse, GetAdError, ThrowOnError>({
@@ -3570,6 +3595,12 @@ export const getAdAnalytics = <ThrowOnError extends boolean = false>(options: Op
  *
  * Requires the Ads add-on. Response shape matches GET /v1/inbox/comments/{postId}.
  *
+ * The `{adId}` path segment accepts any identifier dialect Zernio indexes for the ad:
+ * Zernio internal `_id` (24-char hex), Meta's numeric `platformAdId` (the value shipped in
+ * `comment.received` webhooks as `comment.ad.id`), or the creative's
+ * `effective_object_story_id` / `effective_instagram_media_id`. Caller doesn't need a
+ * translation step.
+ *
  */
 export const getAdComments = <ThrowOnError extends boolean = false>(options: OptionsLegacyParser<GetAdCommentsData, ThrowOnError>) => {
     return (options?.client ?? client).get<GetAdCommentsResponse, GetAdCommentsError, ThrowOnError>({

package/src/generated/types.gen.ts

@@ -5797,6 +5797,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);
@@ -14457,6 +14464,10 @@ export type GetAdsTimelineError = ({
 
 export type GetAdData = {
     path: {
+        /**
+         * Zernio `_id` (hex), Meta `platformAdId` (numeric), or one of the creative's effective story/media IDs. See description for details.
+         *
+         */
         adId: string;
     };
 };