ad2app-lib 1.17.0 → 1.20.0

package/src/analytics/index.ts

@@ -35,6 +35,7 @@ export const EVENTS = {
   COMPOSE_STARTED: 'compose_started',
   POST_SCHEDULED: 'post_scheduled',
   POST_PUBLISHED: 'post_published', // server-confirmed (backend)
+  PUBLISH_FAILED: 'publish_failed', // per-platform publish failure, server-owned (backend, AD2-999)
   ANALYTICS_VIEWED: 'analytics_viewed',
 
   // Revenue (backend = source of truth). Paid-only product: no trial.
@@ -43,6 +44,48 @@ export const EVENTS = {
   CHECKOUT_STARTED: 'checkout_started',
   SUBSCRIPTION_STARTED: 'subscription_started',
   SUBSCRIPTION_CANCELED: 'subscription_canceled',
+
+  // 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
+  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',
+  EXIT_INTENT_CAPTURED: 'exit_intent_captured', // email captured into the beta list
+
+  // Measurement baseline (080) — subscription lifecycle (backend = source of truth)
+  BETA_SIGNUP_CONFIRMED: 'beta_signup_confirmed', // double-opt-in confirm click
+  PAYMENT_FAILED: 'payment_failed', // invoice.payment_failed (excl. unexecuted hard-decline retries)
+  DUNNING_RECOVERED: 'dunning_recovered', // open→paid after ≥1 failure on the same invoice
+  REFUND_ISSUED: 'refund_issued',
+  DISPUTE_OPENED: 'dispute_opened',
+  CANCEL_INITIATED: 'cancel_initiated', // start of the cancel funnel
+  RETENTION_OFFER_SHOWN: 'retention_offer_shown', // emitted ONLY when an offer is actually shown — no fabrication
+  CANCEL_COMPLETED: 'cancel_completed',
+
+  // Onboarding flow (promoted from the frontend-local onboardingEvents.ts into the
+  // governed taxonomy, 2026-07-19 — ONBOARDING_STEP_COMPLETED is defined above).
+  ONBOARDING_STARTED: 'onboarding_started',
+  ONBOARDING_COMPLETED: 'onboarding_completed',
+  ONBOARDING_SKIPPED: 'onboarding_skipped',
+
+  // Inbox engagement (tracking-coverage gap: the inbox surface had ZERO events).
+  COMMENT_REPLIED: 'comment_replied',
+  COMMENT_LIKED: 'comment_liked',
+  COMMENT_HIDDEN: 'comment_hidden',
+  COMMENT_DELETED: 'comment_deleted',
+  COMMENT_PRIVATE_REPLIED: 'comment_private_replied',
+  DM_REPLIED: 'dm_replied',
+  INBOX_MARKED_READ: 'inbox_marked_read', // sanctioned; wired when 082 mark-read lands
+
+  // Post lifecycle + account (tracking-coverage gap).
+  POST_EDITED: 'post_edited',
+  POST_DELETED: 'post_deleted',
+  POST_RESCHEDULED: 'post_rescheduled',
+  ACCOUNT_DISCONNECTED: 'account_disconnected',
+
+  // Settings.
+  NOTIFICATION_PREFERENCES_UPDATED: 'notification_preferences_updated',
 } as const;
 
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
@@ -54,6 +97,46 @@ export interface EmailEventProperties {
   link?: string;
 }
 
+/**
+ * Where a paywall / upgrade / checkout moment was triggered from (080). A named,
+ * stable, closed set so the revenue funnel can attribute conversions to their
+ * origin surface. `checkout_abandon_email` is the recovery-email re-entry point
+ * (Superwall transaction-abandonment pattern). Wire values — do not rename.
+ */
+export type TriggerSource =
+  | 'connect_wall'
+  | 'limit_reached'
+  | 'exit_intent'
+  | 'pricing_page'
+  | 'checkout_abandon_email'
+  | 'other';
+
+/**
+ * The USER-CHOSEN i18n locale (080) — NOT `$browser_language`. Localization is
+ * the top structural conversion lever in the corpus (Adapty), so every wall /
+ * paywall insight slices by it. Stamped on the surfaces the emitter controls.
+ */
+export type AppLocale = 'en' | 'pl';
+
+/**
+ * Coarse failure-reason buckets for the `publish_failed` event (AD2-999).
+ *
+ * Deliberately a small, stable, closed set: it lets publish outcomes be sliced
+ * per failure class in PostHog WITHOUT putting raw provider (Zernio/platform)
+ * error text — which can carry user content or PII — on the event. The emitter
+ * (backend) maps a raw provider error string to exactly one of these; an
+ * absent/unclassifiable error is `'unknown'`. Do NOT rename these values after
+ * they ship — they are wire values, historical data does not migrate.
+ */
+export type PublishFailureReason =
+  | 'auth' // token expired / revoked / missing scope / permission denied
+  | 'rate_limit' // provider throttled us (429 / quota)
+  | 'media' // media rejected (format, size, duration, resolution)
+  | 'content' // caption/content rejected, duplicate, or policy violation
+  | 'network' // timeout / gateway / transport failure reaching the provider
+  | 'platform' // provider-side error (5xx / internal / unexpected)
+  | 'unknown'; // no error detail or unclassifiable
+
 /** Property shape per event. Keeps emitters honest across repos. */
 export interface EventProperties {
   [EVENTS.LANDING_CTA_CLICKED]: {
@@ -82,17 +165,47 @@ export interface EventProperties {
   [EVENTS.SOCIAL_ACCOUNT_CONNECTED]: {
     platform: string;
     account_count?: number;
+    // 080: 1 = first-ever account, 2 = second… — the "second action" activation hook.
+    connection_ordinal?: number;
   };
   [EVENTS.COMPOSE_STARTED]: { source?: 'wizard' | 'quick' };
   [EVENTS.POST_SCHEDULED]: {
     platforms: string[];
     platform_count: number;
     scheduled_for?: string;
+    // 080: nth scheduled post for this user (server-derived where owner=backend).
+    post_ordinal?: number;
   };
   [EVENTS.POST_PUBLISHED]: {
     platforms: string[];
     platform_count: number;
     status: 'success' | 'partial' | 'failed';
+    // 080: nth published post for this user (server-derived where owner=backend).
+    post_ordinal?: number;
+    // Single-platform attribution (AD2-999): set to the sole target platform
+    // when platform_count === 1, so a per-platform outcome is directly
+    // sliceable. Omitted for multi-platform posts, where the aggregate `status`
+    // plus the per-platform `publish_failed` events carry the breakdown.
+    // (AD2-1154 FR-5 also relies on this: Paweł's incident showed post_published
+    // firing with NO platform property, so a partial publish couldn't be sliced.)
+    platform?: string;
+    // The publish path that confirmed the outcome. Only the scheduled/reconcile
+    // path stamps this today; the immediate-publish path omits it (AD2-999).
+    source?: 'scheduled_reconcile';
+    // Optional per-platform outcome breakdown for a future consumer swap that
+    // fans post_published out once per platform (AD2-1154 FR-5; lib prep now,
+    // emission-site change stays a separate story per doctrine).
+    outcome?: 'success' | 'failed' | 'unknown';
+    reason_class?: PublishFailureReason;
+  };
+  // Per-platform publish failure (AD2-999). Emitted once per failed platform on
+  // a failed or partial publish (immediate path and scheduled reconcile), so a
+  // wholesale failure surfaces as explicit events, never a silent absence.
+  [EVENTS.PUBLISH_FAILED]: {
+    platform: string;
+    reason_class: PublishFailureReason;
+    post_id: string;
+    platform_count: number;
   };
   [EVENTS.ANALYTICS_VIEWED]: { scope?: 'overview' | 'account' | 'post' };
   [EVENTS.LIMIT_REACHED]: {
@@ -104,14 +217,83 @@ export interface EventProperties {
     from_plan?: string;
     to_plan?: string;
     surface: string;
+    trigger_source?: TriggerSource; // 080: revenue-funnel origin attribution
   };
-  [EVENTS.CHECKOUT_STARTED]: { plan: string };
+  [EVENTS.CHECKOUT_STARTED]: { plan: string; trigger_source?: TriggerSource };
   [EVENTS.SUBSCRIPTION_STARTED]: {
     plan: string;
     mrr?: number;
     accounts_included?: number;
+    trigger_source?: TriggerSource; // 080
   };
   [EVENTS.SUBSCRIPTION_CANCELED]: { plan: string; reason?: string };
+
+  // ── Measurement baseline (080) — new event property shapes ──────────────────
+  // Paywall surfaces (frontend). hit_number is the analytical truth (an event
+  // property, NOT a person prop, since person props return latest-value for
+  // historical events). app_locale is the user-chosen i18n locale, required here.
+  [EVENTS.PAYWALL_SHOWN]: {
+    surface: 'upgrade_modal' | 'pricing_page';
+    trigger: 'user_click' | 'limit_reached' | 'connect_wall';
+    plan?: string;
+    hit_number: number;
+    dwell_ms?: number;
+    page_views?: number;
+    app_locale: AppLocale;
+  };
+  [EVENTS.PAYWALL_DISMISSED]: {
+    surface: 'upgrade_modal' | 'pricing_page';
+    trigger: 'user_click' | 'limit_reached' | 'connect_wall';
+    hit_number: number;
+    app_locale: AppLocale;
+  };
+  [EVENTS.ONBOARDING_STEP_COMPLETED]: {
+    flow: 'complete_profile'; // closed set, extensible when a new flow ships
+    step: string; // stable slug derived from the real wizard, not guessed
+    step_index: number; // 1-based
+    app_locale: AppLocale;
+  };
+  // Exit-intent (065). surface value is VERBATIM from the ExitIntentModal
+  // component ('connect_wall'); dwell_ms / page_views / app_locale are optional
+  // additions T003 wires (the component does not emit them yet — fidelity gate).
+  [EVENTS.EXIT_INTENT_SHOWN]: { surface: 'connect_wall'; dwell_ms?: number; page_views?: number; app_locale?: AppLocale };
+  [EVENTS.EXIT_INTENT_DISMISSED]: { surface: 'connect_wall'; dwell_ms?: number; page_views?: number; app_locale?: AppLocale };
+  [EVENTS.EXIT_INTENT_CAPTURED]: { surface: 'connect_wall'; dwell_ms?: number; page_views?: number; app_locale?: AppLocale };
+  // Subscription lifecycle (backend). days_since_start / attempts / days_late are
+  // server-derived; retention_offer_shown emits ONLY when an offer is really shown.
+  [EVENTS.BETA_SIGNUP_CONFIRMED]: { source: 'exit_intent' | 'free_skills' };
+  [EVENTS.PAYMENT_FAILED]: { plan: string; attempt: number };
+  [EVENTS.DUNNING_RECOVERED]: { plan: string; attempts: number; days_late: number };
+  [EVENTS.REFUND_ISSUED]: { plan: string; days_since_start: number };
+  [EVENTS.DISPUTE_OPENED]: { plan: string; days_since_start: number };
+  [EVENTS.CANCEL_INITIATED]: { plan: string; days_since_start: number };
+  [EVENTS.RETENTION_OFFER_SHOWN]: { plan: string; offer: string };
+  [EVENTS.CANCEL_COMPLETED]: { plan: string; days_since_start: number; reason?: string };
+
+  // Onboarding flow (promoted 2026-07-19). flow defaults to the main app onboarding.
+  [EVENTS.ONBOARDING_STARTED]: { flow?: string };
+  [EVENTS.ONBOARDING_COMPLETED]: { flow?: string; steps_completed?: number };
+  [EVENTS.ONBOARDING_SKIPPED]: { flow?: string; step?: string };
+
+  // Inbox engagement — platform is the social platform the comment/DM is on.
+  // `success` is emitted on BOTH the success and failure path so a broken action
+  // is visible (slice by success=false), not a silent absence.
+  [EVENTS.COMMENT_REPLIED]: { platform?: string; success: boolean };
+  [EVENTS.COMMENT_LIKED]: { platform?: string; liked: boolean; success: boolean };
+  [EVENTS.COMMENT_HIDDEN]: { platform?: string; hidden: boolean; success: boolean };
+  [EVENTS.COMMENT_DELETED]: { platform?: string; success: boolean };
+  [EVENTS.COMMENT_PRIVATE_REPLIED]: { platform?: string; success: boolean };
+  [EVENTS.DM_REPLIED]: { platform?: string; success: boolean };
+  [EVENTS.INBOX_MARKED_READ]: { platform?: string; success: boolean };
+
+  // Post lifecycle + account.
+  [EVENTS.POST_EDITED]: { platforms?: string[]; platform_count?: number; success: boolean };
+  [EVENTS.POST_DELETED]: { platform_count?: number; success: boolean };
+  [EVENTS.POST_RESCHEDULED]: { platform_count?: number; success: boolean };
+  [EVENTS.ACCOUNT_DISCONNECTED]: { platform: string; success: boolean };
+
+  // Settings — which preference toggled and its new state.
+  [EVENTS.NOTIFICATION_PREFERENCES_UPDATED]: { preference?: string; enabled?: boolean; success: boolean };
 }
 
 /** Canonical person property keys (set via identify / $set). */
@@ -120,6 +302,10 @@ export const PERSON_PROPS = {
   ROLE: 'role',
   PLAN: 'plan', // 'free' | 'starter' | 'pro' (SchedulingSubscriptionTier)
   ACCOUNT_COUNT: 'account_count',
+  // 080: convenience $set mirror of paywall exposure. The event-level `hit_number`
+  // is the analytical truth — person props are query-time-latest here, so a counter
+  // stored here would rewrite the value on every historical paywall_shown event.
+  PAYWALL_HITS: 'paywall_hits',
 } as const;
 
 export type PersonPropKey = (typeof PERSON_PROPS)[keyof typeof PERSON_PROPS];

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

@@ -1,6 +1,19 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { SchedulingInboxCommentDTO } from './I_SchedulingInbox';
+import {
+  SchedulingInboxCommentDTO,
+  SchedulingInboxMentionDTO,
+  SchedulingReplyToMentionDTO,
+  SchedulingInboxReviewDTO,
+  SchedulingReplyToReviewDTO,
+  SchedulingInboxMessageDTO,
+  SchedulingInboxMessagePageDTO,
+  SchedulingCommentModerationDTO,
+  SchedulingInboxCapabilityDTO,
+  SchedulingCreateConversationDTO,
+  SchedulingConversationReadDTO,
+  SchedulingCrossPostCommentDTO,
+} from './I_SchedulingInbox';
 
 // AD2-1088 — engagement + ownership pass-through on inbox comments, verbatim
 // from Zernio GET /v1/inbox/comments/{postId} (OpenAPI v1.0.4:20799). Set
@@ -53,3 +66,207 @@ test('SchedulingInboxCommentDTO nests replies with the same optional fields', ()
   });
   assert.equal(comment.replies?.[0].parentId, 'c1');
 });
+
+// ── 082 Inbox Parity — new inbox surfaces (US1) ───────────────────────────────
+
+// canModerate is YouTube-only (OpenAPI v1.0.4:22489); absent for everything else,
+// never fabricated to false-as-if-known.
+test('SchedulingInboxCommentDTO.canModerate is absent by default and pass-through when set', () => {
+  const plain = new SchedulingInboxCommentDTO({
+    id: 'c1',
+    authorName: 'Jane',
+    text: 'hi',
+    createdAt: '2026-07-19T00:00:00.000Z',
+  });
+  assert.equal(plain.canModerate, undefined);
+  const yt = new SchedulingInboxCommentDTO({
+    id: 'c2',
+    authorName: 'Jane',
+    text: 'hi',
+    createdAt: '2026-07-19T00:00:00.000Z',
+    canModerate: true,
+  });
+  assert.equal(yt.canModerate, true);
+});
+
+// Mentions — GET /v1/inbox/mentions (23108); reply body [accountId, mediaId, message] (23207).
+test('SchedulingInboxMentionDTO keeps source fields optional (honest-or-absent)', () => {
+  const bare = new SchedulingInboxMentionDTO({
+    id: 'm1',
+    platform: 'instagram',
+    accountId: 'a1',
+    authorName: 'fan',
+    text: '@me great post',
+    createdAt: '2026-07-19T00:00:00.000Z',
+  });
+  assert.equal(bare.sourcePostId, undefined);
+  assert.equal(bare.sourcePostUrl, undefined);
+  const full = new SchedulingInboxMentionDTO({
+    id: 'm2',
+    platform: 'instagram',
+    accountId: 'a1',
+    authorName: 'fan',
+    text: '@me nice',
+    createdAt: '2026-07-19T00:00:00.000Z',
+    sourcePostId: 'p9',
+    sourcePostUrl: 'https://example/p9',
+  });
+  assert.equal(full.sourcePostId, 'p9');
+  assert.equal(full.sourcePostUrl, 'https://example/p9');
+});
+
+test('SchedulingReplyToMentionDTO requires accountId, mediaId and message', () => {
+  const dto = new SchedulingReplyToMentionDTO({
+    accountId: 'a1',
+    mediaId: 'md1',
+    message: 'thanks!',
+  });
+  assert.equal(dto.accountId, 'a1');
+  assert.equal(dto.mediaId, 'md1');
+  assert.equal(dto.message, 'thanks!');
+});
+
+// Reviews — GET /v1/inbox/reviews (23269); reply POST /v1/inbox/reviews/{reviewId}/reply (23377).
+test('SchedulingInboxReviewDTO carries rating + optional replied flag', () => {
+  const r = new SchedulingInboxReviewDTO({
+    id: 'rv1',
+    platform: 'googlebusiness',
+    accountId: 'a1',
+    authorName: 'Customer',
+    rating: 5,
+    text: 'great',
+    createdAt: '2026-07-19T00:00:00.000Z',
+  });
+  assert.equal(r.rating, 5);
+  assert.equal(r.replied, undefined);
+  const replied = new SchedulingInboxReviewDTO({
+    id: 'rv2',
+    platform: 'googlebusiness',
+    accountId: 'a1',
+    authorName: 'Customer',
+    rating: 4,
+    text: 'good',
+    createdAt: '2026-07-19T00:00:00.000Z',
+    replied: true,
+  });
+  assert.equal(replied.replied, true);
+});
+
+test('SchedulingReplyToReviewDTO carries reviewId, accountId, text', () => {
+  const dto = new SchedulingReplyToReviewDTO({
+    reviewId: 'rv1',
+    accountId: 'a1',
+    text: 'thank you',
+  });
+  assert.equal(dto.reviewId, 'rv1');
+  assert.equal(dto.accountId, 'a1');
+  assert.equal(dto.text, 'thank you');
+});
+
+// Cursor pagination — kills the 100-message thread truncation.
+test('SchedulingInboxMessageDTO + page keep nextCursor optional', () => {
+  const msg = new SchedulingInboxMessageDTO({
+    id: 'msg1',
+    conversationId: 'conv1',
+    authorId: 'u1',
+    authorName: 'fan',
+    text: 'hi',
+    createdAt: '2026-07-19T00:00:00.000Z',
+    isOwn: false,
+  });
+  const lastPage = new SchedulingInboxMessagePageDTO({ items: [msg] });
+  assert.equal(lastPage.items.length, 1);
+  assert.equal(lastPage.nextCursor, undefined);
+  const midPage = new SchedulingInboxMessagePageDTO({ items: [msg], nextCursor: 'cur2' });
+  assert.equal(midPage.nextCursor, 'cur2');
+});
+
+// Moderation — closed set [published, rejected, heldForReview]; banAuthor only with rejected (22489).
+test('SchedulingCommentModerationDTO carries a closed-set status and optional banAuthor', () => {
+  const approve = new SchedulingCommentModerationDTO({ moderationStatus: 'published' });
+  assert.equal(approve.moderationStatus, 'published');
+  assert.equal(approve.banAuthor, undefined);
+  const reject = new SchedulingCommentModerationDTO({ moderationStatus: 'rejected', banAuthor: true });
+  assert.equal(reject.moderationStatus, 'rejected');
+  assert.equal(reject.banAuthor, true);
+});
+
+// Per-platform capability — drives honest show/hide (FR-4); absent/false = surface hidden.
+test('SchedulingInboxCapabilityDTO exposes per-surface booleans', () => {
+  const cap = new SchedulingInboxCapabilityDTO({
+    platform: 'youtube',
+    dm: false,
+    comments: true,
+    mentions: false,
+    reviews: false,
+    dmInit: false,
+    moderation: true,
+  });
+  assert.equal(cap.comments, true);
+  assert.equal(cap.moderation, true);
+  assert.equal(cap.dm, false);
+});
+
+test('SchedulingCreateConversationDTO carries account, recipient, text', () => {
+  const dto = new SchedulingCreateConversationDTO({
+    accountId: 'a1',
+    recipientId: 'r1',
+    text: 'hello',
+  });
+  assert.equal(dto.accountId, 'a1');
+  assert.equal(dto.recipientId, 'r1');
+  assert.equal(dto.text, 'hello');
+});
+
+// Mark-read acknowledgement — unreadCount absent unless Zernio reports it.
+test('SchedulingConversationReadDTO keeps unreadCount optional', () => {
+  const ack = new SchedulingConversationReadDTO({ conversationId: 'conv1' });
+  assert.equal(ack.conversationId, 'conv1');
+  assert.equal(ack.unreadCount, undefined);
+  const ackWithCount = new SchedulingConversationReadDTO({ conversationId: 'conv1', unreadCount: 0 });
+  assert.equal(ackWithCount.unreadCount, 0);
+});
+
+// 082 US3 (T301 / AD2-1110): comments re-sourced from Zernio cross-post carry their OWN post
+// attribution so an uncached post still surfaces its comments; the cache is enrichment only.
+test('SchedulingCrossPostCommentDTO carries post attribution; enrichment + engagement absent by default', () => {
+  const c = new SchedulingCrossPostCommentDTO({
+    id: 'x1', authorName: 'Jane', text: 'nice', createdAt: '2026-07-19T00:00:00.000Z',
+    postId: 'p1', platform: 'instagram', accountId: 'acc1',
+  });
+  assert.equal(c.postId, 'p1');
+  assert.equal(c.platform, 'instagram');
+  assert.equal(c.accountId, 'acc1');
+  assert.equal(c.postContentSnippet, undefined, 'enrichment absent, never backfilled');
+  assert.equal(c.postThumbnailUrl, undefined);
+  assert.equal(c.likeCount, undefined);
+  assert.equal(c.canModerate, undefined);
+});
+
+test('SchedulingCrossPostCommentDTO fills enrichment + engagement when provided', () => {
+  const c = new SchedulingCrossPostCommentDTO({
+    id: 'x2', authorName: 'Jane', text: 'nice', createdAt: '2026-07-19T00:00:00.000Z',
+    postId: 'p2', platform: 'youtube', accountId: 'acc2',
+    postContentSnippet: 'My launch post', postThumbnailUrl: 'https://cdn/x.jpg',
+    likeCount: 5, replyCount: 2, isOwner: false, canModerate: true,
+  });
+  assert.equal(c.postContentSnippet, 'My launch post');
+  assert.equal(c.postThumbnailUrl, 'https://cdn/x.jpg');
+  assert.equal(c.likeCount, 5);
+  assert.equal(c.replyCount, 2);
+  assert.equal(c.canModerate, true);
+});
+
+test('SchedulingCrossPostCommentDTO nests replies of its own type', () => {
+  const c = new SchedulingCrossPostCommentDTO({
+    id: 'x3', authorName: 'Jane', text: 'top', createdAt: '2026-07-19T00:00:00.000Z',
+    postId: 'p3', platform: 'instagram', accountId: 'acc3',
+    replies: [new SchedulingCrossPostCommentDTO({
+      id: 'x3r1', authorName: 'Bob', text: 'reply', createdAt: '2026-07-19T00:01:00.000Z',
+      postId: 'p3', platform: 'instagram', accountId: 'acc3', parentId: 'x3',
+    })],
+  });
+  assert.equal(c.replies?.length, 1);
+  assert.equal(c.replies?.[0].parentId, 'x3');
+  assert.equal(c.replies?.[0].postId, 'p3', 'nested reply keeps its post attribution');
+});