ad2app-lib 1.32.0 → 1.35.0

package/dist/analytics/index.d.ts

@@ -48,6 +48,7 @@ export declare const EVENTS: {
     readonly PAYWALL_DISMISSED: "paywall_dismissed";
     readonly ACCESS_DENIED: "access_denied";
     readonly ONBOARDING_STEP_COMPLETED: "onboarding_step_completed";
+    readonly ONBOARDING_STEP_VIEWED: "onboarding_step_viewed";
     readonly EXIT_INTENT_SHOWN: "exit_intent_shown";
     readonly EXIT_INTENT_DISMISSED: "exit_intent_dismissed";
     readonly EXIT_INTENT_CAPTURED: "exit_intent_captured";
@@ -162,6 +163,39 @@ export type ComposeStep = 'platforms' | 'content' | 'details' | 'review';
  * PublishFailureReason. Do NOT rename after shipping — wire values.
  */
 export type ComposeBlockReason = 'empty' | 'missing_fields' | 'over_limit' | 'media' | 'channel_blocked' | 'poll';
+/**
+ * Why a connect attempt ended without a connected account (spec 155 US3).
+ *
+ * Wire values, never renamed: historical rows do not migrate. A new cause is a
+ * new value appended here, never a re-meaning of an old one.
+ *
+ * - `paywall` — a free-tier user hit the connect wall (the pre-existing emit).
+ * - `canceled` — the person denied or dismissed the platform's OAuth.
+ * - `failed` — the vendor returned a failure on the callback.
+ * - `returned_without_account` — they came back and no account arrived: the
+ *   silent abandon, e.g. Facebook's Page picker offering an empty list to
+ *   someone who only has a personal profile.
+ * - `personal_profile` — they told us before OAuth that they post from a
+ *   personal Facebook profile, which Meta's API cannot publish to.
+ */
+/**
+ * Which finish line an onboarding completion crossed (094 US6/US8).
+ *
+ * Until 2026-09-01 the guided tour ended at a scheduled post, and almost
+ * nobody crossed it: four completions by two people in ninety days, against
+ * fifteen skips that all landed on the compose step. It now ends at a
+ * connected account. Both lines appear in the same series, so a completion
+ * that does not say which one it crossed turns a redefinition into an
+ * unexplained jump.
+ *
+ * Wire values, never renamed.
+ */
+export type OnboardingCompletedAt = 'connect' | 'install' | 'schedule';
+/** The finish lines, in the order the flow can reach them. */
+export declare const ONBOARDING_COMPLETED_AT: readonly ["connect", "install", "schedule"];
+export type ConnectBlockReason = 'paywall' | 'canceled' | 'failed' | 'returned_without_account' | 'personal_profile';
+/** The reason set, in the order the spec lists it. Iterable for contract tests and dashboards. */
+export declare const CONNECT_BLOCK_REASONS: readonly ["paywall", "canceled", "failed", "returned_without_account", "personal_profile"];
 export type PublishFailureReason = 'auth' | 'rate_limit' | 'media' | 'content' | 'network' | 'platform' | 'unknown';
 /** Property shape per event. Keeps emitters honest across repos. */
 export interface EventProperties {
@@ -176,6 +210,7 @@ export interface EventProperties {
     };
     [EVENTS.ACCOUNT_CONNECT_BLOCKED]: {
         platform?: string;
+        reason: ConnectBlockReason;
     };
     [EVENTS.MCP_POST_BLOCKED_FREE_TIER]: {
         target_count?: number;
@@ -312,11 +347,16 @@ export interface EventProperties {
         app_locale: AppLocale;
     };
     [EVENTS.ONBOARDING_STEP_COMPLETED]: {
-        flow: 'complete_profile';
+        flow: 'complete_profile' | 'beta_consent';
         step: string;
         step_index: number;
         app_locale: AppLocale;
     };
+    [EVENTS.ONBOARDING_STEP_VIEWED]: {
+        flow: 'complete_profile' | 'beta_consent';
+        step: string;
+        app_locale?: AppLocale;
+    };
     [EVENTS.EXIT_INTENT_SHOWN]: {
         surface: 'connect_wall';
         dwell_ms?: number;
@@ -374,6 +414,7 @@ export interface EventProperties {
     [EVENTS.ONBOARDING_COMPLETED]: {
         flow?: string;
         steps_completed?: number;
+        completed_at: OnboardingCompletedAt;
     };
     [EVENTS.ONBOARDING_SKIPPED]: {
         flow?: string;

package/dist/analytics/index.js

@@ -10,7 +10,7 @@
  * Do NOT rename events after they ship — historical data does not migrate.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PERSON_PROPS = exports.EMAIL_PROPS = exports.EVENTS = void 0;
+exports.PERSON_PROPS = exports.CONNECT_BLOCK_REASONS = exports.ONBOARDING_COMPLETED_AT = exports.EMAIL_PROPS = exports.EVENTS = void 0;
 /** Canonical PostHog event names. */
 exports.EVENTS = {
     // Acquisition (landing)
@@ -72,6 +72,12 @@ exports.EVENTS = {
     // 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)
+    // Promoted from a raw string literal at ad2app-frontend's
+    // OnboardingFlow.tsx:887 (spec 158, 2026-09-03) — it was already firing in
+    // production (15 events, 3 people) ungoverned since spec 095. `flow` is
+    // widened alongside ONBOARDING_STEP_COMPLETED below to cover the beta
+    // consent step, which is not part of the complete-profile flow.
+    ONBOARDING_STEP_VIEWED: 'onboarding_step_viewed', // a step was actually shown (drop-off, not just completion)
     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
@@ -126,6 +132,20 @@ exports.EMAIL_PROPS = {
     EDITION_VERSION: 'edition_version',
     FORMAT: 'format',
 };
+/** The finish lines, in the order the flow can reach them. */
+exports.ONBOARDING_COMPLETED_AT = [
+    'connect',
+    'install',
+    'schedule',
+];
+/** The reason set, in the order the spec lists it. Iterable for contract tests and dashboards. */
+exports.CONNECT_BLOCK_REASONS = [
+    'paywall',
+    'canceled',
+    'failed',
+    'returned_without_account',
+    'personal_profile',
+];
 /** Canonical person property keys (set via identify / $set). */
 exports.PERSON_PROPS = {
     EMAIL: 'email',

package/dist/connect-requirements/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The canonical table of what each platform needs before it can be connected.
+ *
+ * ONE home for these facts: the app renders them on the connect step and on
+ * /accounts, and nothing may restate them in a component. A line is rendered
+ * only where `requirement !== 'account'` — six platforms deliberately carry
+ * empty strings, and the UI renders no caption node for them at all.
+ *
+ * The cap on a rendered line is 70 characters, enforced by the contract test:
+ * it is what fits on one line under the platform name at 390px, measured in
+ * the spec 155 design preview.
+ *
+ * Copy: English authored here, Polish composed as Polish (spec 155
+ * `copy-pl.md`, Wariant F). Never edit a line inline — it is a copywriter pass.
+ */
+import type { ConnectRequirement, ConnectRequirementPlatform } from './types';
+export type { ConnectRequirement, ConnectRequirementKind, ConnectRequirementPlatform, } from './types';
+export declare const CONNECT_REQUIREMENT_PLATFORMS: readonly ConnectRequirementPlatform[];
+export declare const CONNECT_REQUIREMENTS: Record<ConnectRequirementPlatform, ConnectRequirement>;
+/**
+ * The line to render under a platform's name, or '' when the platform imposes
+ * no account condition. Callers render nothing at all for an empty string.
+ */
+export declare function connectRequirementLine(platform: ConnectRequirementPlatform, locale: 'en' | 'pl'): string;

package/dist/connect-requirements/index.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONNECT_REQUIREMENTS = exports.CONNECT_REQUIREMENT_PLATFORMS = void 0;
+exports.connectRequirementLine = connectRequirementLine;
+/** Verified against the sources below on this date; re-check when a platform changes its rules. */
+const VERIFIED_ON = '2026-09-01';
+const ZERNIO_DOCS = 'https://docs.zernio.com/platforms';
+exports.CONNECT_REQUIREMENT_PLATFORMS = [
+    'instagram',
+    'tiktok',
+    'facebook',
+    'youtube',
+    'twitter',
+    'linkedin',
+    'pinterest',
+    'threads',
+    'bluesky',
+    'reddit',
+];
+/** A platform with nothing to warn about: the account is the only requirement. */
+function plain(platform) {
+    return {
+        platform,
+        requirement: 'account',
+        en: '',
+        pl: '',
+        sourceUrl: `${ZERNIO_DOCS}/${platform}`,
+        verifiedOn: VERIFIED_ON,
+    };
+}
+exports.CONNECT_REQUIREMENTS = {
+    // "Facebook API only posts to Pages, not personal profiles." Professional
+    // mode on a profile does not open the API either; that fuller explanation
+    // lives in the Facebook sheet, not on the list.
+    facebook: {
+        platform: 'facebook',
+        requirement: 'page',
+        en: 'You need a Page where you are an admin or editor.',
+        pl: 'Potrzebna strona, na której jesteś administratorem lub redaktorem.',
+        sourceUrl: `${ZERNIO_DOCS}/facebook`,
+        verifiedOn: VERIFIED_ON,
+    },
+    // "Instagram requires a Business or Creator account. Personal accounts
+    // cannot post via API." Instagram Login is the default, so no Page is needed.
+    instagram: {
+        platform: 'instagram',
+        requirement: 'professional_account',
+        en: 'You need a professional account: Creator or Business.',
+        pl: 'Potrzebne konto profesjonalne: Twórca albo Firma.',
+        sourceUrl: `${ZERNIO_DOCS}/instagram`,
+        verifiedOn: VERIFIED_ON,
+    },
+    // Threads rides the Instagram account: "You must have an Instagram Business
+    // or Creator account with Threads enabled."
+    threads: {
+        platform: 'threads',
+        requirement: 'professional_account',
+        en: 'Your Instagram account: professional, with Threads turned on.',
+        pl: 'Twoje konto na Instagramie: profesjonalne i z włączonym Threads.',
+        sourceUrl: `${ZERNIO_DOCS}/threads`,
+        verifiedOn: VERIFIED_ON,
+    },
+    // Bluesky signs in with an app password, never the account password.
+    bluesky: {
+        platform: 'bluesky',
+        requirement: 'app_password',
+        en: 'Sign in with an app password, not your main account password.',
+        pl: 'Zaloguj się hasłem aplikacji, nie głównym hasłem do konta.',
+        sourceUrl: `${ZERNIO_DOCS}/bluesky`,
+        verifiedOn: VERIFIED_ON,
+    },
+    tiktok: plain('tiktok'),
+    youtube: plain('youtube'),
+    twitter: plain('twitter'),
+    linkedin: plain('linkedin'),
+    pinterest: plain('pinterest'),
+    reddit: plain('reddit'),
+};
+/**
+ * The line to render under a platform's name, or '' when the platform imposes
+ * no account condition. Callers render nothing at all for an empty string.
+ */
+function connectRequirementLine(platform, locale) {
+    return exports.CONNECT_REQUIREMENTS[platform][locale];
+}

package/dist/connect-requirements/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Per-platform connect requirements (spec 155).
+ *
+ * What a creator has to have BEFORE a platform's OAuth can succeed. Only four
+ * of the ten platforms impose anything; the rest only ever meet the platform's
+ * own consent screens, which is not worth a line on the connect list (design
+ * verdict F, Jan 2026-09-01, after the two-column preview showed ten lines
+ * crowding the step).
+ */
+/** The 10 platforms ad2app can connect. Matches the frontend's CONNECTABLE_PLATFORMS. */
+export type ConnectRequirementPlatform = 'instagram' | 'tiktok' | 'facebook' | 'youtube' | 'twitter' | 'linkedin' | 'pinterest' | 'threads' | 'bluesky' | 'reddit';
+/**
+ * What the platform demands of the account itself. Wire values: they drive
+ * whether a line renders, so renaming one silently blanks a warning.
+ *
+ * - `page` — publishing goes to a Page, never a personal profile (Facebook).
+ * - `professional_account` — the account must be a Creator/Business account
+ *   (Instagram, and Threads by way of the Instagram account behind it).
+ * - `app_password` — sign-in uses a per-app password, not the account password
+ *   (Bluesky).
+ * - `account` — no condition beyond having the account. Renders NO line.
+ */
+export type ConnectRequirementKind = 'page' | 'professional_account' | 'app_password' | 'account';
+export interface ConnectRequirement {
+    platform: ConnectRequirementPlatform;
+    requirement: ConnectRequirementKind;
+    /** The line shown under the platform name. Empty when `requirement` is `account`. */
+    en: string;
+    /** Polish is its own composition, not a translation of `en`. Empty when `requirement` is `account`. */
+    pl: string;
+    /** The vendor or platform document the claim rests on. */
+    sourceUrl: string;
+    /** ISO date the claim was last checked against `sourceUrl`. */
+    verifiedOn: string;
+}

package/dist/connect-requirements/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Per-platform connect requirements (spec 155).
+ *
+ * What a creator has to have BEFORE a platform's OAuth can succeed. Only four
+ * of the ten platforms impose anything; the rest only ever meet the platform's
+ * own consent screens, which is not worth a line on the connect list (design
+ * verdict F, Jan 2026-09-01, after the two-column preview showed ten lines
+ * crowding the step).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.32.0",
+  "version": "1.35.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -11,6 +11,7 @@
     "./legal": "./dist/legal/index.js",
     "./analytics": "./dist/analytics/index.js",
     "./publish-limits": "./dist/publish-limits/index.js",
+    "./connect-requirements": "./dist/connect-requirements/index.js",
     "./brand": "./brand/brand.mjs"
   },
   "typesVersions": {
@@ -36,6 +37,9 @@
       "brand": [
         "brand/brand.d.ts"
       ],
+      "connect-requirements": [
+        "dist/connect-requirements/index.d.ts"
+      ],
       "*": [
         "dist/index.d.ts"
       ]
@@ -47,7 +51,7 @@
     "prepare": "npm run build"
   },
   "keywords": [],
-  "author": "Maciej G\u00f3rski@ad2.app",
+  "author": "Maciej Górski@ad2.app",
   "license": "ISC",
   "description": "Package to share types and utils across the ad2app projects",
   "dependencies": {

package/src/analytics/account-connect-blocked.test.ts

@@ -0,0 +1,40 @@
+/**
+ * The connect-abandon contract (spec 155 US3).
+ *
+ * Every connect attempt that does not end with a connected account leaves one
+ * row with one reason. Before this, the event existed but only the paywall
+ * emitted it, so a person who walked into Meta's OAuth with a personal profile
+ * and never came back left no trace at all: their last event was the click
+ * (measured on a real tester, 2026-09-01 10:56:14).
+ */
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { CONNECT_BLOCK_REASONS, EVENTS } from './index';
+import type { ConnectBlockReason, EventProperties } from './index';
+
+test('the reason set is the five causes, as wire values', () => {
+	assert.deepEqual([...CONNECT_BLOCK_REASONS], [
+		'paywall',
+		'canceled',
+		'failed',
+		'returned_without_account',
+		'personal_profile',
+	]);
+});
+
+test('an emit without a reason does not type-check', () => {
+	// @ts-expect-error reason is required: a reasonless row is exactly the
+	// silent abandon this event exists to end.
+	const bad: EventProperties[typeof EVENTS.ACCOUNT_CONNECT_BLOCKED] = { platform: 'facebook' };
+	assert.ok(bad);
+});
+
+test('a full emit type-checks and carries the platform', () => {
+	const reason: ConnectBlockReason = 'personal_profile';
+	const good: EventProperties[typeof EVENTS.ACCOUNT_CONNECT_BLOCKED] = {
+		platform: 'facebook',
+		reason,
+	};
+	assert.equal(good.reason, 'personal_profile');
+});

package/src/analytics/index.test.ts

@@ -105,6 +105,7 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   [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.ONBOARDING_STEP_VIEWED]: { flow: "beta_consent", step: "consent" },
   [EVENTS.EXIT_INTENT_SHOWN]: { surface: "connect_wall" },
   [EVENTS.EXIT_INTENT_DISMISSED]: { surface: "connect_wall" },
   [EVENTS.EXIT_INTENT_CAPTURED]: { surface: "connect_wall" },
@@ -186,6 +187,10 @@ test("080 paywall / onboarding wire names are locked (rename breaks the baseline
   assert.equal(EVENTS.ONBOARDING_STEP_COMPLETED, "onboarding_step_completed");
 });
 
+test("158: onboarding_step_viewed wire name is locked — it was already live in production as a raw string before this promotion (rename breaks the existing 15 events)", () => {
+  assert.equal(EVENTS.ONBOARDING_STEP_VIEWED, "onboarding_step_viewed");
+});
+
 test("080 subscription-lifecycle wire names are locked (backend = source of truth)", () => {
   assert.deepEqual(
     [

package/src/analytics/index.ts

@@ -78,6 +78,12 @@ export const EVENTS = {
   // 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)
+  // Promoted from a raw string literal at ad2app-frontend's
+  // OnboardingFlow.tsx:887 (spec 158, 2026-09-03) — it was already firing in
+  // production (15 events, 3 people) ungoverned since spec 095. `flow` is
+  // widened alongside ONBOARDING_STEP_COMPLETED below to cover the beta
+  // consent step, which is not part of the complete-profile flow.
+  ONBOARDING_STEP_VIEWED: 'onboarding_step_viewed', // a step was actually shown (drop-off, not just completion)
   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
@@ -231,6 +237,58 @@ export type ComposeBlockReason =
   | 'channel_blocked' // the channel itself refused (e.g. a failed prerequisite read)
   | 'poll'; // an incomplete or unpostable poll
 
+/**
+ * Why a connect attempt ended without a connected account (spec 155 US3).
+ *
+ * Wire values, never renamed: historical rows do not migrate. A new cause is a
+ * new value appended here, never a re-meaning of an old one.
+ *
+ * - `paywall` — a free-tier user hit the connect wall (the pre-existing emit).
+ * - `canceled` — the person denied or dismissed the platform's OAuth.
+ * - `failed` — the vendor returned a failure on the callback.
+ * - `returned_without_account` — they came back and no account arrived: the
+ *   silent abandon, e.g. Facebook's Page picker offering an empty list to
+ *   someone who only has a personal profile.
+ * - `personal_profile` — they told us before OAuth that they post from a
+ *   personal Facebook profile, which Meta's API cannot publish to.
+ */
+/**
+ * Which finish line an onboarding completion crossed (094 US6/US8).
+ *
+ * Until 2026-09-01 the guided tour ended at a scheduled post, and almost
+ * nobody crossed it: four completions by two people in ninety days, against
+ * fifteen skips that all landed on the compose step. It now ends at a
+ * connected account. Both lines appear in the same series, so a completion
+ * that does not say which one it crossed turns a redefinition into an
+ * unexplained jump.
+ *
+ * Wire values, never renamed.
+ */
+export type OnboardingCompletedAt = 'connect' | 'install' | 'schedule';
+
+/** The finish lines, in the order the flow can reach them. */
+export const ONBOARDING_COMPLETED_AT = [
+  'connect',
+  'install',
+  'schedule',
+] as const satisfies readonly OnboardingCompletedAt[];
+
+export type ConnectBlockReason =
+  | 'paywall'
+  | 'canceled'
+  | 'failed'
+  | 'returned_without_account'
+  | 'personal_profile';
+
+/** The reason set, in the order the spec lists it. Iterable for contract tests and dashboards. */
+export const CONNECT_BLOCK_REASONS = [
+  'paywall',
+  'canceled',
+  'failed',
+  'returned_without_account',
+  'personal_profile',
+] as const satisfies readonly ConnectBlockReason[];
+
 export type PublishFailureReason =
   | 'auth' // token expired / revoked / missing scope / permission denied
   | 'rate_limit' // provider throttled us (429 / quota)
@@ -255,7 +313,7 @@ export interface EventProperties {
     target: 'app' | 'ask' | 'terminal' | 'editor';
   };
   [EVENTS.FREE_SKILLS_REQUESTED]: { source: string };
-  [EVENTS.ACCOUNT_CONNECT_BLOCKED]: { platform?: string };
+  [EVENTS.ACCOUNT_CONNECT_BLOCKED]: { platform?: string; reason: ConnectBlockReason };
   [EVENTS.MCP_POST_BLOCKED_FREE_TIER]: { target_count?: number };
   [EVENTS.EMAIL_SENT]: EmailEventProperties;
   [EVENTS.EMAIL_DELIVERED]: EmailEventProperties;
@@ -384,11 +442,19 @@ export interface EventProperties {
     app_locale: AppLocale;
   };
   [EVENTS.ONBOARDING_STEP_COMPLETED]: {
-    flow: 'complete_profile'; // closed set, extensible when a new flow ships
+    flow: 'complete_profile' | 'beta_consent'; // widened 2026-09-03 (spec 158) for the beta consent step
     step: string; // stable slug derived from the real wizard, not guessed
     step_index: number; // 1-based
     app_locale: AppLocale;
   };
+  // Promoted from a raw string (spec 158) — same `flow`/`step` shape as
+  // ONBOARDING_STEP_COMPLETED, fired once per step actually SHOWN rather than
+  // finished, so drop-off is visible per step, not only per completion.
+  [EVENTS.ONBOARDING_STEP_VIEWED]: {
+    flow: 'complete_profile' | 'beta_consent';
+    step: string;
+    app_locale?: AppLocale; // optional: the pre-existing raw call site does not have it yet (T001a repairs the call site, not the type's honesty about what ships today)
+  };
   // 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).
@@ -408,7 +474,11 @@ export interface EventProperties {
 
   // 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_COMPLETED]: {
+    flow?: string;
+    steps_completed?: number;
+    completed_at: OnboardingCompletedAt;
+  };
   [EVENTS.ONBOARDING_SKIPPED]: { flow?: string; step?: string };
 
   // Inbox engagement — platform is the social platform the comment/DM is on.

package/src/analytics/onboarding-completion.test.ts

@@ -0,0 +1,30 @@
+/**
+ * Which finish line a tour completion crossed (094 US8).
+ *
+ * The tour used to end at a scheduled post and now ends at a connected
+ * account. Both lines will appear in the same series, so the event has to say
+ * which one it was; without that the change reads as a sudden jump in
+ * completions rather than a redefinition.
+ */
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import { EVENTS, ONBOARDING_COMPLETED_AT } from './index';
+import type { EventProperties, OnboardingCompletedAt } from './index';
+
+test('the finish lines are a closed set of wire values', () => {
+	assert.deepEqual([...ONBOARDING_COMPLETED_AT], ['connect', 'install', 'schedule']);
+});
+
+test('a completion without its finish line does not type-check', () => {
+	// @ts-expect-error completed_at is required: an unlabelled completion is the
+	// ambiguity this property exists to remove.
+	const bad: EventProperties[typeof EVENTS.ONBOARDING_COMPLETED] = { steps_completed: 4 };
+	assert.ok(bad);
+});
+
+test('a labelled completion type-checks', () => {
+	const via: OnboardingCompletedAt = 'connect';
+	const good: EventProperties[typeof EVENTS.ONBOARDING_COMPLETED] = { completed_at: via };
+	assert.equal(good.completed_at, 'connect');
+});

package/src/connect-requirements/index.test.ts

@@ -0,0 +1,96 @@
+/**
+ * Contract tests for the per-platform connect requirements (spec 155, design
+ * verdict F, Jan 2026-09-01).
+ *
+ * The rule these lock: a line is rendered ONLY where the platform's API
+ * imposes a real account condition. Six of the ten platforms impose none, so
+ * they carry empty strings and the UI renders no caption node at all. A line
+ * that IS rendered has to fit one line under the platform name on a 390px
+ * phone, which is where the 70-character cap comes from (measured in the
+ * design preview: at 2 columns the same text truncated after three words).
+ */
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+
+import {
+	CONNECT_REQUIREMENTS,
+	CONNECT_REQUIREMENT_PLATFORMS,
+	connectRequirementLine,
+} from './index';
+import type { ConnectRequirement, ConnectRequirementPlatform } from './types';
+
+const MAX_LINE = 70;
+const CONSTRAINED: Record<string, string> = {
+	facebook: 'page',
+	instagram: 'professional_account',
+	threads: 'professional_account',
+	bluesky: 'app_password',
+};
+
+test('covers the ten connectable platforms, once each', () => {
+	assert.equal(CONNECT_REQUIREMENT_PLATFORMS.length, 10);
+	assert.equal(new Set(CONNECT_REQUIREMENT_PLATFORMS).size, 10);
+	for (const platform of CONNECT_REQUIREMENT_PLATFORMS) {
+		assert.ok(CONNECT_REQUIREMENTS[platform], `missing record: ${platform}`);
+		assert.equal(CONNECT_REQUIREMENTS[platform].platform, platform);
+	}
+});
+
+test('assigns the requirement kind each platform actually has', () => {
+	for (const platform of CONNECT_REQUIREMENT_PLATFORMS) {
+		const expected = CONNECT_REQUIREMENTS[platform].requirement;
+		assert.equal(expected, CONSTRAINED[platform] ?? 'account', `wrong kind: ${platform}`);
+	}
+});
+
+test('a constrained platform carries one short line in both locales', () => {
+	for (const platform of Object.keys(CONSTRAINED) as ConnectRequirementPlatform[]) {
+		const record = CONNECT_REQUIREMENTS[platform];
+		for (const locale of ['en', 'pl'] as const) {
+			const line = record[locale];
+			assert.ok(line.length > 0, `${platform}.${locale} is empty`);
+			assert.ok(
+				line.length <= MAX_LINE,
+				`${platform}.${locale} is ${line.length} chars, cap is ${MAX_LINE}`,
+			);
+		}
+	}
+});
+
+test('an unconstrained platform carries no line at all', () => {
+	const unconstrained = CONNECT_REQUIREMENT_PLATFORMS.filter((p) => !(p in CONSTRAINED));
+	assert.equal(unconstrained.length, 6);
+	for (const platform of unconstrained) {
+		assert.equal(CONNECT_REQUIREMENTS[platform].en, '');
+		assert.equal(CONNECT_REQUIREMENTS[platform].pl, '');
+		assert.equal(connectRequirementLine(platform, 'pl'), '');
+		assert.equal(connectRequirementLine(platform, 'en'), '');
+	}
+});
+
+test('no line carries a dash character or a screen count', () => {
+	for (const platform of CONNECT_REQUIREMENT_PLATFORMS) {
+		for (const locale of ['en', 'pl'] as const) {
+			const line = CONNECT_REQUIREMENTS[platform][locale];
+			assert.ok(!/[—–]/.test(line), `${platform}.${locale} contains a dash`);
+			assert.ok(
+				!/\d+\s*(screens?|ekran)/i.test(line),
+				`${platform}.${locale} promises a screen count`,
+			);
+		}
+	}
+});
+
+test('every record cites a source and the date it was verified', () => {
+	for (const platform of CONNECT_REQUIREMENT_PLATFORMS) {
+		const record: ConnectRequirement = CONNECT_REQUIREMENTS[platform];
+		assert.ok(record.sourceUrl.startsWith('https://'), `${platform} sourceUrl is not https`);
+		assert.match(record.verifiedOn, /^\d{4}-\d{2}-\d{2}$/, `${platform} verifiedOn is not a date`);
+	}
+});
+
+test('connectRequirementLine returns the locale asked for', () => {
+	assert.equal(connectRequirementLine('facebook', 'pl'), CONNECT_REQUIREMENTS.facebook.pl);
+	assert.equal(connectRequirementLine('facebook', 'en'), CONNECT_REQUIREMENTS.facebook.en);
+	assert.notEqual(CONNECT_REQUIREMENTS.facebook.pl, CONNECT_REQUIREMENTS.facebook.en);
+});

package/src/connect-requirements/index.ts

@@ -0,0 +1,115 @@
+/**
+ * The canonical table of what each platform needs before it can be connected.
+ *
+ * ONE home for these facts: the app renders them on the connect step and on
+ * /accounts, and nothing may restate them in a component. A line is rendered
+ * only where `requirement !== 'account'` — six platforms deliberately carry
+ * empty strings, and the UI renders no caption node for them at all.
+ *
+ * The cap on a rendered line is 70 characters, enforced by the contract test:
+ * it is what fits on one line under the platform name at 390px, measured in
+ * the spec 155 design preview.
+ *
+ * Copy: English authored here, Polish composed as Polish (spec 155
+ * `copy-pl.md`, Wariant F). Never edit a line inline — it is a copywriter pass.
+ */
+import type {
+	ConnectRequirement,
+	ConnectRequirementPlatform,
+} from './types';
+
+export type {
+	ConnectRequirement,
+	ConnectRequirementKind,
+	ConnectRequirementPlatform,
+} from './types';
+
+/** Verified against the sources below on this date; re-check when a platform changes its rules. */
+const VERIFIED_ON = '2026-09-01';
+
+const ZERNIO_DOCS = 'https://docs.zernio.com/platforms';
+
+export const CONNECT_REQUIREMENT_PLATFORMS: readonly ConnectRequirementPlatform[] = [
+	'instagram',
+	'tiktok',
+	'facebook',
+	'youtube',
+	'twitter',
+	'linkedin',
+	'pinterest',
+	'threads',
+	'bluesky',
+	'reddit',
+];
+
+/** A platform with nothing to warn about: the account is the only requirement. */
+function plain(platform: ConnectRequirementPlatform): ConnectRequirement {
+	return {
+		platform,
+		requirement: 'account',
+		en: '',
+		pl: '',
+		sourceUrl: `${ZERNIO_DOCS}/${platform}`,
+		verifiedOn: VERIFIED_ON,
+	};
+}
+
+export const CONNECT_REQUIREMENTS: Record<ConnectRequirementPlatform, ConnectRequirement> = {
+	// "Facebook API only posts to Pages, not personal profiles." Professional
+	// mode on a profile does not open the API either; that fuller explanation
+	// lives in the Facebook sheet, not on the list.
+	facebook: {
+		platform: 'facebook',
+		requirement: 'page',
+		en: 'You need a Page where you are an admin or editor.',
+		pl: 'Potrzebna strona, na której jesteś administratorem lub redaktorem.',
+		sourceUrl: `${ZERNIO_DOCS}/facebook`,
+		verifiedOn: VERIFIED_ON,
+	},
+	// "Instagram requires a Business or Creator account. Personal accounts
+	// cannot post via API." Instagram Login is the default, so no Page is needed.
+	instagram: {
+		platform: 'instagram',
+		requirement: 'professional_account',
+		en: 'You need a professional account: Creator or Business.',
+		pl: 'Potrzebne konto profesjonalne: Twórca albo Firma.',
+		sourceUrl: `${ZERNIO_DOCS}/instagram`,
+		verifiedOn: VERIFIED_ON,
+	},
+	// Threads rides the Instagram account: "You must have an Instagram Business
+	// or Creator account with Threads enabled."
+	threads: {
+		platform: 'threads',
+		requirement: 'professional_account',
+		en: 'Your Instagram account: professional, with Threads turned on.',
+		pl: 'Twoje konto na Instagramie: profesjonalne i z włączonym Threads.',
+		sourceUrl: `${ZERNIO_DOCS}/threads`,
+		verifiedOn: VERIFIED_ON,
+	},
+	// Bluesky signs in with an app password, never the account password.
+	bluesky: {
+		platform: 'bluesky',
+		requirement: 'app_password',
+		en: 'Sign in with an app password, not your main account password.',
+		pl: 'Zaloguj się hasłem aplikacji, nie głównym hasłem do konta.',
+		sourceUrl: `${ZERNIO_DOCS}/bluesky`,
+		verifiedOn: VERIFIED_ON,
+	},
+	tiktok: plain('tiktok'),
+	youtube: plain('youtube'),
+	twitter: plain('twitter'),
+	linkedin: plain('linkedin'),
+	pinterest: plain('pinterest'),
+	reddit: plain('reddit'),
+};
+
+/**
+ * The line to render under a platform's name, or '' when the platform imposes
+ * no account condition. Callers render nothing at all for an empty string.
+ */
+export function connectRequirementLine(
+	platform: ConnectRequirementPlatform,
+	locale: 'en' | 'pl',
+): string {
+	return CONNECT_REQUIREMENTS[platform][locale];
+}

package/src/connect-requirements/types.ts

@@ -0,0 +1,52 @@
+/**
+ * Per-platform connect requirements (spec 155).
+ *
+ * What a creator has to have BEFORE a platform's OAuth can succeed. Only four
+ * of the ten platforms impose anything; the rest only ever meet the platform's
+ * own consent screens, which is not worth a line on the connect list (design
+ * verdict F, Jan 2026-09-01, after the two-column preview showed ten lines
+ * crowding the step).
+ */
+
+/** The 10 platforms ad2app can connect. Matches the frontend's CONNECTABLE_PLATFORMS. */
+export type ConnectRequirementPlatform =
+	| 'instagram'
+	| 'tiktok'
+	| 'facebook'
+	| 'youtube'
+	| 'twitter'
+	| 'linkedin'
+	| 'pinterest'
+	| 'threads'
+	| 'bluesky'
+	| 'reddit';
+
+/**
+ * What the platform demands of the account itself. Wire values: they drive
+ * whether a line renders, so renaming one silently blanks a warning.
+ *
+ * - `page` — publishing goes to a Page, never a personal profile (Facebook).
+ * - `professional_account` — the account must be a Creator/Business account
+ *   (Instagram, and Threads by way of the Instagram account behind it).
+ * - `app_password` — sign-in uses a per-app password, not the account password
+ *   (Bluesky).
+ * - `account` — no condition beyond having the account. Renders NO line.
+ */
+export type ConnectRequirementKind =
+	| 'page'
+	| 'professional_account'
+	| 'app_password'
+	| 'account';
+
+export interface ConnectRequirement {
+	platform: ConnectRequirementPlatform;
+	requirement: ConnectRequirementKind;
+	/** The line shown under the platform name. Empty when `requirement` is `account`. */
+	en: string;
+	/** Polish is its own composition, not a translation of `en`. Empty when `requirement` is `account`. */
+	pl: string;
+	/** The vendor or platform document the claim rests on. */
+	sourceUrl: string;
+	/** ISO date the claim was last checked against `sourceUrl`. */
+	verifiedOn: string;
+}

package/src/package-exports.test.ts

@@ -0,0 +1,44 @@
+/**
+ * Every published subpath resolves BOTH at runtime and for TypeScript.
+ *
+ * Spec 155 caught this the expensive way: `exports` gained
+ * `./connect-requirements` but `typesVersions` did not, so `npm run build`
+ * passed in the lib and the consumer failed with "Cannot find module
+ * 'ad2app-lib/connect-requirements' or its corresponding type declarations".
+ * The two maps are one fact and drift silently, so pin them together.
+ */
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { test } from 'node:test';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {
+	exports: Record<string, string>;
+	typesVersions: Record<string, Record<string, string[]>>;
+};
+
+test('every export subpath has a matching typesVersions entry', () => {
+	const subpaths = Object.keys(pkg.exports)
+		.filter((key) => key !== '.')
+		.map((key) => key.replace(/^\.\//, ''));
+	const typed = pkg.typesVersions['*'];
+	for (const subpath of subpaths) {
+		assert.ok(typed[subpath], `exports has "${subpath}" but typesVersions does not`);
+		assert.match(
+			typed[subpath][0],
+			/\.d\.(ts|mts)$/,
+			`typesVersions["${subpath}"] must point at a declaration file`,
+		);
+	}
+});
+
+test('every typesVersions entry except the catch-all has an export', () => {
+	const exported = new Set(
+		Object.keys(pkg.exports)
+			.filter((key) => key !== '.')
+			.map((key) => key.replace(/^\.\//, '')),
+	);
+	for (const subpath of Object.keys(pkg.typesVersions['*'])) {
+		if (subpath === '*') continue;
+		assert.ok(exported.has(subpath), `typesVersions has "${subpath}" but exports does not`);
+	}
+});