ad2app-lib 1.31.0 → 1.34.0

package/dist/analytics/index.d.ts

@@ -162,6 +162,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 +209,7 @@ export interface EventProperties {
     };
     [EVENTS.ACCOUNT_CONNECT_BLOCKED]: {
         platform?: string;
+        reason: ConnectBlockReason;
     };
     [EVENTS.MCP_POST_BLOCKED_FREE_TIER]: {
         target_count?: number;
@@ -374,6 +408,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)
@@ -126,6 +126,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/dist/types/scheduling/I_SchedulingPost.d.ts

@@ -74,6 +74,18 @@ export declare class SchedulingUpdatePostDTO {
     platforms?: SchedulingPlatformTargetDTO[];
     /** Full media array for the edit patch (C2, AD2-1026), same shape as create. */
     mediaItems?: SchedulingMediaItemDTO[];
+    /**
+     * Per-platform settings on the edit patch, same shape as create (AD2-1328).
+     * When PRESENT the patch is the full per-platform state: a platform it does
+     * not mention is cleared at the vendor. When ABSENT the stored per-target
+     * settings are carried over unchanged. The compose editor always sends it
+     * (`{}` when nothing is set) so a cleared field actually clears.
+     */
+    platformSpecificData?: Record<string, Record<string, unknown>>;
+    /** TikTok settings on the edit patch, same shape as create (AD2-1328). */
+    tiktokSettings?: Record<string, unknown>;
+    /** Compose disclosure on the edit patch, same shape as create (AD2-1328). */
+    disclosure?: SchedulingPostDisclosureDTO;
     constructor(data?: Partial<SchedulingUpdatePostDTO>);
 }
 /**

package/dist/types/scheduling/I_SchedulingPost.js

@@ -87,6 +87,9 @@ class SchedulingUpdatePostDTO {
         this.scheduledAt = data.scheduledAt;
         this.platforms = data.platforms;
         this.mediaItems = data.mediaItems;
+        this.platformSpecificData = data.platformSpecificData;
+        this.tiktokSettings = data.tiktokSettings;
+        this.disclosure = data.disclosure;
     }
 }
 exports.SchedulingUpdatePostDTO = SchedulingUpdatePostDTO;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.31.0",
+  "version": "1.34.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.ts

@@ -231,6 +231,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 +307,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;
@@ -408,7 +460,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`);
+	}
+});

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

@@ -91,6 +91,28 @@ test('SchedulingUpdatePostDTO platforms/mediaItems are absent by default (backwa
   assert.equal(patch.mediaItems, undefined);
 });
 
+// AD2-1328 — the compose editor has sent the per-platform trio on save since
+// AD2-1026; the backend typed it locally as an intersection because the lib
+// had no home for it. Pinned here so the local clone can retire at ship time.
+test('SchedulingUpdatePostDTO carries platformSpecificData/tiktokSettings/disclosure for the edit patch (AD2-1328)', () => {
+  const patch = new SchedulingUpdatePostDTO({
+    platforms: [new SchedulingPlatformTargetDTO({ platform: 'youtube', accountId: 'acc-yt' })],
+    platformSpecificData: { youtube: { title: 'Launch day' } },
+    tiktokSettings: { privacy_level: 'SELF_ONLY' },
+    disclosure: { aiGenerated: true },
+  });
+  assert.deepEqual(patch.platformSpecificData, { youtube: { title: 'Launch day' } });
+  assert.deepEqual(patch.tiktokSettings, { privacy_level: 'SELF_ONLY' });
+  assert.equal(patch.disclosure?.aiGenerated, true);
+});
+
+test('SchedulingUpdatePostDTO per-platform trio is absent by default, so absence still means "keep what is stored"', () => {
+  const patch = new SchedulingUpdatePostDTO({ content: 'x' });
+  assert.equal(patch.platformSpecificData, undefined);
+  assert.equal(patch.tiktokSettings, undefined);
+  assert.equal(patch.disclosure, undefined);
+});
+
 // AD2-1153 — the backend's local SocialPostStatus enum already has a
 // PUBLISHING member (Zernio accepted the post but its outcome couldn't be
 // confirmed inline); this pins the lib side so the backend's

package/src/types/scheduling/I_SchedulingPost.ts

@@ -134,6 +134,18 @@ export class SchedulingUpdatePostDTO {
   platforms?: SchedulingPlatformTargetDTO[];
   /** Full media array for the edit patch (C2, AD2-1026), same shape as create. */
   mediaItems?: SchedulingMediaItemDTO[];
+  /**
+   * Per-platform settings on the edit patch, same shape as create (AD2-1328).
+   * When PRESENT the patch is the full per-platform state: a platform it does
+   * not mention is cleared at the vendor. When ABSENT the stored per-target
+   * settings are carried over unchanged. The compose editor always sends it
+   * (`{}` when nothing is set) so a cleared field actually clears.
+   */
+  platformSpecificData?: Record<string, Record<string, unknown>>;
+  /** TikTok settings on the edit patch, same shape as create (AD2-1328). */
+  tiktokSettings?: Record<string, unknown>;
+  /** Compose disclosure on the edit patch, same shape as create (AD2-1328). */
+  disclosure?: SchedulingPostDisclosureDTO;
 
   constructor(data?: Partial<SchedulingUpdatePostDTO>) {
     if (!data) return;
@@ -141,6 +153,9 @@ export class SchedulingUpdatePostDTO {
     this.scheduledAt = data.scheduledAt;
     this.platforms = data.platforms;
     this.mediaItems = data.mediaItems;
+    this.platformSpecificData = data.platformSpecificData;
+    this.tiktokSettings = data.tiktokSettings;
+    this.disclosure = data.disclosure;
   }
 }