ad2app-lib 1.29.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/dist/types/I_User.d.ts

@@ -10,8 +10,39 @@ export declare class I_User {
     has_connected_platforms?: boolean;
     influencer?: I_Influencer;
 }
+/**
+ * The answer an account has recorded about the onboarding tour.
+ *
+ * Three values, and the difference between the last two is the whole point:
+ *   'skipped' | 'completed' — a recorded answer. Never re-teach this user.
+ *   null                    — no record yet. A genuinely new user; show it.
+ *   ABSENT (the field is missing entirely) — the server could not read the
+ *                             column. Decide NOTHING.
+ *
+ * Absent is deliberately not `null`. Collapsing them shows the tour to every
+ * existing user in the window between a deploy and its manual migration
+ * (migrations here are run by hand, never on deploy).
+ */
+export type OnboardingState = 'skipped' | 'completed';
 export declare class I_SignedUser extends I_User {
     accessToken: string;
+    /**
+     * AD2-1331 AC3 (Maciej's review, 2026-08-25). Every response that hands back
+     * a session carries this, not just `authenticate` — the client replaces its
+     * authed slice wholesale with whichever payload arrives, so a path that omits
+     * it leaves the answer unknown for the rest of the session (AD2-1329 AC4).
+     *
+     * It lives HERE because AC3 chose an echoing PATCH over a failing one
+     * specifically to remove the forward-only rule from the client, and that only
+     * works if both sides agree on the shape. Until this shipped, the field was
+     * written by the backend, read by the frontend, and declared by neither: the
+     * frontend had to cast through `unknown` to see it, and a rename on either
+     * side would have type-checked clean while the onboarding funnel silently
+     * went dark.
+     *
+     * Optional on purpose — see OnboardingState: absent means "could not read".
+     */
+    onboardingState?: OnboardingState | null;
 }
 export declare enum UserRoles {
     ADMIN = "ADMIN",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -47,7 +47,7 @@
     "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

@@ -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,

package/src/types/I_User.ts

@@ -13,8 +13,41 @@ export class I_User {
   influencer?: I_Influencer;
 }
 
+/**
+ * The answer an account has recorded about the onboarding tour.
+ *
+ * Three values, and the difference between the last two is the whole point:
+ *   'skipped' | 'completed' — a recorded answer. Never re-teach this user.
+ *   null                    — no record yet. A genuinely new user; show it.
+ *   ABSENT (the field is missing entirely) — the server could not read the
+ *                             column. Decide NOTHING.
+ *
+ * Absent is deliberately not `null`. Collapsing them shows the tour to every
+ * existing user in the window between a deploy and its manual migration
+ * (migrations here are run by hand, never on deploy).
+ */
+export type OnboardingState = 'skipped' | 'completed';
+
 export class I_SignedUser extends I_User {
   accessToken: string;
+
+  /**
+   * AD2-1331 AC3 (Maciej's review, 2026-08-25). Every response that hands back
+   * a session carries this, not just `authenticate` — the client replaces its
+   * authed slice wholesale with whichever payload arrives, so a path that omits
+   * it leaves the answer unknown for the rest of the session (AD2-1329 AC4).
+   *
+   * It lives HERE because AC3 chose an echoing PATCH over a failing one
+   * specifically to remove the forward-only rule from the client, and that only
+   * works if both sides agree on the shape. Until this shipped, the field was
+   * written by the backend, read by the frontend, and declared by neither: the
+   * frontend had to cast through `unknown` to see it, and a rename on either
+   * side would have type-checked clean while the onboarding funnel silently
+   * went dark.
+   *
+   * Optional on purpose — see OnboardingState: absent means "could not read".
+   */
+  onboardingState?: OnboardingState | null;
 }
 
 export enum UserRoles {

package/src/types/onboarding-state.test.ts

@@ -0,0 +1,66 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { I_SignedUser, OnboardingState, UserRoles } from './I_User';
+
+/**
+ * AD2-1331 AC3 — the shared shape, pinned.
+ *
+ * These are mostly COMPILE-time assertions: the value of this file is that
+ * `tsc` fails if `onboardingState` is renamed, narrowed, or made required on
+ * one side of the wire. Before it existed the field was written by the backend,
+ * read by the frontend, and declared by neither, so either side could rename it
+ * and every type-check would still pass while the onboarding funnel went dark.
+ *
+ * The runtime assertions below exist so the file is also a real test rather
+ * than a silent type-only artefact that a test runner skips over.
+ */
+
+test('a signed user may carry a recorded answer', () => {
+	const user: I_SignedUser = {
+		id: 'u-1',
+		role: UserRoles.INFLUENCER,
+		accessToken: 'tok',
+		onboardingState: 'completed',
+	};
+
+	assert.equal(user.onboardingState, 'completed');
+});
+
+test('null is a value, and means "no record yet" — a new user', () => {
+	const user: I_SignedUser = {
+		id: 'u-1',
+		role: UserRoles.INFLUENCER,
+		accessToken: 'tok',
+		onboardingState: null,
+	};
+
+	// null must survive as null: the client tells it apart from absent, and
+	// only null means "show the tour".
+	assert.equal(user.onboardingState, null);
+	assert.ok('onboardingState' in user);
+});
+
+test('ABSENT is distinct from null — the field may be omitted entirely', () => {
+	// The migration-pending case. If this ever stops compiling because the
+	// field was made required, the deploy window that follows would show the
+	// onboarding tour to the entire existing user base.
+	const user: I_SignedUser = {
+		id: 'u-1',
+		role: UserRoles.INFLUENCER,
+		accessToken: 'tok',
+	};
+
+	assert.equal('onboardingState' in user, false);
+	assert.equal(user.onboardingState, undefined);
+});
+
+test('the state union is exactly the two recorded answers', () => {
+	const every: OnboardingState[] = ['skipped', 'completed'];
+
+	assert.deepEqual(every, ['skipped', 'completed']);
+	// @ts-expect-error 'pending' is not a recorded answer; null/absent cover
+	// "no answer", and a third string would be a state nobody handles.
+	const invalid: OnboardingState = 'pending';
+	assert.equal(invalid, 'pending');
+});