@zernio/node 0.2.783 → 0.2.785

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.783",
+  version: "0.2.785",
   description: "The official Node.js library for the Zernio API",
   main: "dist/index.js",
   module: "dist/index.mjs",
@@ -4725,12 +4725,17 @@ var downloadTikTokVideo = (options) => {
 
 // src/errors.ts
 var ZernioApiError = class _ZernioApiError extends Error {
-  constructor(message, statusCode, code, details) {
+  constructor(message, statusCode, code, details, body) {
     super(message);
     this.name = "ZernioApiError";
     this.statusCode = statusCode;
     this.code = code;
     this.details = details;
+    this.type = body?.type;
+    this.param = body?.param;
+    this.platform = body?.platform;
+    this.platformError = body?.platformError;
+    this.body = body;
     if (Error.captureStackTrace) {
       Error.captureStackTrace(this, _ZernioApiError);
     }
@@ -4774,8 +4779,8 @@ var ZernioApiError = class _ZernioApiError extends Error {
 };
 var LateApiError = ZernioApiError;
 var RateLimitError = class extends ZernioApiError {
-  constructor(message, limit, remaining, resetAt) {
-    super(message, 429, "rate_limit_exceeded");
+  constructor(message, limit, remaining, resetAt, body) {
+    super(message, 429, body?.code ?? "rate_limit_exceeded", body?.details, body);
     this.name = "RateLimitError";
     this.limit = limit;
     this.remaining = remaining;
@@ -4790,8 +4795,8 @@ var RateLimitError = class extends ZernioApiError {
   }
 };
 var ValidationError = class extends ZernioApiError {
-  constructor(message, fields) {
-    super(message, 400, "validation_error", { fields });
+  constructor(message, fields, body) {
+    super(message, 400, body?.code ?? "validation_error", body?.details ?? { fields }, body);
     this.name = "ValidationError";
     this.fields = fields;
   }
@@ -4808,13 +4813,14 @@ function parseApiError(response, body) {
       message,
       limit ? parseInt(limit, 10) : void 0,
       remaining ? parseInt(remaining, 10) : void 0,
-      reset ? new Date(parseInt(reset, 10) * 1e3) : void 0
+      reset ? new Date(parseInt(reset, 10) * 1e3) : void 0,
+      body
     );
   }
   if (response.status === 400 && details?.fields) {
-    return new ValidationError(message, details.fields);
+    return new ValidationError(message, details.fields, body);
   }
-  return new ZernioApiError(message, response.status, code, details);
+  return new ZernioApiError(message, response.status, code, details, body);
 }
 
 // src/client.ts

package/package.json

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

package/src/errors.ts

@@ -1,22 +1,57 @@
 /**
  * Base error class for Zernio API errors
  */
+/**
+ * The canonical error envelope the API returns. Everything but `error` is
+ * optional, and every field is surfaced on ZernioApiError: dropping any of them
+ * leaves callers unable to tell apart failures the API distinguishes. For a
+ * Meta pass-through in particular, `platformError.subcode` is the only thing
+ * that separates a closed messaging window from a blocked recipient, since both
+ * arrive as code `platform_api_error`.
+ */
+export interface ZernioErrorBody {
+  error?: string;
+  message?: string;
+  type?: string;
+  code?: string;
+  param?: string;
+  platform?: string;
+  platformError?: Record<string, unknown>;
+  details?: Record<string, unknown>;
+}
+
 export class ZernioApiError extends Error {
   public readonly statusCode: number;
   public readonly code?: string;
   public readonly details?: Record<string, unknown>;
+  /** Error class, e.g. invalid_request_error, platform_error, rate_limit_error. */
+  public readonly type?: string;
+  /** The request field that caused the error, when the API names one. */
+  public readonly param?: string;
+  /** Upstream platform, present when type is platform_error. */
+  public readonly platform?: string;
+  /** The upstream platform's own payload, verbatim (Meta: code, subcode, fbtrace_id). */
+  public readonly platformError?: Record<string, unknown>;
+  /** The parsed response body exactly as the API sent it, for anything not modelled above. */
+  public readonly body?: ZernioErrorBody;
 
   constructor(
     message: string,
     statusCode: number,
     code?: string,
-    details?: Record<string, unknown>
+    details?: Record<string, unknown>,
+    body?: ZernioErrorBody
   ) {
     super(message);
     this.name = 'ZernioApiError';
     this.statusCode = statusCode;
     this.code = code;
     this.details = details;
+    this.type = body?.type;
+    this.param = body?.param;
+    this.platform = body?.platform;
+    this.platformError = body?.platformError;
+    this.body = body;
 
     // Maintains proper stack trace for where error was thrown
     if (Error.captureStackTrace) {
@@ -82,9 +117,12 @@ export class RateLimitError extends ZernioApiError {
     message: string,
     limit?: number,
     remaining?: number,
-    resetAt?: Date
+    resetAt?: Date,
+    body?: ZernioErrorBody
   ) {
-    super(message, 429, 'rate_limit_exceeded');
+    // The envelope's own code wins when the API sent one: a Google Ads quota
+    // 429 and a Zernio rate limit are different failures.
+    super(message, 429, body?.code ?? 'rate_limit_exceeded', body?.details, body);
     this.name = 'RateLimitError';
     this.limit = limit;
     this.remaining = remaining;
@@ -106,8 +144,8 @@ export class RateLimitError extends ZernioApiError {
 export class ValidationError extends ZernioApiError {
   public readonly fields?: Record<string, string[]>;
 
-  constructor(message: string, fields?: Record<string, string[]>) {
-    super(message, 400, 'validation_error', { fields });
+  constructor(message: string, fields?: Record<string, string[]>, body?: ZernioErrorBody) {
+    super(message, 400, body?.code ?? 'validation_error', body?.details ?? { fields }, body);
     this.name = 'ValidationError';
     this.fields = fields;
   }
@@ -118,7 +156,7 @@ export class ValidationError extends ZernioApiError {
  */
 export function parseApiError(
   response: Response,
-  body?: { error?: string; message?: string; code?: string; details?: Record<string, unknown> }
+  body?: ZernioErrorBody
 ): ZernioApiError {
   const message = body?.error || body?.message || response.statusText || 'Unknown error';
   const code = body?.code;
@@ -134,14 +172,15 @@ export function parseApiError(
       message,
       limit ? parseInt(limit, 10) : undefined,
       remaining ? parseInt(remaining, 10) : undefined,
-      reset ? new Date(parseInt(reset, 10) * 1000) : undefined
+      reset ? new Date(parseInt(reset, 10) * 1000) : undefined,
+      body
     );
   }
 
   // Handle validation errors
   if (response.status === 400 && details?.fields) {
-    return new ValidationError(message, details.fields as Record<string, string[]>);
+    return new ValidationError(message, details.fields as Record<string, string[]>, body);
   }
 
-  return new ZernioApiError(message, response.status, code, details);
+  return new ZernioApiError(message, response.status, code, details, body);
 }

package/src/generated/types.gen.ts

@@ -3925,10 +3925,28 @@ export type ErrorResponse = {
         [key: string]: unknown;
     };
     /**
-     * Additional structured context (e.g. field-level validation errors), for example `privateReplyConsumed` on the private-reply endpoint's 400 when the comment's single reply is already spent.
+     * Additional structured context (e.g. field-level validation errors), for example
+     * `privateReplyConsumed` on the private-reply endpoint's 400 when the comment's
+     * single reply is already spent.
+     *
+     * On a Google Ads 429 it carries `quotaExhausted: true`, which marks the failure as
+     * Google's own ads quota rather than a Zernio rate limit, so you can keep calling
+     * other platforms instead of backing off everywhere. When Google names the scope it
+     * also carries `quotaScope`: `DEVELOPER` means the shared developer-token budget
+     * (every Google account is affected and there is nothing to change on your side),
+     * `ACCOUNT` means your own ad account. A Meta 429 carries neither field.
+     *
      */
     details?: {
-        [key: string]: unknown;
+        /**
+         * Google Ads 429 only. True when the upstream Google Ads quota is spent rather than a Zernio limit.
+         */
+        quotaExhausted?: boolean;
+        /**
+         * Google Ads 429 only, when Google names the scope. DEVELOPER is the shared developer-token budget; ACCOUNT is your ad account.
+         */
+        quotaScope?: 'DEVELOPER' | 'ACCOUNT';
+        [key: string]: unknown | boolean | string;
     };
 };
 
@@ -3937,6 +3955,11 @@ export type ErrorResponse = {
  */
 export type type4 = 'invalid_request_error' | 'authentication_error' | 'permission_error' | 'not_found' | 'rate_limit_error' | 'platform_error' | 'api_error';
 
+/**
+ * Google Ads 429 only, when Google names the scope. DEVELOPER is the shared developer-token budget; ACCOUNT is your ad account.
+ */
+export type quotaScope = 'DEVELOPER' | 'ACCOUNT';
+
 /**
  * A media item on a native (external/synced) post, as carried by post.external.* webhook payloads. Distinct from the richer MediaItem used for Zernio-authored posts: external items are always already-published and limited to image or video. Kept as a separate schema so the generated SDK model does not collide with MediaItem.
  *
@@ -24330,7 +24353,7 @@ export type ReplyToInboxReviewResponse = ({
     platform?: string;
 });
 
-export type ReplyToInboxReviewError = ({
+export type ReplyToInboxReviewError = (ErrorResponse | {
     error?: string;
 } | unknown);