ad2app-lib 1.15.0 → 1.20.0

package/dist/types/scheduling/I_SchedulingInbox.js

@@ -6,7 +6,7 @@
  * the connected social accounts.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SchedulingReplyToCommentDTO = exports.SchedulingSendMessageDTO = exports.SchedulingInboxCommentDTO = exports.SchedulingInboxPostWithCommentsDTO = exports.SchedulingInboxConversationDTO = void 0;
+exports.SchedulingCrossPostCommentDTO = exports.SchedulingInboxCapabilityDTO = exports.SchedulingCreateConversationDTO = exports.SchedulingCommentModerationDTO = exports.SchedulingReplyToReviewDTO = exports.SchedulingInboxReviewDTO = exports.SchedulingReplyToMentionDTO = exports.SchedulingInboxMentionDTO = exports.SchedulingConversationReadDTO = exports.SchedulingInboxMessagePageDTO = exports.SchedulingInboxMessageDTO = exports.SchedulingReplyToCommentDTO = exports.SchedulingSendMessageDTO = exports.SchedulingInboxCommentDTO = exports.SchedulingInboxPostWithCommentsDTO = exports.SchedulingInboxConversationDTO = void 0;
 // ── SchedulingInboxConversationDTO ────────────────────────────────────────────
 /**
  * A DM conversation (thread) entry.
@@ -60,6 +60,7 @@ class SchedulingInboxCommentDTO {
         this.isOwner = data.isOwner;
         this.parentId = data.parentId;
         this.replies = data.replies;
+        this.canModerate = data.canModerate;
     }
 }
 exports.SchedulingInboxCommentDTO = SchedulingInboxCommentDTO;
@@ -84,3 +85,187 @@ class SchedulingReplyToCommentDTO {
     }
 }
 exports.SchedulingReplyToCommentDTO = SchedulingReplyToCommentDTO;
+// ── 082 Inbox Parity — new inbox surfaces (US1) ───────────────────────────────
+//
+// Shapes below mirror the Zernio OpenAPI v1.0.4 inbox surface (line anchors in
+// each comment); ad2app must NOT invent fields (AD2-1038). Availability is
+// honest-or-absent: an optional field is absent when Zernio does not report it,
+// never zero/false-backfilled.
+// ── SchedulingInboxMessageDTO / SchedulingInboxMessagePageDTO ──────────────────
+/**
+ * One message inside a DM thread.
+ * Returned (paginated) by GET /social/inbox/messages/:id/thread — backed by
+ * Zernio GET /v1/inbox/conversations/{id}/messages (OpenAPI v1.0.4:20845).
+ */
+class SchedulingInboxMessageDTO {
+    constructor(data) {
+        this.id = data.id;
+        this.conversationId = data.conversationId;
+        this.authorId = data.authorId;
+        this.authorName = data.authorName;
+        this.text = data.text;
+        this.createdAt = data.createdAt;
+        this.isOwn = data.isOwn;
+        this.mediaUrl = data.mediaUrl;
+    }
+}
+exports.SchedulingInboxMessageDTO = SchedulingInboxMessageDTO;
+/**
+ * A cursor page of thread messages — kills the prior 100-message truncation.
+ * `nextCursor` absent = last page.
+ */
+class SchedulingInboxMessagePageDTO {
+    constructor(data) {
+        this.items = data.items;
+        this.nextCursor = data.nextCursor;
+    }
+}
+exports.SchedulingInboxMessagePageDTO = SchedulingInboxMessagePageDTO;
+// ── SchedulingConversationReadDTO ─────────────────────────────────────────────
+/**
+ * Mark-read acknowledgement — POST /social/inbox/messages/:id/read → Zernio
+ * POST /v1/inbox/conversations/{id}/read (OpenAPI v1.0.4:21692). `unreadCount`
+ * absent unless Zernio reports the post-read count.
+ */
+class SchedulingConversationReadDTO {
+    constructor(data) {
+        this.conversationId = data.conversationId;
+        this.unreadCount = data.unreadCount;
+    }
+}
+exports.SchedulingConversationReadDTO = SchedulingConversationReadDTO;
+// ── SchedulingInboxMentionDTO / SchedulingReplyToMentionDTO ────────────────────
+/**
+ * An inbound mention.
+ * Returned by GET /social/inbox/mentions → Zernio GET /v1/inbox/mentions
+ * (OpenAPI v1.0.4:23108). Source post fields absent when the platform omits them.
+ */
+class SchedulingInboxMentionDTO {
+    constructor(data) {
+        this.id = data.id;
+        this.platform = data.platform;
+        this.accountId = data.accountId;
+        this.authorName = data.authorName;
+        this.authorAvatarUrl = data.authorAvatarUrl;
+        this.text = data.text;
+        this.createdAt = data.createdAt;
+        this.sourcePostId = data.sourcePostId;
+        this.sourcePostUrl = data.sourcePostUrl;
+    }
+}
+exports.SchedulingInboxMentionDTO = SchedulingInboxMentionDTO;
+/**
+ * Input for replying to a mention. Zernio requires [accountId, mediaId, message]
+ * (OpenAPI v1.0.4:23207) — `mediaId` (the mention's target media) is mandatory,
+ * unlike a DM reply.
+ */
+class SchedulingReplyToMentionDTO {
+    constructor(data) {
+        this.accountId = data.accountId;
+        this.mediaId = data.mediaId;
+        this.message = data.message;
+    }
+}
+exports.SchedulingReplyToMentionDTO = SchedulingReplyToMentionDTO;
+// ── SchedulingInboxReviewDTO / SchedulingReplyToReviewDTO ──────────────────────
+/**
+ * A platform review (e.g. Google Business).
+ * Returned by GET /social/inbox/reviews → Zernio GET /v1/inbox/reviews
+ * (OpenAPI v1.0.4:23269). `replied` absent unless Zernio reports reply state.
+ */
+class SchedulingInboxReviewDTO {
+    constructor(data) {
+        this.id = data.id;
+        this.platform = data.platform;
+        this.accountId = data.accountId;
+        this.authorName = data.authorName;
+        this.rating = data.rating;
+        this.text = data.text;
+        this.createdAt = data.createdAt;
+        this.replied = data.replied;
+    }
+}
+exports.SchedulingInboxReviewDTO = SchedulingInboxReviewDTO;
+/**
+ * Input for replying to a review — POST /social/inbox/reviews/:reviewId/reply →
+ * Zernio POST /v1/inbox/reviews/{reviewId}/reply (OpenAPI v1.0.4:23377).
+ */
+class SchedulingReplyToReviewDTO {
+    constructor(data) {
+        this.reviewId = data.reviewId;
+        this.accountId = data.accountId;
+        this.text = data.text;
+    }
+}
+exports.SchedulingReplyToReviewDTO = SchedulingReplyToReviewDTO;
+class SchedulingCommentModerationDTO {
+    constructor(data) {
+        this.moderationStatus = data.moderationStatus;
+        this.banAuthor = data.banAuthor;
+    }
+}
+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).
+ */
+class SchedulingCreateConversationDTO {
+    constructor(data) {
+        this.accountId = data.accountId;
+        this.recipientId = data.recipientId;
+        this.text = data.text;
+    }
+}
+exports.SchedulingCreateConversationDTO = SchedulingCreateConversationDTO;
+// ── SchedulingInboxCapabilityDTO ──────────────────────────────────────────────
+/**
+ * Per-connected-account inbox capability truth — which surfaces a platform
+ * actually supports. Drives honest showing/hiding (082 FR-4): a false/absent
+ * surface is HIDDEN, never rendered as a fabricated empty. Reconciled from
+ * platform-capabilities + Zernio /accounts/health.
+ */
+class SchedulingInboxCapabilityDTO {
+    constructor(data) {
+        this.platform = data.platform;
+        this.dm = data.dm;
+        this.comments = data.comments;
+        this.mentions = data.mentions;
+        this.reviews = data.reviews;
+        this.dmInit = data.dmInit;
+        this.moderation = data.moderation;
+    }
+}
+exports.SchedulingInboxCapabilityDTO = SchedulingInboxCapabilityDTO;
+// ── SchedulingCrossPostCommentDTO ─────────────────────────────────────────────
+/**
+ * A comment re-sourced from Zernio's cross-post inbox (GET /v1/inbox/comments),
+ * carrying its OWN post attribution so it surfaces even when the post is absent
+ * from our local SocialPostCache. The cache is enrichment ONLY (post snippet /
+ * thumbnail), never the source of truth (082 US3 / AD2-1110): a comment on an
+ * uncached post must still reach the moderator. Comment/engagement fields mirror
+ * SchedulingInboxCommentDTO; enrichment fields are honest-or-absent — filled from
+ * the cache when present, never zero/empty-backfilled.
+ */
+class SchedulingCrossPostCommentDTO {
+    constructor(data) {
+        this.id = data.id;
+        this.authorName = data.authorName;
+        this.authorAvatarUrl = data.authorAvatarUrl;
+        this.text = data.text;
+        this.createdAt = data.createdAt;
+        this.likeCount = data.likeCount;
+        this.replyCount = data.replyCount;
+        this.isOwner = data.isOwner;
+        this.parentId = data.parentId;
+        this.canModerate = data.canModerate;
+        this.replies = data.replies;
+        this.postId = data.postId;
+        this.platform = data.platform;
+        this.accountId = data.accountId;
+        this.postContentSnippet = data.postContentSnippet;
+        this.postThumbnailUrl = data.postThumbnailUrl;
+    }
+}
+exports.SchedulingCrossPostCommentDTO = SchedulingCrossPostCommentDTO;

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

