docs(sdk): engagementRate semantics; account rate is always null

Mirrors the server fixes in bulk-publish 5029cac and 4149e6d.

- Account-level engagementRate is documented and typed as always null: no
  handler computes one (the getAccountAnalytics contract has no such field),
  so it was the column default 0 on all 125 production rows and looked like a
  measured 0%. Both SDKs already allowed null, so nothing breaks.
- The two engagementRate fields on the engagement response are different
  numbers — post-level is a mean over the post's measurable channels,
  platformMetrics[] is one channel's own rate. Documented at both, since
  rendering the former beside the latter's counters is what produced a
  TikTok panel reading 0/0/0/0 and 24.55%.
- profileViews is Facebook-only, websiteClicks is Google-Business-only; a 0
  elsewhere means not reported.

node SDK 1.7.2, python SDK 0.8.2 (pyproject + __version__ in step).

Author: Azym

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2026-07-29 — analytics accuracy: engagementRate semantics (node SDK 1.7.2, python SDK 0.8.2)
+
+### Fixed
+
+- **`avgEngagementRate` on `GET /api/analytics/engagement` was averaged over only the posts with non-zero engagement.** The server stores `engagement_rate` as engagements ÷ impressions and writes 0 when impressions is 0, so filtering on `rate > 0` dropped every post that genuinely got no engagement — 66% of measurable rows in production — and reported a mean over only the posts that performed. It is now averaged over every row with `impressions > 0`, which is exactly when the stored rate is meaningful. Expect this number to go DOWN, and to be correct.
+- **`engagementRate` on `GET /api/analytics/account` is now `null`, never `0`.** No platform handler computes an account-level engagement rate — the internal `getAccountAnalytics` contract has no such field — so the column was its default 0 on every row and was indistinguishable from a measured 0%. Both SDKs already typed it as nullable, so this is not a breaking change. For a real rate use `platformMetrics[].engagementRate` from the engagement endpoint.
+
+### Documented
+
+- **`platformMetrics[].engagementRate` vs the post-level `engagementRate`** on the engagement response are different numbers: the post-level value is the mean over the post's channels that were measurable, the per-channel value is that one channel's own rate. Rendering the post-level average beside a single channel's counters shows one network's percentage next to another network's zeros.
+- **`profileViews` is Facebook-only** (`page_views_total`) and **`websiteClicks` is Google-Business-only**. A 0 on any other platform means "not reported", not "measured zero".
+
 ## 2026-07-29 — RFC 9207 issuer validation on the MCP OAuth server (MCP 1.11.0)
 
 ### Added

node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bulkpublish",
-  "version": "1.7.1",
+  "version": "1.7.2",
   "description": "Social media automation API for AI agents, LLMs, and developers. Publish to 11 platforms programmatically.",
   "author": "BulkPublish",
   "license": "MIT",

node/src/types.ts

@@ -819,8 +819,16 @@ export interface AccountMetricsDataPoint {
   following: number | null;
   impressions: number | null;
   reach: number | null;
+  /** Facebook only (`page_views_total`); null/0 elsewhere — not measured. */
   profileViews: number | null;
+  /** Google Business only; null/0 elsewhere — not measured. */
   websiteClicks: number | null;
+  /**
+   * ALWAYS null. No platform handler computes an account-level engagement rate,
+   * so the server returns null rather than a 0 that would look like a measured
+   * 0%. For a real rate use `platformMetrics[].engagementRate` from
+   * `analytics.engagement()`.
+   */
   engagementRate: number | null;
 }
 

openapi.json

@@ -3436,7 +3436,7 @@
         ],
         "responses": {
           "200": {
-            "description": "Account metrics with channel list",
+            "description": "Account metrics with channel list.\n\n`engagementRate` on each row is ALWAYS `null`: no platform handler computes an account-level engagement rate (the `getAccountAnalytics` contract has no such field), so the stored column is its default 0 for every row. It is returned as null rather than 0 so it cannot be mistaken for a measured 0%. For a real rate, use the per-post `engagementRate` inside `platformMetrics[]` on `GET /api/analytics/engagement`.\n\n`websiteClicks` is populated by Google Business only; `profileViews` by Facebook only (`page_views_total`). Both are 0 for every other platform because no other handler reports them — not because the value was measured as zero.",
             "content": {
               "application/json": {
                 "schema": {

python/bulkpublish/__init__.py

@@ -9,7 +9,7 @@
     ValidationError,
 )
 
-__version__ = "0.8.1"
+__version__ = "0.8.2"
 __all__ = [
     "BulkPublish",
     "AsyncBulkPublish",

python/bulkpublish/types.py

@@ -313,7 +313,10 @@ class AccountMetrics(TypedDict, total=False):
     followers: int
     following: int
     totalPosts: int
-    engagementRate: float
+    #: Always ``None`` — no platform handler computes an account-level rate, so
+    #: the server returns null rather than a 0 that would look measured. Use the
+    #: per-post ``engagementRate`` from ``analytics.engagement()`` instead.
+    engagementRate: Optional[float]
 
 
 # ---------------------------------------------------------------------------

python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bulkpublish"
-version = "0.8.1"
+version = "0.8.2"
 description = "Social media automation API for AI agents, LLMs, and developers. Publish to 11 platforms programmatically."
 readme = "README.md"
 license = "MIT"