ad2app-lib 1.20.0 → 1.22.0

package/dist/api/apiDriver.d.ts

@@ -1,9 +1,25 @@
 import { FetchParams } from "../types";
-type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+type HttpMethod = "get" | "post" | "put" | "PATCH" | "delete";
 interface DriverConfig {
     apiUrl: string;
     getHeaders?: () => HeadersInit;
 }
+/**
+ * Thrown by `fetchCall` for any non-2xx response.
+ *
+ * Previously this was a bare `Error` carrying only the response body text, so
+ * the HTTP status — the one piece of information a caller needs to tell
+ * "you sent the wrong thing" apart from "you're not allowed" apart from
+ * "reload and try again" — was discarded at the driver. Callers had no way to
+ * branch, so every failure collapsed into one generic message. Keeping
+ * `message` byte-identical to the old value means existing `catch` blocks that
+ * read it are unaffected; `status` is purely additive.
+ */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
 export declare function configureApiDriver(config: DriverConfig): void;
 type FetchCallArgs<Q> = {
     path?: string;

package/dist/api/apiDriver.js

@@ -1,9 +1,32 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiError = void 0;
 exports.configureApiDriver = configureApiDriver;
 exports.fetchCall = fetchCall;
 exports.apiDriver = apiDriver;
 const utils_1 = require("./utils");
+/**
+ * Thrown by `fetchCall` for any non-2xx response.
+ *
+ * Previously this was a bare `Error` carrying only the response body text, so
+ * the HTTP status — the one piece of information a caller needs to tell
+ * "you sent the wrong thing" apart from "you're not allowed" apart from
+ * "reload and try again" — was discarded at the driver. Callers had no way to
+ * branch, so every failure collapsed into one generic message. Keeping
+ * `message` byte-identical to the old value means existing `catch` blocks that
+ * read it are unaffected; `status` is purely additive.
+ */
+class ApiError extends Error {
+    constructor(message, status, body) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.body = body;
+        // Required for `instanceof` to work when the output is transpiled to ES5.
+        Object.setPrototypeOf(this, ApiError.prototype);
+    }
+}
+exports.ApiError = ApiError;
 let CONFIG;
 function configureApiDriver(config) {
     CONFIG = config;
@@ -49,7 +72,7 @@ async function fetchCall(args) {
         catch {
             // non-JSON error body: keep the raw text
         }
-        throw new Error(message || `Request failed with status ${res.status}`);
+        throw new ApiError(message || `Request failed with status ${res.status}`, res.status, rawBody);
     }
     if (!rawBody)
         return undefined;
@@ -83,7 +106,13 @@ function apiDriver(baseUrl) {
         patch: (...args) => fetchCall({
             ...args[1],
             path: args[0],
-            method: "patch",
+            // MUST be uppercase: the Fetch spec normalizes get/post/put/delete to
+            // uppercase but deliberately NOT patch, so a lowercase "patch" reaches
+            // the CORS preflight as-is and fails the server's case-sensitive
+            // PATCH allow-list — every cross-origin PATCH from the app failed
+            // with net::ERR_FAILED. Caught live by the 015 coverage suite
+            // (2026-08-02) on the marketing-consent toggle.
+            method: "PATCH",
             baseUrl,
         }),
         delete: (...args) => fetchCall({

package/dist/api/utils.js

@@ -4,9 +4,18 @@ exports.insertParams = exports.extractParams = exports.createQueryString = expor
 const concatApiPaths = (apiUrl, endpoint) => apiUrl + '/' + endpoint;
 exports.concatApiPaths = concatApiPaths;
 const createQueryString = (fetchParams) => {
-    return fetchParams?.query
-        ? '?' + new URLSearchParams(fetchParams.query).toString()
-        : '';
+    if (!fetchParams?.query) {
+        return '';
+    }
+    // URLSearchParams stringifies missing values ({ platform: undefined } →
+    // "platform=undefined"), so optional params must be dropped before
+    // serialization. Falsy-but-real values (0, '', false) are kept.
+    const definedEntries = Object.entries(fetchParams.query).filter(([, value]) => value !== undefined && value !== null);
+    if (definedEntries.length === 0) {
+        return '';
+    }
+    return ('?' +
+        new URLSearchParams(definedEntries.map(([key, value]) => [key, String(value)])).toString());
 };
 exports.createQueryString = createQueryString;
 const extractParams = (path) => {

package/dist/types/scheduling/I_SchedulingAnalytics.d.ts

@@ -23,6 +23,12 @@ export declare class SchedulingAnalyticsKpiDTO {
     views: number;
     engagementRate: number;
     followerGrowth: number;
+    /**
+     * Range growth percentage derived from Zernio's authoritative growth
+     * totals (growth ÷ range-start followers — 050 FR-10 fast-follow).
+     * Absent when the range-start base is unknown or zero; never fabricated.
+     */
+    followerGrowthPercentage?: number;
     /**
      * Sources that were unavailable when this response was assembled
      * (AD2-1045). Absent/empty = all sources healthy. When present, the

package/dist/types/scheduling/I_SchedulingAnalytics.js

@@ -31,6 +31,9 @@ class SchedulingAnalyticsKpiDTO {
         this.views = data.views;
         this.engagementRate = data.engagementRate;
         this.followerGrowth = data.followerGrowth;
+        if (data.followerGrowthPercentage !== undefined) {
+            this.followerGrowthPercentage = data.followerGrowthPercentage;
+        }
         if (data.failedSources !== undefined) {
             this.failedSources = data.failedSources;
         }

package/dist/types/scheduling/I_SchedulingInbox.d.ts

@@ -180,13 +180,17 @@ export declare class SchedulingCommentModerationDTO {
 }
 /**
  * Input for starting a new DM — POST /social/inbox/conversations → Zernio
- * POST /v1/inbox/conversations (OpenAPI v1.0.4:20355). WhatsApp is excluded
- * (it requires an approved template to open a thread; 082 non-goal).
+ * POST /v1/inbox/conversations (OpenAPI v1.0.4:20488). WhatsApp is excluded
+ * (it requires an approved template to open a thread; 082 non-goal). Field
+ * names mirror the wire exactly: accountId is required; the recipient is
+ * EITHER participantId (numeric id / phone) OR participantUsername (handle) —
+ * provide one; the body text is `message`, not `text`.
  */
 export declare class SchedulingCreateConversationDTO {
     accountId: string;
-    recipientId: string;
-    text: string;
+    participantId?: string;
+    participantUsername?: string;
+    message: string;
     constructor(data: SchedulingCreateConversationDTO);
 }
 /**

package/dist/types/scheduling/I_SchedulingInbox.js

@@ -208,14 +208,18 @@ exports.SchedulingCommentModerationDTO = SchedulingCommentModerationDTO;
 // ── SchedulingCreateConversationDTO ───────────────────────────────────────────
 /**
  * Input for starting a new DM — POST /social/inbox/conversations → Zernio
- * POST /v1/inbox/conversations (OpenAPI v1.0.4:20355). WhatsApp is excluded
- * (it requires an approved template to open a thread; 082 non-goal).
+ * POST /v1/inbox/conversations (OpenAPI v1.0.4:20488). WhatsApp is excluded
+ * (it requires an approved template to open a thread; 082 non-goal). Field
+ * names mirror the wire exactly: accountId is required; the recipient is
+ * EITHER participantId (numeric id / phone) OR participantUsername (handle) —
+ * provide one; the body text is `message`, not `text`.
  */
 class SchedulingCreateConversationDTO {
     constructor(data) {
         this.accountId = data.accountId;
-        this.recipientId = data.recipientId;
-        this.text = data.text;
+        this.participantId = data.participantId;
+        this.participantUsername = data.participantUsername;
+        this.message = data.message;
     }
 }
 exports.SchedulingCreateConversationDTO = SchedulingCreateConversationDTO;

package/dist/types/scheduling/I_SchedulingPost.d.ts

@@ -125,6 +125,15 @@ export declare class SchedulingPostDTO {
     content?: string;
     mediaItems?: SchedulingPostMediaItemDTO[];
     platformTargets?: SchedulingPostTargetDTO[];
+    /**
+     * Per-post engagement, populated only by the analytics "top posts" path
+     * (enriched from Zernio GET /v1/analytics). Absent on ordinary post listings —
+     * undefined means "not fetched", distinct from a real 0 (AD2-1079).
+     */
+    totalEngagements?: number;
+    likes?: number;
+    comments?: number;
+    shares?: number;
     constructor(data: SchedulingPostDTO);
 }
 /** Query parameters for listing posts with optional filters. */

package/dist/types/scheduling/I_SchedulingPost.js

@@ -134,6 +134,10 @@ class SchedulingPostDTO {
         this.content = data.content;
         this.mediaItems = data.mediaItems;
         this.platformTargets = data.platformTargets;
+        this.totalEngagements = data.totalEngagements;
+        this.likes = data.likes;
+        this.comments = data.comments;
+        this.shares = data.shares;
     }
 }
 exports.SchedulingPostDTO = SchedulingPostDTO;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.20.0",
+  "version": "1.22.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -47,7 +47,7 @@
     "prepare": "npm run build"
   },
   "keywords": [],
-  "author": "Maciej G\u00f3rski@ad2.app",
+  "author": "Maciej Górski@ad2.app",
   "license": "ISC",
   "description": "Package to share types and utils across the ad2app projects",
   "dependencies": {

package/src/api/apiDriver.test.ts

@@ -6,7 +6,7 @@
 import assert from "node:assert/strict";
 import { afterEach, beforeEach, test } from "node:test";
 
-import { apiDriver, configureApiDriver, fetchCall } from "./apiDriver";
+import { ApiError, apiDriver, configureApiDriver, fetchCall } from "./apiDriver";
 
 configureApiDriver({ apiUrl: "https://default.test" });
 
@@ -81,3 +81,48 @@ test("fetchCall surfaces a JSON error body in the thrown message", async () => {
   status = 400;
   await assert.rejects(() => fetchCall({ path: "x", method: "get" }), /nope/);
 });
+
+/**
+ * The status used to be dropped at the driver, so a caller could not tell a
+ * 400 ("your input is stale — refetch and retry") from a 403 ("you are not
+ * allowed") from a 500. Every failure collapsed into one generic message. These
+ * pin the status onto the thrown error for every non-2xx shape.
+ */
+test("a non-2xx throws an ApiError carrying the HTTP status", async () => {
+  for (const expected of [400, 401, 403, 404, 429, 500, 503]) {
+    body = JSON.stringify({ message: "nope", statusCode: expected });
+    status = expected;
+    const err = await fetchCall({ path: "x", method: "get" }).then(
+      () => null,
+      (e: unknown) => e
+    );
+    assert.ok(err instanceof ApiError, `${expected} should throw an ApiError`);
+    assert.equal(err.status, expected);
+    assert.equal(err.name, "ApiError");
+  }
+});
+
+test("ApiError is still an Error and keeps the body text in message", async () => {
+  body = "Service Unavailable";
+  status = 503;
+  const err = await fetchCall({ path: "x", method: "get" }).then(
+    () => null,
+    (e: unknown) => e
+  );
+  // Existing callers only ever read `.message` — that must not shift.
+  assert.ok(err instanceof Error);
+  assert.match((err as Error).message, /Service Unavailable/);
+  assert.equal((err as ApiError).body, "Service Unavailable");
+});
+
+test("an empty error body still carries the status, not just a generic message", async () => {
+  body = null;
+  status = 502;
+  const err = await fetchCall({ path: "x", method: "get" }).then(
+    () => null,
+    (e: unknown) => e
+  );
+  assert.ok(err instanceof ApiError);
+  assert.equal(err.status, 502);
+  assert.match(err.message, /502/);
+});

package/src/api/apiDriver.ts

@@ -1,13 +1,41 @@
 import { FetchParams } from "../types";
 import { concatApiPaths, createQueryString, insertParams } from "./utils";
 
-type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+// PATCH is uppercase by necessity: the Fetch spec normalizes the other four
+// to uppercase but NOT patch, and CORS preflight matching is case-sensitive
+// (see the patch call below).
+type HttpMethod = "get" | "post" | "put" | "PATCH" | "delete";
 
 interface DriverConfig {
   apiUrl: string;
   getHeaders?: () => HeadersInit;
 }
 
+/**
+ * Thrown by `fetchCall` for any non-2xx response.
+ *
+ * Previously this was a bare `Error` carrying only the response body text, so
+ * the HTTP status — the one piece of information a caller needs to tell
+ * "you sent the wrong thing" apart from "you're not allowed" apart from
+ * "reload and try again" — was discarded at the driver. Callers had no way to
+ * branch, so every failure collapsed into one generic message. Keeping
+ * `message` byte-identical to the old value means existing `catch` blocks that
+ * read it are unaffected; `status` is purely additive.
+ */
+export class ApiError extends Error {
+  readonly status: number;
+  readonly body: string;
+
+  constructor(message: string, status: number, body: string) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.body = body;
+    // Required for `instanceof` to work when the output is transpiled to ES5.
+    Object.setPrototypeOf(this, ApiError.prototype);
+  }
+}
+
 let CONFIG: DriverConfig;
 
 export function configureApiDriver(config: DriverConfig) {
@@ -77,7 +105,11 @@ export async function fetchCall<T, Q>(args: FetchCallArgs<Q>): Promise<T> {
     } catch {
       // non-JSON error body: keep the raw text
     }
-    throw new Error(message || `Request failed with status ${res.status}`);
+    throw new ApiError(
+      message || `Request failed with status ${res.status}`,
+      res.status,
+      rawBody
+    );
   }
 
   if (!rawBody) return undefined as T;
@@ -120,7 +152,13 @@ export function apiDriver(baseUrl?: string) {
       fetchCall<T, Q>({
         ...args[1],
         path: args[0],
-        method: "patch",
+        // MUST be uppercase: the Fetch spec normalizes get/post/put/delete to
+        // uppercase but deliberately NOT patch, so a lowercase "patch" reaches
+        // the CORS preflight as-is and fails the server's case-sensitive
+        // PATCH allow-list — every cross-origin PATCH from the app failed
+        // with net::ERR_FAILED. Caught live by the 015 coverage suite
+        // (2026-08-02) on the marketing-consent toggle.
+        method: "PATCH",
         baseUrl,
       }),
     delete: <T, Q>(...args: MethodCallArgs<Q>) =>

package/src/api/utils.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Unit tests for createQueryString. Covers the AD2 serialization bug found
+ * 2026-07-26: URLSearchParams stringifies undefined/null values, so callers
+ * passing optional params ({ platform: undefined }) produced live requests
+ * carrying the literal strings "?platform=undefined" / "null".
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { createQueryString } from "./utils";
+
+test("serializes defined params", () => {
+  assert.equal(
+    createQueryString({ query: { platform: "instagram", limit: 20 } }),
+    "?platform=instagram&limit=20"
+  );
+});
+
+test("omits undefined values instead of serializing the string 'undefined'", () => {
+  assert.equal(
+    createQueryString({
+      query: { fromDate: "2026-06-28", platform: undefined, contentType: undefined },
+    }),
+    "?fromDate=2026-06-28"
+  );
+});
+
+test("omits null values instead of serializing the string 'null'", () => {
+  assert.equal(
+    createQueryString({ query: { platform: null, status: "scheduled" } }),
+    "?status=scheduled"
+  );
+});
+
+test("returns empty string when every value is undefined", () => {
+  assert.equal(createQueryString({ query: { platform: undefined } }), "");
+});
+
+test("returns empty string with no query at all", () => {
+  assert.equal(createQueryString(), "");
+  assert.equal(createQueryString({}), "");
+});
+
+test("keeps falsy-but-real values (0, empty string, false)", () => {
+  assert.equal(
+    createQueryString({ query: { offset: 0, q: "", includeRead: false } }),
+    "?offset=0&q=&includeRead=false"
+  );
+});

package/src/api/utils.ts

@@ -4,9 +4,27 @@ export const concatApiPaths = (apiUrl: string, endpoint: string) =>
   apiUrl + '/' + endpoint;
 
 export const createQueryString = <T>(fetchParams?: FetchParams<T>) => {
-  return fetchParams?.query
-    ? '?' + new URLSearchParams(fetchParams.query as URLSearchParams).toString()
-    : '';
+  if (!fetchParams?.query) {
+    return '';
+  }
+
+  // URLSearchParams stringifies missing values ({ platform: undefined } →
+  // "platform=undefined"), so optional params must be dropped before
+  // serialization. Falsy-but-real values (0, '', false) are kept.
+  const definedEntries = Object.entries(
+    fetchParams.query as Record<string, unknown>
+  ).filter(([, value]) => value !== undefined && value !== null);
+
+  if (definedEntries.length === 0) {
+    return '';
+  }
+
+  return (
+    '?' +
+    new URLSearchParams(
+      definedEntries.map(([key, value]) => [key, String(value)])
+    ).toString()
+  );
 };
 
 export const extractParams = (path: string): string[] => {

package/src/types/scheduling/I_SchedulingAnalytics.ts

@@ -35,6 +35,12 @@ export class SchedulingAnalyticsKpiDTO {
   views: number;
   engagementRate: number;
   followerGrowth: number;
+  /**
+   * Range growth percentage derived from Zernio's authoritative growth
+   * totals (growth ÷ range-start followers — 050 FR-10 fast-follow).
+   * Absent when the range-start base is unknown or zero; never fabricated.
+   */
+  followerGrowthPercentage?: number;
   /**
    * Sources that were unavailable when this response was assembled
    * (AD2-1045). Absent/empty = all sources healthy. When present, the
@@ -64,6 +70,9 @@ export class SchedulingAnalyticsKpiDTO {
     this.views = data.views;
     this.engagementRate = data.engagementRate;
     this.followerGrowth = data.followerGrowth;
+    if (data.followerGrowthPercentage !== undefined) {
+      this.followerGrowthPercentage = data.followerGrowthPercentage;
+    }
     if (data.failedSources !== undefined) {
       this.failedSources = data.failedSources;
     }

package/src/types/scheduling/I_SchedulingInbox.test.ts

@@ -207,15 +207,34 @@ test('SchedulingInboxCapabilityDTO exposes per-surface booleans', () => {
   assert.equal(cap.dm, false);
 });
 
-test('SchedulingCreateConversationDTO carries account, recipient, text', () => {
+// sig-c276683e78bd9f37 — Zernio POST /v1/inbox/conversations (OpenAPI
+// v1.0.4:20488) takes participantId/participantUsername + message, not
+// recipientId/text; assert the SERIALIZED wire shape, not just the DTO's
+// own field names, so a future rename can't drift from the contract again.
+test('SchedulingCreateConversationDTO serializes to the Zernio wire shape (accountId, participantId, message)', () => {
   const dto = new SchedulingCreateConversationDTO({
     accountId: 'a1',
-    recipientId: 'r1',
-    text: 'hello',
+    participantId: 'r1',
+    message: 'hello',
   });
+  const wireKeys = Object.keys(JSON.parse(JSON.stringify(dto))).sort();
+  assert.deepEqual(wireKeys, ['accountId', 'message', 'participantId']);
   assert.equal(dto.accountId, 'a1');
-  assert.equal(dto.recipientId, 'r1');
-  assert.equal(dto.text, 'hello');
+  assert.equal(dto.participantId, 'r1');
+  assert.equal(dto.message, 'hello');
+  assert.equal((dto as Record<string, unknown>).recipientId, undefined);
+  assert.equal((dto as Record<string, unknown>).text, undefined);
+});
+
+test('SchedulingCreateConversationDTO accepts participantUsername in place of participantId', () => {
+  const dto = new SchedulingCreateConversationDTO({
+    accountId: 'a1',
+    participantUsername: 'jane',
+    message: 'hello',
+  });
+  const wireKeys = Object.keys(JSON.parse(JSON.stringify(dto))).sort();
+  assert.deepEqual(wireKeys, ['accountId', 'message', 'participantUsername']);
+  assert.equal(dto.participantUsername, 'jane');
 });
 
 // Mark-read acknowledgement — unreadCount absent unless Zernio reports it.

package/src/types/scheduling/I_SchedulingInbox.ts

@@ -321,18 +321,23 @@ export class SchedulingCommentModerationDTO {
 
 /**
  * Input for starting a new DM — POST /social/inbox/conversations → Zernio
- * POST /v1/inbox/conversations (OpenAPI v1.0.4:20355). WhatsApp is excluded
- * (it requires an approved template to open a thread; 082 non-goal).
+ * POST /v1/inbox/conversations (OpenAPI v1.0.4:20488). WhatsApp is excluded
+ * (it requires an approved template to open a thread; 082 non-goal). Field
+ * names mirror the wire exactly: accountId is required; the recipient is
+ * EITHER participantId (numeric id / phone) OR participantUsername (handle) —
+ * provide one; the body text is `message`, not `text`.
  */
 export class SchedulingCreateConversationDTO {
   accountId: string;
-  recipientId: string;
-  text: string;
+  participantId?: string;
+  participantUsername?: string;
+  message: string;
 
   constructor(data: SchedulingCreateConversationDTO) {
     this.accountId = data.accountId;
-    this.recipientId = data.recipientId;
-    this.text = data.text;
+    this.participantId = data.participantId;
+    this.participantUsername = data.participantUsername;
+    this.message = data.message;
   }
 }
 

package/src/types/scheduling/I_SchedulingPost.ts

@@ -199,6 +199,15 @@ export class SchedulingPostDTO {
   content?: string;
   mediaItems?: SchedulingPostMediaItemDTO[];
   platformTargets?: SchedulingPostTargetDTO[];
+  /**
+   * Per-post engagement, populated only by the analytics "top posts" path
+   * (enriched from Zernio GET /v1/analytics). Absent on ordinary post listings —
+   * undefined means "not fetched", distinct from a real 0 (AD2-1079).
+   */
+  totalEngagements?: number;
+  likes?: number;
+  comments?: number;
+  shares?: number;
 
   constructor(data: SchedulingPostDTO) {
     this.id = data.id;
@@ -219,6 +228,10 @@ export class SchedulingPostDTO {
     this.content = data.content;
     this.mediaItems = data.mediaItems;
     this.platformTargets = data.platformTargets;
+    this.totalEngagements = data.totalEngagements;
+    this.likes = data.likes;
+    this.comments = data.comments;
+    this.shares = data.shares;
   }
 }