@@ -9,9 +9,17 @@ export declare enum SchedulingPostStatus {
     SCHEDULED = "scheduled",
     PUBLISHED = "published",
     FAILED = "failed",
-    PARTIAL = "partial"
+    PARTIAL = "partial",
+    /**
+     * The publisher accepted the post (an id exists) but its outcome could not
+     * be confirmed inline — a gateway timeout, or a 409 whose live status
+     * couldn't be fetched immediately (AD2-1153). Distinct from SCHEDULED: a
+     * PUBLISHING post may already be publishing server-side and must not be
+     * treated as still-editable.
+     */
+    PUBLISHING = "publishing"
 }
-export type SchedulingPlatformStatusMap = Record<string, 'scheduled' | 'published' | 'failed'>;
+export type SchedulingPlatformStatusMap = Record<string, 'scheduled' | 'published' | 'failed' | 'unknown'>;
 export declare class SchedulingPlatformTargetDTO {
     platform: string;
     accountId: string;
@@ -86,6 +94,12 @@ export declare class SchedulingPostDTO {
     postUrls?: Record<string, string>;
     /** Per-platform error messages for platforms that failed to publish. */
     platformErrors?: Record<string, string>;
+    /**
+     * Per-platform retry-attempt counts (AD2-1154 FR-3a). A platform that has
+     * used its 3rd attempt and is still failed is terminal — the retry
+     * affordance withdraws and the last real error is shown as permanent.
+     */
+    platformRetryCounts?: Record<string, number>;
     scheduledAt?: string;
     publishedAt?: string;
     status: SchedulingPostStatus;

package/dist/types/scheduling/I_SchedulingPost.js

@@ -15,6 +15,14 @@ var SchedulingPostStatus;
     SchedulingPostStatus["PUBLISHED"] = "published";
     SchedulingPostStatus["FAILED"] = "failed";
     SchedulingPostStatus["PARTIAL"] = "partial";
+    /**
+     * The publisher accepted the post (an id exists) but its outcome could not
+     * be confirmed inline — a gateway timeout, or a 409 whose live status
+     * couldn't be fetched immediately (AD2-1153). Distinct from SCHEDULED: a
+     * PUBLISHING post may already be publishing server-side and must not be
+     * treated as still-editable.
+     */
+    SchedulingPostStatus["PUBLISHING"] = "publishing";
 })(SchedulingPostStatus || (exports.SchedulingPostStatus = SchedulingPostStatus = {}));
 // ── SchedulingPlatformTargetDTO ───────────────────────────────────────────────
 class SchedulingPlatformTargetDTO {
@@ -114,6 +122,7 @@ class SchedulingPostDTO {
         this.platformStatuses = data.platformStatuses;
         this.postUrls = data.postUrls;
         this.platformErrors = data.platformErrors;
+        this.platformRetryCounts = data.platformRetryCounts;
         this.scheduledAt = data.scheduledAt;
         this.publishedAt = data.publishedAt;
         this.status = data.status;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.15.0",
+  "version": "1.20.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -43,10 +43,11 @@
   },
   "scripts": {
     "build": "npx tsc",
-    "test": "node --import tsx --test $(find src -name '*.test.ts')"
+    "test": "node --import tsx --test $(find src -name '*.test.ts')",
+    "prepare": "npm run build"
   },
   "keywords": [],
-  "author": "Maciej Górski@ad2.app",
+  "author": "Maciej G\u00f3rski@ad2.app",
   "license": "ISC",
   "description": "Package to share types and utils across the ad2app projects",
   "dependencies": {

package/src/analytics/index.test.ts

@@ -9,7 +9,7 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 
 import { EVENTS, PERSON_PROPS } from "./index";
-import type { EventProperties, EmailEventProperties } from "./index";
+import type { EventProperties, EmailEventProperties, TriggerSource, PublishFailureReason } from "./index";
 
 const SNAKE_CASE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
 
@@ -77,13 +77,45 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   [EVENTS.SOCIAL_ACCOUNT_CONNECTED]: { platform: "instagram" },
   [EVENTS.COMPOSE_STARTED]: {},
   [EVENTS.POST_SCHEDULED]: { platforms: ["instagram"], platform_count: 1 },
-  [EVENTS.POST_PUBLISHED]: { platforms: ["instagram"], platform_count: 1, status: "success" },
+  [EVENTS.POST_PUBLISHED]: { platforms: ["instagram"], platform_count: 1, status: "success", platform: "instagram" },
+  [EVENTS.PUBLISH_FAILED]: { platform: "instagram", reason_class: "auth", post_id: "post-1", platform_count: 1 },
   [EVENTS.ANALYTICS_VIEWED]: {},
   [EVENTS.LIMIT_REACHED]: { limit: "accounts", plan: "free", cap: 1 },
   [EVENTS.UPGRADE_CLICKED]: { surface: "compose" },
   [EVENTS.CHECKOUT_STARTED]: { plan: "starter" },
   [EVENTS.SUBSCRIPTION_STARTED]: { plan: "starter" },
   [EVENTS.SUBSCRIPTION_CANCELED]: { plan: "starter" },
+  // 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.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" },
+  [EVENTS.EXIT_INTENT_CAPTURED]: { surface: "connect_wall" },
+  [EVENTS.BETA_SIGNUP_CONFIRMED]: { source: "exit_intent" },
+  [EVENTS.PAYMENT_FAILED]: { plan: "starter", attempt: 1 },
+  [EVENTS.DUNNING_RECOVERED]: { plan: "starter", attempts: 2, days_late: 3 },
+  [EVENTS.REFUND_ISSUED]: { plan: "starter", days_since_start: 10 },
+  [EVENTS.DISPUTE_OPENED]: { plan: "starter", days_since_start: 10 },
+  [EVENTS.CANCEL_INITIATED]: { plan: "starter", days_since_start: 30 },
+  [EVENTS.RETENTION_OFFER_SHOWN]: { plan: "starter", offer: "discount_20" },
+  [EVENTS.CANCEL_COMPLETED]: { plan: "starter", days_since_start: 30 },
+  // Onboarding + inbox + post-lifecycle coverage (2026-07-19)
+  [EVENTS.ONBOARDING_STARTED]: {},
+  [EVENTS.ONBOARDING_COMPLETED]: {},
+  [EVENTS.ONBOARDING_SKIPPED]: {},
+  [EVENTS.COMMENT_REPLIED]: { success: true },
+  [EVENTS.COMMENT_LIKED]: { liked: true, success: true },
+  [EVENTS.COMMENT_HIDDEN]: { hidden: true, success: true },
+  [EVENTS.COMMENT_DELETED]: { success: true },
+  [EVENTS.COMMENT_PRIVATE_REPLIED]: { success: true },
+  [EVENTS.DM_REPLIED]: { success: true },
+  [EVENTS.INBOX_MARKED_READ]: { success: true },
+  [EVENTS.POST_EDITED]: { success: true },
+  [EVENTS.POST_DELETED]: { success: true },
+  [EVENTS.POST_RESCHEDULED]: { success: true },
+  [EVENTS.ACCOUNT_DISCONNECTED]: { platform: "instagram", success: true },
+  [EVENTS.NOTIFICATION_PREFERENCES_UPDATED]: { success: true },
 };
 
 test("EVENTS values are 1:1 with EventProperties keys (no missing or typo'd event)", () => {
@@ -119,3 +151,168 @@ test("the 5 EMAIL_* events are locked and share the EmailEventProperties shape (
     }
   }
 });
