ad2app-lib 1.23.0 → 1.24.0

package/dist/analytics/index.d.ts

@@ -36,6 +36,7 @@ export declare const EVENTS: {
     readonly SUBSCRIPTION_CANCELED: "subscription_canceled";
     readonly PAYWALL_SHOWN: "paywall_shown";
     readonly PAYWALL_DISMISSED: "paywall_dismissed";
+    readonly ACCESS_DENIED: "access_denied";
     readonly ONBOARDING_STEP_COMPLETED: "onboarding_step_completed";
     readonly EXIT_INTENT_SHOWN: "exit_intent_shown";
     readonly EXIT_INTENT_DISMISSED: "exit_intent_dismissed";
@@ -194,6 +195,11 @@ export interface EventProperties {
         page_views?: number;
         app_locale: AppLocale;
     };
+    [EVENTS.ACCESS_DENIED]: {
+        reason: 'beta-required' | 'subscription-required';
+        path?: string;
+        app_locale: AppLocale;
+    };
     [EVENTS.PAYWALL_DISMISSED]: {
         surface: 'upgrade_modal' | 'pricing_page';
         trigger: 'user_click' | 'limit_reached' | 'connect_wall';

package/dist/analytics/index.js

@@ -45,6 +45,13 @@ exports.EVENTS = {
     // Measurement baseline (080) — paywall / onboarding / exit-intent (frontend-owned)
     PAYWALL_SHOWN: 'paywall_shown', // any monetization surface is shown (upgrade modal / pricing page)
     PAYWALL_DISMISSED: 'paywall_dismissed', // closed without converting
+    // AD2-1284: an entitlement wall rejected an API READ, which is control flow,
+    // not an error. Distinct from PAYWALL_SHOWN because nothing was shown: the
+    // driver classified a 403 at the choke point and the redirect follows. Before
+    // this event existed the only record was a captured $exception, which put
+    // expected paywall hits into Error Tracking and made that dashboard harder to
+    // trust — it is part of why a REAL retry defect sat unnoticed in the same list.
+    ACCESS_DENIED: 'access_denied', // entitlement 403 at the API choke point (beta wall / subscription)
     ONBOARDING_STEP_COMPLETED: 'onboarding_step_completed', // one step of a multi-step flow (complete-profile)
     EXIT_INTENT_SHOWN: 'exit_intent_shown', // exit-intent capture modal armed (065, verbatim wire values)
     EXIT_INTENT_DISMISSED: 'exit_intent_dismissed',

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

@@ -10,6 +10,24 @@
  */
 export declare const ANALYTICS_SOURCES: readonly ["daily-metrics", "follower-stats", "content-decay", "top-posts"];
 export type AnalyticsSource = (typeof ANALYTICS_SOURCES)[number];
+/**
+ * The metrics whose visibility is decided by the connected platform mix rather
+ * than by the data itself.
+ *
+ * Not every metric is here. `engagements` is our own roll-up (likes + comments
+ * + shares + saves) and `followerGrowth` comes from the follower-stats surface,
+ * so neither is platform-reported and neither is gated.
+ */
+export declare const GATED_METRICS: readonly ["impressions", "reach", "likes", "comments", "shares", "saves", "clicks", "views"];
+export type GatedMetric = (typeof GATED_METRICS)[number];
+/**
+ * Which gated metrics the current platform mix can actually report.
+ *
+ * An ABSENT entry means UNKNOWN, never unavailable — the producer omits the map
+ * when it could not determine the platform mix, and a consumer must fall
+ * through to showing the figure rather than withhold on a guess.
+ */
+export type MetricAvailability = Partial<Record<GatedMetric, boolean>>;
 /**
  * Aggregated KPI figures for the selected date range.
  * Returned by GET /social/analytics.
@@ -50,6 +68,16 @@ export declare class SchedulingAnalyticsKpiDTO {
      * Absent/true = available.
      */
     reachAvailable?: boolean;
+    /**
+     * Structural availability for every gated metric, from the backend's
+     * per-platform capability map (spec 111). Supersedes the two flags above,
+     * which stay for consumers that only ever read those two.
+     *
+     * ABSENT means UNKNOWN, not unavailable: the backend omits this whole map
+     * when it could not determine the connected platform mix, and a consumer
+     * must show the figure rather than withhold on a guess.
+     */
+    metricAvailability?: MetricAvailability;
     constructor(data: SchedulingAnalyticsKpiDTO);
 }
 /**

package/dist/types/scheduling/I_SchedulingAnalytics.js

@@ -6,7 +6,7 @@
  * per-post timeline snapshots, content decay windows, and follower stats.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SchedulingFollowerStatDTO = exports.SchedulingContentDecayDTO = exports.SchedulingPostTimelineEntryDTO = exports.SchedulingBestTimeSlotDTO = exports.SchedulingAnalyticsParamsDTO = exports.SchedulingAnalyticsEntryDTO = exports.SchedulingAnalyticsKpiDTO = exports.ANALYTICS_SOURCES = void 0;
+exports.SchedulingFollowerStatDTO = exports.SchedulingContentDecayDTO = exports.SchedulingPostTimelineEntryDTO = exports.SchedulingBestTimeSlotDTO = exports.SchedulingAnalyticsParamsDTO = exports.SchedulingAnalyticsEntryDTO = exports.SchedulingAnalyticsKpiDTO = exports.GATED_METRICS = exports.ANALYTICS_SOURCES = void 0;
 // ── Analytics sources (AD2-1045) ──────────────────────────────────────────────
 /**
  * The upstream sources an analytics response aggregates. Used by
@@ -18,6 +18,25 @@ exports.ANALYTICS_SOURCES = [
     'content-decay',
     'top-posts',
 ];
+// ── Per-metric structural availability (spec 111) ─────────────────────────────
+/**
+ * The metrics whose visibility is decided by the connected platform mix rather
+ * than by the data itself.
+ *
+ * Not every metric is here. `engagements` is our own roll-up (likes + comments
+ * + shares + saves) and `followerGrowth` comes from the follower-stats surface,
+ * so neither is platform-reported and neither is gated.
+ */
+exports.GATED_METRICS = [
+    'impressions',
+    'reach',
+    'likes',
+    'comments',
+    'shares',
+    'saves',
+    'clicks',
+    'views',
+];
 // ── SchedulingAnalyticsKpiDTO ─────────────────────────────────────────────────
 /**
  * Aggregated KPI figures for the selected date range.
@@ -43,6 +62,9 @@ class SchedulingAnalyticsKpiDTO {
         if (data.reachAvailable !== undefined) {
             this.reachAvailable = data.reachAvailable;
         }
+        if (data.metricAvailability !== undefined) {
+            this.metricAvailability = data.metricAvailability;
+        }
     }
 }
 exports.SchedulingAnalyticsKpiDTO = SchedulingAnalyticsKpiDTO;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",

package/src/analytics/index.test.ts

@@ -88,6 +88,7 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   // 080 measurement baseline
   [EVENTS.PAYWALL_SHOWN]: { surface: "upgrade_modal", trigger: "user_click", hit_number: 1, app_locale: "en" },
   [EVENTS.PAYWALL_DISMISSED]: { surface: "upgrade_modal", trigger: "user_click", hit_number: 1, app_locale: "en" },
+  [EVENTS.ACCESS_DENIED]: { reason: "subscription-required", app_locale: "en" },
   [EVENTS.ONBOARDING_STEP_COMPLETED]: { flow: "complete_profile", step: "role", step_index: 1, app_locale: "en" },
   [EVENTS.EXIT_INTENT_SHOWN]: { surface: "connect_wall" },
   [EVENTS.EXIT_INTENT_DISMISSED]: { surface: "connect_wall" },
@@ -202,6 +203,28 @@ test("080 exit_intent_* wire values match the 065 component verbatim (fidelity g
   assert.equal(shown.surface, "connect_wall");
 });
 
+test("AD2-1284 access_denied is locked, and its reasons mirror the backend's two 403s", () => {
+  // The wire name is final: Error Tracking noise was traded for this event, and
+  // renaming it would orphan whatever reads it.
+  assert.equal(EVENTS.ACCESS_DENIED, "access_denied");
+
+  // Both reasons must type-check — they are the two DIFFERENT 403s the backend
+  // sends, and accessDenied.ts's AccessDenial union is the other copy of this
+  // fact. A drift between them is the defect this pins.
+  const beta: EventProperties["access_denied"] = {
+    reason: "beta-required",
+    path: "/social/inbox/messages",
+    app_locale: "pl",
+  };
+  const sub: EventProperties["access_denied"] = {
+    reason: "subscription-required",
+    app_locale: "en",
+  };
+  assert.equal(beta.reason, "beta-required");
+  assert.equal(beta.path, "/social/inbox/messages");
+  assert.equal(sub.path, undefined);
+});
+
 test("080 PAYWALL_HITS person prop is locked; hit_number stays the event-level truth", () => {
   assert.equal(PERSON_PROPS.PAYWALL_HITS, "paywall_hits");
   // The analytical counter lives on the event (person props are query-time-latest).

package/src/analytics/index.ts

@@ -48,6 +48,13 @@ export const EVENTS = {
   // Measurement baseline (080) — paywall / onboarding / exit-intent (frontend-owned)
   PAYWALL_SHOWN: 'paywall_shown', // any monetization surface is shown (upgrade modal / pricing page)
   PAYWALL_DISMISSED: 'paywall_dismissed', // closed without converting
+  // AD2-1284: an entitlement wall rejected an API READ, which is control flow,
+  // not an error. Distinct from PAYWALL_SHOWN because nothing was shown: the
+  // driver classified a 403 at the choke point and the redirect follows. Before
+  // this event existed the only record was a captured $exception, which put
+  // expected paywall hits into Error Tracking and made that dashboard harder to
+  // trust — it is part of why a REAL retry defect sat unnoticed in the same list.
+  ACCESS_DENIED: 'access_denied', // entitlement 403 at the API choke point (beta wall / subscription)
   ONBOARDING_STEP_COMPLETED: 'onboarding_step_completed', // one step of a multi-step flow (complete-profile)
   EXIT_INTENT_SHOWN: 'exit_intent_shown', // exit-intent capture modal armed (065, verbatim wire values)
   EXIT_INTENT_DISMISSED: 'exit_intent_dismissed',
@@ -241,6 +248,14 @@ export interface EventProperties {
     page_views?: number;
     app_locale: AppLocale;
   };
+  // `reason` mirrors accessDenied.ts's AccessDenial union exactly — the two
+  // different 403s the backend sends. `path` is the request path, never a URL
+  // with query params (no PII in analytics).
+  [EVENTS.ACCESS_DENIED]: {
+    reason: 'beta-required' | 'subscription-required';
+    path?: string;
+    app_locale: AppLocale;
+  };
   [EVENTS.PAYWALL_DISMISSED]: {
     surface: 'upgrade_modal' | 'pricing_page';
     trigger: 'user_click' | 'limit_reached' | 'connect_wall';

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

@@ -2,7 +2,9 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import {
   ANALYTICS_SOURCES,
+  GATED_METRICS,
   SchedulingAnalyticsKpiDTO,
+  type MetricAvailability,
 } from './I_SchedulingAnalytics';
 
 // AD2-1045 — the analytics partial-failure signal: a KPI response can name
@@ -89,3 +91,58 @@ test('impressionsAvailable/reachAvailable are optional and absent by default (ba
   assert.equal('impressionsAvailable' in serialized, false);
   assert.equal('reachAvailable' in serialized, false);
 });
+
+// Spec 111 — per-metric structural availability. The two AD2-1078 flags above
+// only ever described impressions and reach; the capability map the backend
+// now derives covers eight metrics, and it travelled as an undeclared field
+// cast onto the DTO on one side and re-widened on the other until this landed.
+
+test('SchedulingAnalyticsKpiDTO carries metricAvailability when provided', () => {
+  const kpi = new SchedulingAnalyticsKpiDTO({
+    impressions: 10,
+    reach: 5,
+    engagements: 4,
+    views: 20,
+    engagementRate: 1.2,
+    followerGrowth: 3,
+    metricAvailability: { reach: false, saves: true, clicks: false },
+  });
+  assert.equal(kpi.metricAvailability?.reach, false);
+  assert.equal(kpi.metricAvailability?.saves, true);
+  assert.equal(kpi.metricAvailability?.clicks, false);
+  assert.deepEqual(
+    JSON.parse(JSON.stringify(kpi)).metricAvailability,
+    { reach: false, saves: true, clicks: false },
+  );
+});
+
+test('metricAvailability is optional and absent by default — absent means UNKNOWN', () => {
+  const kpi = new SchedulingAnalyticsKpiDTO({
+    impressions: 10,
+    reach: 5,
+    engagements: 4,
+    views: 20,
+    engagementRate: 1.2,
+    followerGrowth: 3,
+  });
+  assert.equal(kpi.metricAvailability, undefined);
+  assert.equal('metricAvailability' in JSON.parse(JSON.stringify(kpi)), false);
+});
+
+test('GATED_METRICS names every metric the capability map gates, and nothing else', () => {
+  // engagements is our own roll-up and followerGrowth is a different surface —
+  // neither is platform-reported, so neither may appear here.
+  assert.deepEqual([...GATED_METRICS], [
+    'impressions',
+    'reach',
+    'likes',
+    'comments',
+    'shares',
+    'saves',
+    'clicks',
+    'views',
+  ]);
+  const availability: MetricAvailability = {};
+  for (const metric of GATED_METRICS) availability[metric] = true;
+  assert.equal(Object.keys(availability).length, 8);
+});

package/src/types/scheduling/I_SchedulingAnalytics.ts

@@ -20,6 +20,38 @@ export const ANALYTICS_SOURCES = [
 
 export type AnalyticsSource = (typeof ANALYTICS_SOURCES)[number];
 
+// ── Per-metric structural availability (spec 111) ─────────────────────────────
+
+/**
+ * The metrics whose visibility is decided by the connected platform mix rather
+ * than by the data itself.
+ *
+ * Not every metric is here. `engagements` is our own roll-up (likes + comments
+ * + shares + saves) and `followerGrowth` comes from the follower-stats surface,
+ * so neither is platform-reported and neither is gated.
+ */
+export const GATED_METRICS = [
+  'impressions',
+  'reach',
+  'likes',
+  'comments',
+  'shares',
+  'saves',
+  'clicks',
+  'views',
+] as const;
+
+export type GatedMetric = (typeof GATED_METRICS)[number];
+
+/**
+ * Which gated metrics the current platform mix can actually report.
+ *
+ * An ABSENT entry means UNKNOWN, never unavailable — the producer omits the map
+ * when it could not determine the platform mix, and a consumer must fall
+ * through to showing the figure rather than withhold on a guess.
+ */
+export type MetricAvailability = Partial<Record<GatedMetric, boolean>>;
+
 // ── SchedulingAnalyticsKpiDTO ─────────────────────────────────────────────────
 
 /**
@@ -62,6 +94,16 @@ export class SchedulingAnalyticsKpiDTO {
    * Absent/true = available.
    */
   reachAvailable?: boolean;
+  /**
+   * Structural availability for every gated metric, from the backend's
+   * per-platform capability map (spec 111). Supersedes the two flags above,
+   * which stay for consumers that only ever read those two.
+   *
+   * ABSENT means UNKNOWN, not unavailable: the backend omits this whole map
+   * when it could not determine the connected platform mix, and a consumer
+   * must show the figure rather than withhold on a guess.
+   */
+  metricAvailability?: MetricAvailability;
 
   constructor(data: SchedulingAnalyticsKpiDTO) {
     this.impressions = data.impressions;
@@ -82,6 +124,9 @@ export class SchedulingAnalyticsKpiDTO {
     if (data.reachAvailable !== undefined) {
       this.reachAvailable = data.reachAvailable;
     }
+    if (data.metricAvailability !== undefined) {
+      this.metricAvailability = data.metricAvailability;
+    }
   }
 }