ad2app-lib 1.30.0 → 1.31.0

package/dist/analytics/index.d.ts

@@ -33,6 +33,8 @@ export declare const EVENTS: {
     readonly LOGGED_IN: "logged_in";
     readonly SOCIAL_ACCOUNT_CONNECTED: "social_account_connected";
     readonly COMPOSE_STARTED: "compose_started";
+    readonly COMPOSE_STEP_VIEWED: "compose_step_viewed";
+    readonly COMPOSE_BLOCKED: "compose_blocked";
     readonly POST_SCHEDULED: "post_scheduled";
     readonly POST_PUBLISHED: "post_published";
     readonly PUBLISH_FAILED: "publish_failed";
@@ -147,6 +149,19 @@ export type AppLocale = 'en' | 'pl';
  * absent/unclassifiable error is `'unknown'`. Do NOT rename these values after
  * they ship — they are wire values, historical data does not migrate.
  */
+/**
+ * Which wizard step the composer is showing. Wire values, not indexes: a step
+ * reordered or inserted would silently re-label every historical row if this
+ * carried 0-3 (AD2-1371).
+ */
+export type ComposeStep = 'platforms' | 'content' | 'details' | 'review';
+/**
+ * Why the composer refused to advance. The readiness summary renders LOCALISED
+ * PROSE that names platforms and field labels, and the caption itself is user
+ * content, so neither may ride the event: only the class does. Same contract as
+ * PublishFailureReason. Do NOT rename after shipping — wire values.
+ */
+export type ComposeBlockReason = 'empty' | 'missing_fields' | 'over_limit' | 'media' | 'channel_blocked' | 'poll';
 export type PublishFailureReason = 'auth' | 'rate_limit' | 'media' | 'content' | 'network' | 'platform' | 'unknown';
 /** Property shape per event. Keeps emitters honest across repos. */
 export interface EventProperties {
@@ -211,6 +226,16 @@ export interface EventProperties {
     [EVENTS.COMPOSE_STARTED]: {
         source?: 'wizard' | 'quick';
     };
+    [EVENTS.COMPOSE_STEP_VIEWED]: {
+        step: ComposeStep;
+    };
+    [EVENTS.COMPOSE_BLOCKED]: {
+        step: ComposeStep;
+        /** Distinct reason classes present, deduped. Never the rendered prose. */
+        reasons: ComposeBlockReason[];
+        /** How many readiness lines the user faced, which `reasons` dedupes away. */
+        reason_count: number;
+    };
     [EVENTS.POST_SCHEDULED]: {
         platforms: string[];
         platform_count: number;

package/dist/analytics/index.js

@@ -43,6 +43,14 @@ exports.EVENTS = {
     LOGGED_IN: 'logged_in',
     SOCIAL_ACCOUNT_CONNECTED: 'social_account_connected',
     COMPOSE_STARTED: 'compose_started',
+    // AD2-1371: the composer was a black box between COMPOSE_STARTED and
+    // POST_SCHEDULED. Measured 2026-08-28: of seven users who connected an
+    // account and never scheduled, the one who reached the composer opened it
+    // twice across two days and left both times, and the event stream carried
+    // nothing between arriving and leaving. These two say where they stopped
+    // and what stopped them.
+    COMPOSE_STEP_VIEWED: 'compose_step_viewed',
+    COMPOSE_BLOCKED: 'compose_blocked',
     POST_SCHEDULED: 'post_scheduled',
     POST_PUBLISHED: 'post_published', // server-confirmed (backend)
     PUBLISH_FAILED: 'publish_failed', // per-platform publish failure, server-owned (backend, AD2-999)

package/dist/publish-limits/index.d.ts

@@ -10,6 +10,36 @@
  *    ad2app-frontend/src/components/social/compose/platformConstants.ts
  *    (PLATFORM_CONFIGS[*].charLimit / maxImages / maxVideos / acceptsVideo /
  *    acceptsImages / metadata.mediaConstraints.maxVideoDuration).
+ *
+ *    CAVEAT ON THAT WORD "CORRECTED" (AD2-1369, measured 2026-08-28). It holds for
+ *    the character and count fields. It does NOT hold for maxVideoDurationSec, which
+ *    was inherited from platformConstants.ts wholesale and never checked against any
+ *    platform. Five platforms share the value 3600, which is a default rather than a
+ *    researched figure, and comparing the whole column against the export-specs
+ *    registry (.claude/skills/ad2app-graphics/data/export-specs.jsonl) shows it
+ *    disagrees with platform truth in both directions:
+ *
+ *      platform    ours     platform's own figure
+ *      twitter     3600     140s free; Premium up to 4h   -> ours is ABOVE the free tier
+ *      instagram   3600     900s (15 min)                 -> ours is ABOVE
+ *      linkedin    3600     600s (10 min)                 -> ours is ABOVE
+ *      pinterest    900     300s organic (900s is the ADS product) -> ours uses the ads figure
+ *      bluesky       60     180s                          -> ours is BELOW
+ *      facebook    3600     241 min                       -> ours is below, conservative
+ *      tiktok       600     600s via API                  -> matches
+ *      threads      300     300s                          -> matches
+ *      youtube    43200     43200s for verified accounts  -> matches (verified only)
+ *      reddit      3600     not recorded in the registry  -> unverified
+ *
+ *    An ABOVE-truth value is the worse half: we accept a video the platform will
+ *    reject, so the failure surfaces late, at publish time, instead of in compose.
+ *    A BELOW-truth value silently blocks something the user is allowed to post.
+ *
+ *    Nothing is changed here on purpose. Each row is a live publishing behaviour, and
+ *    the vendor we publish through (Zernio) may impose its own caps that none of these
+ *    numbers reflect; I could find no Zernio-side duration limits this session. Fixing
+ *    a row means verifying BOTH the platform figure and Zernio's, per platform, which
+ *    is its own ticket. Until then this table tells the truth about itself.
  *  - MAX_UPLOAD_BYTES matches ad2app-backend
  *    src/modules/late/late-media-upload.service.ts MAX_FILE_SIZE_BYTES + FR-105.
  *

package/dist/publish-limits/index.js

@@ -11,6 +11,36 @@
  *    ad2app-frontend/src/components/social/compose/platformConstants.ts
  *    (PLATFORM_CONFIGS[*].charLimit / maxImages / maxVideos / acceptsVideo /
  *    acceptsImages / metadata.mediaConstraints.maxVideoDuration).
+ *
+ *    CAVEAT ON THAT WORD "CORRECTED" (AD2-1369, measured 2026-08-28). It holds for
+ *    the character and count fields. It does NOT hold for maxVideoDurationSec, which
+ *    was inherited from platformConstants.ts wholesale and never checked against any
+ *    platform. Five platforms share the value 3600, which is a default rather than a
+ *    researched figure, and comparing the whole column against the export-specs
+ *    registry (.claude/skills/ad2app-graphics/data/export-specs.jsonl) shows it
+ *    disagrees with platform truth in both directions:
+ *
+ *      platform    ours     platform's own figure
+ *      twitter     3600     140s free; Premium up to 4h   -> ours is ABOVE the free tier
+ *      instagram   3600     900s (15 min)                 -> ours is ABOVE
+ *      linkedin    3600     600s (10 min)                 -> ours is ABOVE
+ *      pinterest    900     300s organic (900s is the ADS product) -> ours uses the ads figure
+ *      bluesky       60     180s                          -> ours is BELOW
+ *      facebook    3600     241 min                       -> ours is below, conservative
+ *      tiktok       600     600s via API                  -> matches
+ *      threads      300     300s                          -> matches
+ *      youtube    43200     43200s for verified accounts  -> matches (verified only)
+ *      reddit      3600     not recorded in the registry  -> unverified
+ *
+ *    An ABOVE-truth value is the worse half: we accept a video the platform will
+ *    reject, so the failure surfaces late, at publish time, instead of in compose.
+ *    A BELOW-truth value silently blocks something the user is allowed to post.
+ *
+ *    Nothing is changed here on purpose. Each row is a live publishing behaviour, and
+ *    the vendor we publish through (Zernio) may impose its own caps that none of these
+ *    numbers reflect; I could find no Zernio-side duration limits this session. Fixing
+ *    a row means verifying BOTH the platform figure and Zernio's, per platform, which
+ *    is its own ticket. Until then this table tells the truth about itself.
  *  - MAX_UPLOAD_BYTES matches ad2app-backend
  *    src/modules/late/late-media-upload.service.ts MAX_FILE_SIZE_BYTES + FR-105.
  *
@@ -107,6 +137,8 @@ exports.PUBLISH_LIMITS = {
         charLimit: 300,
         maxImages: 4,
         maxVideos: 1,
+        // 60 is OURS, not Bluesky's. Bluesky allows 180s (its social-app constants.ts sets
+        // VIDEO_MAX_DURATION_MS = 3 * 60 * 1000). Left as-is deliberately, see the header.
         maxVideoDurationSec: 60,
         acceptsVideo: true,
         acceptsImages: true,

package/package.json

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

package/src/analytics/index.test.ts

@@ -89,6 +89,8 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   [EVENTS.LOGGED_IN]: {},
   [EVENTS.SOCIAL_ACCOUNT_CONNECTED]: { platform: "instagram" },
   [EVENTS.COMPOSE_STARTED]: {},
+  [EVENTS.COMPOSE_STEP_VIEWED]: { step: "content" },
+  [EVENTS.COMPOSE_BLOCKED]: { step: "content", reasons: ["missing_fields"], reason_count: 1 },
   [EVENTS.POST_SCHEDULED]: { platforms: ["instagram"], platform_count: 1 },
   [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 },

package/src/analytics/index.ts

@@ -47,6 +47,14 @@ export const EVENTS = {
   LOGGED_IN: 'logged_in',
   SOCIAL_ACCOUNT_CONNECTED: 'social_account_connected',
   COMPOSE_STARTED: 'compose_started',
+  // AD2-1371: the composer was a black box between COMPOSE_STARTED and
+  // POST_SCHEDULED. Measured 2026-08-28: of seven users who connected an
+  // account and never scheduled, the one who reached the composer opened it
+  // twice across two days and left both times, and the event stream carried
+  // nothing between arriving and leaving. These two say where they stopped
+  // and what stopped them.
+  COMPOSE_STEP_VIEWED: 'compose_step_viewed',
+  COMPOSE_BLOCKED: 'compose_blocked',
   POST_SCHEDULED: 'post_scheduled',
   POST_PUBLISHED: 'post_published', // server-confirmed (backend)
   PUBLISH_FAILED: 'publish_failed', // per-platform publish failure, server-owned (backend, AD2-999)
@@ -198,6 +206,31 @@ export type AppLocale = 'en' | 'pl';
  * absent/unclassifiable error is `'unknown'`. Do NOT rename these values after
  * they ship — they are wire values, historical data does not migrate.
  */
+/**
+ * Which wizard step the composer is showing. Wire values, not indexes: a step
+ * reordered or inserted would silently re-label every historical row if this
+ * carried 0-3 (AD2-1371).
+ */
+export type ComposeStep =
+  | 'platforms' // step 1 — pick the accounts to post to
+  | 'content' // step 2 — caption and media
+  | 'details' // step 3 — per-platform required fields
+  | 'review'; // step 4 — schedule or publish
+
+/**
+ * Why the composer refused to advance. The readiness summary renders LOCALISED
+ * PROSE that names platforms and field labels, and the caption itself is user
+ * content, so neither may ride the event: only the class does. Same contract as
+ * PublishFailureReason. Do NOT rename after shipping — wire values.
+ */
+export type ComposeBlockReason =
+  | 'empty' // no caption and no media
+  | 'missing_fields' // a platform's required fields are unset
+  | 'over_limit' // caption longer than a selected platform allows
+  | 'media' // media rejected (format, size, duration, count)
+  | 'channel_blocked' // the channel itself refused (e.g. a failed prerequisite read)
+  | 'poll'; // an incomplete or unpostable poll
+
 export type PublishFailureReason =
   | 'auth' // token expired / revoked / missing scope / permission denied
   | 'rate_limit' // provider throttled us (429 / quota)
@@ -251,6 +284,14 @@ export interface EventProperties {
     connection_ordinal?: number;
   };
   [EVENTS.COMPOSE_STARTED]: { source?: 'wizard' | 'quick' };
+  [EVENTS.COMPOSE_STEP_VIEWED]: { step: ComposeStep };
+  [EVENTS.COMPOSE_BLOCKED]: {
+    step: ComposeStep;
+    /** Distinct reason classes present, deduped. Never the rendered prose. */
+    reasons: ComposeBlockReason[];
+    /** How many readiness lines the user faced, which `reasons` dedupes away. */
+    reason_count: number;
+  };
   [EVENTS.POST_SCHEDULED]: {
     platforms: string[];
     platform_count: number;

package/src/publish-limits/index.ts

@@ -10,6 +10,36 @@
  *    ad2app-frontend/src/components/social/compose/platformConstants.ts
  *    (PLATFORM_CONFIGS[*].charLimit / maxImages / maxVideos / acceptsVideo /
  *    acceptsImages / metadata.mediaConstraints.maxVideoDuration).
+ *
+ *    CAVEAT ON THAT WORD "CORRECTED" (AD2-1369, measured 2026-08-28). It holds for
+ *    the character and count fields. It does NOT hold for maxVideoDurationSec, which
+ *    was inherited from platformConstants.ts wholesale and never checked against any
+ *    platform. Five platforms share the value 3600, which is a default rather than a
+ *    researched figure, and comparing the whole column against the export-specs
+ *    registry (.claude/skills/ad2app-graphics/data/export-specs.jsonl) shows it
+ *    disagrees with platform truth in both directions:
+ *
+ *      platform    ours     platform's own figure
+ *      twitter     3600     140s free; Premium up to 4h   -> ours is ABOVE the free tier
+ *      instagram   3600     900s (15 min)                 -> ours is ABOVE
+ *      linkedin    3600     600s (10 min)                 -> ours is ABOVE
+ *      pinterest    900     300s organic (900s is the ADS product) -> ours uses the ads figure
+ *      bluesky       60     180s                          -> ours is BELOW
+ *      facebook    3600     241 min                       -> ours is below, conservative
+ *      tiktok       600     600s via API                  -> matches
+ *      threads      300     300s                          -> matches
+ *      youtube    43200     43200s for verified accounts  -> matches (verified only)
+ *      reddit      3600     not recorded in the registry  -> unverified
+ *
+ *    An ABOVE-truth value is the worse half: we accept a video the platform will
+ *    reject, so the failure surfaces late, at publish time, instead of in compose.
+ *    A BELOW-truth value silently blocks something the user is allowed to post.
+ *
+ *    Nothing is changed here on purpose. Each row is a live publishing behaviour, and
+ *    the vendor we publish through (Zernio) may impose its own caps that none of these
+ *    numbers reflect; I could find no Zernio-side duration limits this session. Fixing
+ *    a row means verifying BOTH the platform figure and Zernio's, per platform, which
+ *    is its own ticket. Until then this table tells the truth about itself.
  *  - MAX_UPLOAD_BYTES matches ad2app-backend
  *    src/modules/late/late-media-upload.service.ts MAX_FILE_SIZE_BYTES + FR-105.
  *
@@ -110,6 +140,8 @@ export const PUBLISH_LIMITS: Record<PublishPlatform, PlatformPublishLimits> = {
     charLimit: 300,
     maxImages: 4,
     maxVideos: 1,
+    // 60 is OURS, not Bluesky's. Bluesky allows 180s (its social-app constants.ts sets
+    // VIDEO_MAX_DURATION_MS = 3 * 60 * 1000). Left as-is deliberately, see the header.
     maxVideoDurationSec: 60,
     acceptsVideo: true,
     acceptsImages: true,