+
+// ── 080 measurement baseline — wire values are FINAL once shipped ───────────────
+
+test("080 paywall / onboarding wire names are locked (rename breaks the baseline dashboards)", () => {
+  assert.equal(EVENTS.PAYWALL_SHOWN, "paywall_shown");
+  assert.equal(EVENTS.PAYWALL_DISMISSED, "paywall_dismissed");
+  assert.equal(EVENTS.ONBOARDING_STEP_COMPLETED, "onboarding_step_completed");
+});
+
+test("080 subscription-lifecycle wire names are locked (backend = source of truth)", () => {
+  assert.deepEqual(
+    [
+      EVENTS.BETA_SIGNUP_CONFIRMED,
+      EVENTS.PAYMENT_FAILED,
+      EVENTS.DUNNING_RECOVERED,
+      EVENTS.REFUND_ISSUED,
+      EVENTS.DISPUTE_OPENED,
+      EVENTS.CANCEL_INITIATED,
+      EVENTS.RETENTION_OFFER_SHOWN,
+      EVENTS.CANCEL_COMPLETED,
+    ],
+    [
+      "beta_signup_confirmed",
+      "payment_failed",
+      "dunning_recovered",
+      "refund_issued",
+      "dispute_opened",
+      "cancel_initiated",
+      "retention_offer_shown",
+      "cancel_completed",
+    ],
+  );
+});
+
+// Fidelity gate (T001): the exit_intent_* wire values are adopted VERBATIM from the
+// 065 ExitIntentModal component. Verified against
+// ad2app-frontend feature/ad2-1132-exit-intent
+// src/components/social/exit-intent/ExitIntentModal.tsx —
+//   L38  const SURFACE = 'connect_wall'
+//   L67  trackLocal('exit_intent_shown',     { surface: SURFACE })
+//   L79  trackLocal('exit_intent_dismissed', { surface: SURFACE })
+//   L99  trackLocal('exit_intent_captured',  { surface: SURFACE })
+// T003 swaps those literals to these constants; the values must not drift here.
+test("080 exit_intent_* wire values match the 065 component verbatim (fidelity gate)", () => {
+  assert.equal(EVENTS.EXIT_INTENT_SHOWN, "exit_intent_shown");
+  assert.equal(EVENTS.EXIT_INTENT_DISMISSED, "exit_intent_dismissed");
+  assert.equal(EVENTS.EXIT_INTENT_CAPTURED, "exit_intent_captured");
+  const shown: EventProperties["exit_intent_shown"] = { surface: "connect_wall" };
+  assert.equal(shown.surface, "connect_wall");
+});
+
+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).
+  const shown: EventProperties["paywall_shown"] = {
+    surface: "upgrade_modal",
+    trigger: "limit_reached",
+    hit_number: 3,
+    app_locale: "pl",
+  };
+  assert.equal(shown.hit_number, 3);
+  assert.equal(shown.app_locale, "pl");
+});
+
+test("080 trigger_source closed set attributes the revenue funnel across the three intent events", () => {
+  const sources: TriggerSource[] = [
+    "connect_wall",
+    "limit_reached",
+    "exit_intent",
+    "pricing_page",
+    "checkout_abandon_email",
+    "other",
+  ];
+  // Each intent event accepts a trigger_source from the shared closed set.
+  const upgrade: EventProperties["upgrade_clicked"] = { surface: "compose", trigger_source: "connect_wall" };
+  const checkout: EventProperties["checkout_started"] = { plan: "pro", trigger_source: "exit_intent" };
+  const started: EventProperties["subscription_started"] = { plan: "pro", trigger_source: "checkout_abandon_email" };
+  assert.ok(sources.includes(upgrade.trigger_source!));
+  assert.ok(sources.includes(checkout.trigger_source!));
+  assert.ok(sources.includes(started.trigger_source!));
+});
+
+/**
+ * AD2-999 — per-platform publish instrumentation. Locks the new publish_failed
+ * wire name, its payload shape, the reason_class value set, and the optional
+ * `platform` attribution added to post_published.
+ */
+
+test("post_published and publish_failed wire names are locked (AD2-999)", () => {
+  assert.equal(EVENTS.POST_PUBLISHED, "post_published");
+  assert.equal(EVENTS.PUBLISH_FAILED, "publish_failed");
+});
+
+test("publish_failed carries exactly platform, reason_class, post_id, platform_count (AD2-999)", () => {
+  const witness: EventProperties[typeof EVENTS.PUBLISH_FAILED] =
+    EVENT_PROPERTY_WITNESS[EVENTS.PUBLISH_FAILED];
+  assert.deepEqual(Object.keys(witness).sort(), [
+    "platform",
+    "platform_count",
+    "post_id",
+    "reason_class",
+  ]);
+  assert.equal(typeof witness.platform, "string");
+  assert.equal(typeof witness.post_id, "string");
+  assert.equal(typeof witness.platform_count, "number");
+});
+
+test("PublishFailureReason is a stable closed set of snake_case buckets (AD2-999)", () => {
+  // The union is compile-time; this pins the wire values a renamed bucket would
+  // break. Kept in sync with the exported type via the typed `reasons` array —
+  // an added/removed union member fails `tsc --noEmit`, a renamed value fails here.
+  const reasons: PublishFailureReason[] = [
+    "auth",
+    "rate_limit",
+    "media",
+    "content",
+    "network",
+    "platform",
+    "unknown",
+  ];
+  assert.equal(new Set(reasons).size, reasons.length, "duplicate reason_class");
+  for (const reason of reasons) assert.match(reason, SNAKE_CASE, `not snake_case: ${reason}`);
+});
+
+test("post_published accepts optional single-platform attribution (AD2-999)", () => {
+  const single: EventProperties[typeof EVENTS.POST_PUBLISHED] = {
+    platforms: ["instagram"],
+    platform_count: 1,
+    status: "success",
+    platform: "instagram",
+  };
+  const multi: EventProperties[typeof EVENTS.POST_PUBLISHED] = {
+    platforms: ["instagram", "tiktok"],
+    platform_count: 2,
+    status: "partial",
+  };
+  assert.equal(single.platform, "instagram");
+  assert.equal(multi.platform, undefined);
+});
+
+// AD2-1154 FR-5 — Paweł's incident: post_published fired with NO platform
+// property, so a partial publish (YT ok / TikTok fail) couldn't be sliced by
+// which platform actually failed in PostHog. These are OPTIONAL additions —
+// existing aggregate-only emitters (platforms/platform_count/status) stay
+// valid; a future consumer swap fans this event out once per platform.
+test("POST_PUBLISHED gains optional per-platform properties (AD2-1154 FR-5 lib prep)", () => {
+  const aggregateOnly: EventProperties[typeof EVENTS.POST_PUBLISHED] = {
+    platforms: ["youtube", "tiktok"],
+    platform_count: 2,
+    status: "partial",
+  };
+  assert.equal(aggregateOnly.platform, undefined);
+
+  const perPlatform: EventProperties[typeof EVENTS.POST_PUBLISHED] = {
+    platforms: ["tiktok"],
+    platform_count: 1,
+    status: "failed",
+    platform: "tiktok",
+    outcome: "failed",
+    reason_class: "media",
+  };
+  assert.equal(perPlatform.platform, "tiktok");
+  assert.equal(perPlatform.outcome, "failed");
+  assert.equal(perPlatform.reason_class, "media");
+});