ad2app-lib 1.20.0 → 1.21.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.20.0",
+  "version": "1.21.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/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;
     }