ad2app-lib 1.25.0 → 1.28.0

package/brand/brand.d.ts

@@ -23,12 +23,42 @@ export interface ColorTokens {
 	error: string;
 	/** The PRODUCT blue, deliberately distinct from the marketing primary. */
 	productPrimary: string;
+	/**
+	 * v5 accent ramp (spec 124): the landing's color-field language — tonal
+	 * hi/lo stops for ramped fields, tint for card fills. WHITE text on
+	 * magenta/violet fields, DARK text on lime/aqua.
+	 */
+	v5: {
+		magenta: string;
+		magentaHi: string;
+		magentaLo: string;
+		magentaTint: string;
+		violet: string;
+		violetHi: string;
+		violetLo: string;
+		lime: string;
+		limeHi: string;
+		limeLo: string;
+		aqua: string;
+		aquaHi: string;
+		aquaLo: string;
+		borderStrong: string;
+	};
 }
 export const color: ColorTokens;
 
+export interface DisplayFontTokens {
+	/** Direction-5 display face (spec 099 US5, OFL). Display roles only. */
+	family: string;
+	weights: readonly number[];
+	/** Below this size the face is illegible by design — fall back to `family`. */
+	minSizePx: number;
+	role: string;
+}
 export interface FontTokens {
 	family: string;
 	fallback: string;
+	display: DisplayFontTokens;
 }
 export const font: FontTokens;
 

package/brand/brand.mjs

@@ -21,11 +21,46 @@ export const color = {
   successText: '#0f7a33',
   error: '#ff3b30',
   productPrimary: '#0000ff',   // the PRODUCT blue, deliberately distinct from marketing #0042ff
+
+  // v5 accent ramp (spec 124): the landing's color-field language — tonal hi/lo stops for
+  // ramped fields, tint for card fills. Mirrors ad2app-landing globals.css EXACTLY (the
+  // contract test pins equality). Contrast rule from the landing: WHITE text on
+  // magenta/violet fields, DARK text on lime/aqua (lime additionally wants heavy grain).
+  v5: {
+    magenta: '#ff2d78',
+    magentaHi: '#ff5c95',
+    magentaLo: '#e0175f',
+    magentaTint: '#fff0f5',
+    violet: '#7c3aed',
+    violetHi: '#9d6ff5',
+    violetLo: '#6323d0',
+    lime: '#d9f24b',
+    limeHi: '#e9fa74',
+    limeLo: '#becc25',
+    aqua: '#4dd6f5',
+    aquaHi: '#7ce4fa',
+    aquaLo: '#22b8dd',
+    borderStrong: '#8e8e9a',
+  },
 };
 
 export const font = {
   family: 'Funnel Sans',
   fallback: '-apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif',
+  // The Direction-5 DISPLAY face (spec 099 US5; Jan-picked from a five-font exploration; OFL).
+  // It lived only in the landing (SiteShell.tsx wires it through next/font, globals.css exposes it
+  // as --font-display) until 2026-08-12, when a rendered story card was judged against the live
+  // landing and read as another company's: every headline in the motion lane was being set in the
+  // BODY face, because this token had no home here. Display roles ONLY — H1/H2 and big numerals.
+  // Below ~24px Unbounded is illegible by design, so body and UI stay Funnel Sans.
+  // A non-Next consumer (the Remotion lane) must self-host the same family; there is no CDN at
+  // render time.
+  display: {
+    family: 'Unbounded',
+    weights: [500, 700],
+    minSizePx: 24,
+    role: 'display only: h1, h2, big numerals — never body or UI',
+  },
 };
 
 // Social canvas sizes (px), the canonical ad set.

package/dist/analytics/index.d.ts

@@ -15,11 +15,18 @@ export declare const EVENTS: {
     readonly FREE_SKILLS_REQUESTED: "free_skills_requested";
     readonly ACCOUNT_CONNECT_BLOCKED: "account_connect_blocked";
     readonly MCP_POST_BLOCKED_FREE_TIER: "mcp_post_blocked_free_tier";
+    readonly EMAIL_SENT: "email_sent";
     readonly EMAIL_DELIVERED: "email_delivered";
     readonly EMAIL_OPENED: "email_opened";
     readonly EMAIL_CLICKED: "email_clicked";
     readonly EMAIL_BOUNCED: "email_bounced";
     readonly EMAIL_COMPLAINED: "email_complained";
+    readonly EMAIL_FAILED: "email_failed";
+    readonly EMAIL_DELIVERY_DELAYED: "email_delivery_delayed";
+    readonly EMAIL_UNSUBSCRIBED: "email_unsubscribed";
+    readonly EMAIL_SUPPRESSED: "email_suppressed";
+    readonly PLAYBOOK_OPENED: "playbook_opened";
+    readonly PLAYBOOK_DOWNLOADED: "playbook_downloaded";
     readonly SIGNED_UP: "signed_up";
     readonly PROFILE_COMPLETED: "profile_completed";
     readonly LOGGED_IN: "logged_in";
@@ -66,12 +73,56 @@ export declare const EVENTS: {
     readonly NOTIFICATION_PREFERENCES_UPDATED: "notification_preferences_updated";
 };
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
-/** Shared shape for the Resend email lifecycle events (AD2-894). */
-export interface EmailEventProperties {
+/** Which email program a send belongs to (spec 120). Wire values — do not rename. */
+export type EmailStream = 'transactional' | 'nurture' | 'broadcast';
+/** How an unsubscribe arrived (spec 120). */
+export type UnsubscribeMechanism = 'one_click' | 'footer_link';
+/** Why an address entered the suppression list (spec 120). */
+export type SuppressionReason = 'hard_bounce' | 'complaint';
+/**
+ * BASE property set every email event carries (spec 120 T001 contract). All
+ * fields are optional AT THE TYPE LEVEL only because legacy tag-less sends
+ * resolve by email lookup and legitimately lack stream/trigger context (they
+ * carry `unjoined: true` instead); the backend tests enforce the full set on
+ * every NEW send. Identity (distinct_id) rides the capture call, not this shape.
+ */
+export interface EmailEventBaseProperties {
+    email_stream?: EmailStream;
+    trigger_key?: string;
+    variant?: string;
+    has_attachment?: boolean;
     email_id?: string;
+    unjoined?: boolean;
+}
+/**
+ * Shared shape for the Resend email lifecycle events (AD2-894; widened by spec
+ * 120 to carry the base set — additive, wire names unchanged).
+ */
+export interface EmailEventProperties extends EmailEventBaseProperties {
     subject?: string;
     link?: string;
 }
+/**
+ * Canonical email event property KEYS (spec 120 T001). Emitters and tests
+ * reference these instead of retyping strings — the single home for the names.
+ */
+export declare const EMAIL_PROPS: {
+    readonly EMAIL_STREAM: "email_stream";
+    readonly TRIGGER_KEY: "trigger_key";
+    readonly VARIANT: "variant";
+    readonly HAS_ATTACHMENT: "has_attachment";
+    readonly EMAIL_ID: "email_id";
+    readonly UNJOINED: "unjoined";
+    readonly SUBJECT: "subject";
+    readonly LINK: "link";
+    readonly BOUNCE_TYPE: "bounce_type";
+    readonly MPP_SUSPECTED: "mpp_suspected";
+    readonly REASON: "reason";
+    readonly MECHANISM: "mechanism";
+    readonly HOURS_SINCE_SEND: "hours_since_send";
+    readonly EDITION_VERSION: "edition_version";
+    readonly FORMAT: "format";
+};
 /**
  * Where a paywall / upgrade / checkout moment was triggered from (080). A named,
  * stable, closed set so the revenue funnel can attribute conversions to their
@@ -113,11 +164,34 @@ export interface EventProperties {
     [EVENTS.MCP_POST_BLOCKED_FREE_TIER]: {
         target_count?: number;
     };
+    [EVENTS.EMAIL_SENT]: EmailEventProperties;
     [EVENTS.EMAIL_DELIVERED]: EmailEventProperties;
-    [EVENTS.EMAIL_OPENED]: EmailEventProperties;
+    [EVENTS.EMAIL_OPENED]: EmailEventProperties & {
+        mpp_suspected?: boolean;
+    };
     [EVENTS.EMAIL_CLICKED]: EmailEventProperties;
-    [EVENTS.EMAIL_BOUNCED]: EmailEventProperties;
+    [EVENTS.EMAIL_BOUNCED]: EmailEventProperties & {
+        bounce_type?: string;
+    };
     [EVENTS.EMAIL_COMPLAINED]: EmailEventProperties;
+    [EVENTS.EMAIL_FAILED]: EmailEventProperties & {
+        reason?: string;
+    };
+    [EVENTS.EMAIL_DELIVERY_DELAYED]: EmailEventProperties;
+    [EVENTS.EMAIL_UNSUBSCRIBED]: EmailEventProperties & {
+        mechanism?: UnsubscribeMechanism;
+        hours_since_send?: number;
+    };
+    [EVENTS.EMAIL_SUPPRESSED]: EmailEventProperties & {
+        reason?: SuppressionReason;
+    };
+    [EVENTS.PLAYBOOK_OPENED]: {
+        edition_version?: string;
+    };
+    [EVENTS.PLAYBOOK_DOWNLOADED]: {
+        edition_version?: string;
+        format?: string;
+    };
     [EVENTS.SIGNED_UP]: {
         method: 'email' | 'google';
         role: 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.EVENTS = void 0;
+exports.PERSON_PROPS = exports.EMAIL_PROPS = exports.EVENTS = void 0;
 /** Canonical PostHog event names. */
 exports.EVENTS = {
     // Acquisition (landing)
@@ -20,12 +20,23 @@ exports.EVENTS = {
     FREE_SKILLS_REQUESTED: 'free_skills_requested', // email submitted for the free skills (AD2-889)
     ACCOUNT_CONNECT_BLOCKED: 'account_connect_blocked', // free user hits the connect wall (AD2-892)
     MCP_POST_BLOCKED_FREE_TIER: 'mcp_post_blocked_free_tier', // free user tries to post in the MCP (AD2-898)
-    // Email lifecycle (Resend webhook -> PostHog, AD2-894)
+    // Email lifecycle (Resend webhook -> PostHog, AD2-894; extended by spec 120:
+    // send-time denominator + failure/delay mappings + list-hygiene events, all
+    // carrying the EmailEventBaseProperties set per
+    // specs/120-email-program-v2/contracts/email-event-properties.md)
+    EMAIL_SENT: 'email_sent', // send-time, at the ResendService choke points (the denominator)
     EMAIL_DELIVERED: 'email_delivered',
     EMAIL_OPENED: 'email_opened',
     EMAIL_CLICKED: 'email_clicked',
     EMAIL_BOUNCED: 'email_bounced',
     EMAIL_COMPLAINED: 'email_complained',
+    EMAIL_FAILED: 'email_failed', // webhook email.failed
+    EMAIL_DELIVERY_DELAYED: 'email_delivery_delayed', // webhook email.delivery_delayed
+    EMAIL_UNSUBSCRIBED: 'email_unsubscribed', // one-click header or footer link
+    EMAIL_SUPPRESSED: 'email_suppressed', // suppression-list upsert (hard bounce / complaint)
+    // Posting Playbook (spec 120 US2) — hosted artifact engagement
+    PLAYBOOK_OPENED: 'playbook_opened',
+    PLAYBOOK_DOWNLOADED: 'playbook_downloaded',
     // Activation (web app)
     SIGNED_UP: 'signed_up', // server-owned (backend, on user creation)
     PROFILE_COMPLETED: 'profile_completed', // the /complete-profile step (influencers)
@@ -86,6 +97,27 @@ exports.EVENTS = {
     // Settings.
     NOTIFICATION_PREFERENCES_UPDATED: 'notification_preferences_updated',
 };
+/**
+ * Canonical email event property KEYS (spec 120 T001). Emitters and tests
+ * reference these instead of retyping strings — the single home for the names.
+ */
+exports.EMAIL_PROPS = {
+    EMAIL_STREAM: 'email_stream',
+    TRIGGER_KEY: 'trigger_key',
+    VARIANT: 'variant',
+    HAS_ATTACHMENT: 'has_attachment',
+    EMAIL_ID: 'email_id',
+    UNJOINED: 'unjoined',
+    SUBJECT: 'subject',
+    LINK: 'link',
+    BOUNCE_TYPE: 'bounce_type',
+    MPP_SUSPECTED: 'mpp_suspected',
+    REASON: 'reason',
+    MECHANISM: 'mechanism',
+    HOURS_SINCE_SEND: 'hours_since_send',
+    EDITION_VERSION: 'edition_version',
+    FORMAT: 'format',
+};
 /** Canonical person property keys (set via identify / $set). */
 exports.PERSON_PROPS = {
     EMAIL: 'email',

package/dist/api/apiDriver.d.ts

@@ -3,6 +3,14 @@ type HttpMethod = "get" | "post" | "put" | "PATCH" | "delete";
 interface DriverConfig {
     apiUrl: string;
     getHeaders?: () => HeadersInit;
+    /**
+     * Forwarded verbatim to `fetch`'s own `credentials` option on every call
+     * (AD2-1297: the frontend needs `'include'` so the backend's HttpOnly
+     * session cookie actually rides along on a cross-subdomain request).
+     * Undefined preserves the previous, unconfigured behavior (the browser's
+     * `fetch` default, `'same-origin'`) for any other consumer of this driver.
+     */
+    credentials?: RequestCredentials;
 }
 /**
  * Thrown by `fetchCall` for any non-2xx response.

package/dist/api/apiDriver.js

@@ -47,6 +47,7 @@ async function fetchCall(args) {
     const init = {
         method,
         headers,
+        ...(CONFIG?.credentials ? { credentials: CONFIG.credentials } : {}),
     };
     if (params?.body) {
         if (transformers?.body) {

package/dist/legal/terms.js

@@ -23,7 +23,7 @@ exports.TERMS_SECTIONS = [
                     { text: 'Media and content file management.' },
                     { text: 'Optional connection of third-party AI assistants and tools that support the Model Context Protocol (MCP), letting you manage scheduling, posting, and analytics from within a tool of your choice. See Section 13 and our {PRIVACY}.' },
                 ] },
-            { kind: 'p', text: 'The Service is offered on three plans: **Free** (connecting new social accounts and publishing are not available on this plan; if you previously had a paid plan, your previously-connected accounts, post history, and analytics also become inaccessible while you are on the Free plan. That data is retained, not deleted, and becomes available again if you resubscribe), **Starter**, and **Pro** (Starter and Pro differ only in how many social accounts you may connect; all other features are identical). Current plan details and pricing are shown in the app and on our pricing page.' },
+            { kind: 'p', text: 'The Service is offered on three plans: **Free** (connecting new social accounts and publishing are not available on this plan; if you previously had a paid plan or a beta place, your previously-connected accounts, post history, and analytics remain visible to you in read-only form. That data is retained, not deleted, and full access returns if you subscribe), **Starter**, and **Pro** (Starter and Pro differ only in how many social accounts you may connect; all other features are identical). Current plan details and pricing are shown in the app and on our pricing page.' },
             { kind: 'p', text: 'Not all features described in these Terms are available in every plan. We may modify the Service where this is not necessary to keep it conforming with the contract **only for a valid reason stated here**: to comply with law or a decision of a court or authority; to maintain or restore security; to reflect a change in the third-party platforms we integrate with; or to replace a feature with an equivalent or better one. Where a modification negatively and more than minorly affects your access to or use of the Service, we will notify you on a durable medium (such as email) in advance, describing the change and when it takes effect, and, **if you are a consumer, you may terminate the contract free of charge within 30 days of the later of the date the change is made and the date you are informed of it**, with a pro-rata refund of any prepaid Fees for the unused period. This applies whether you are on a paid plan, the Free plan or the private beta.' },
         ],
     },
@@ -35,7 +35,7 @@ exports.TERMS_SECTIONS = [
             { kind: 'ul', items: [
                     { text: 'The beta is **free of charge**. No payment is due, no payment method is collected, and your beta place never converts into a paid plan automatically.' },
                     { text: 'The beta runs for a **fixed period**, stated to you before you accept and confirmed in the message we send you when you accept. Access begins when you accept and **ends automatically on the stated end date**. That end date is the agreed duration of the beta, not a change we make to the contract later.' },
-                    { text: 'When the beta period ends, **your account moves to the Free plan**. Nothing is charged and nothing is deleted. On the Free plan, connecting new social accounts and publishing are unavailable, and the social accounts, post history and analytics from your beta period become inaccessible while you remain on the Free plan. That data is **retained, not deleted**, and becomes available again if you subscribe to a paid plan. You can also ask us to export it at any time, not only when you leave (Section 12).' },
+                    { text: 'When the beta period ends, **your account moves to the Free plan**. Nothing is charged and nothing is deleted. On the Free plan, connecting new social accounts and publishing are unavailable, but the social accounts, post history and analytics from your beta period **remain visible to you in read-only form**. That data is retained, not deleted, and full access returns if you subscribe to a paid plan. You can also ask us to export it at any time, not only when you leave (Section 12).' },
                     { text: 'We will remind you before the beta period ends and tell you when it has ended. Neither message is a condition of the end date taking effect: the end date is already part of these Terms.' },
                     { text: 'You may leave the beta at any time, for any reason, at no cost, by closing your account (Section 12) or by writing to us at {EMAIL}.' },
                     { text: 'Your **statutory right of withdrawal (Section 8a) applies to the beta contract in full**, exactly as it applies to a paid plan. Nothing in this section limits it.' },

package/dist/legal/terms.pl.js

@@ -38,7 +38,7 @@ exports.TERMS_SECTIONS_PL = [
                     { text: 'Zarządzanie plikami multimedialnymi i treściami.' },
                     { text: 'Opcjonalne podłączenie zewnętrznych asystentów AI i narzędzi obsługujących Model Context Protocol (MCP), pozwalające Ci zarządzać planowaniem, publikowaniem i statystykami z poziomu wybranego przez Ciebie narzędzia. Zobacz sekcję 13 oraz naszą {PRIVACY}.' },
                 ] },
-            { kind: 'p', text: 'Usługa jest oferowana w trzech planach: **Free** (na tym planie łączenie nowych kont społecznościowych i publikowanie są niedostępne; jeżeli wcześniej korzystałeś z planu płatnego, wcześniej połączone konta, historia postów i statystyki również stają się niedostępne, dopóki pozostajesz na planie Free, przy czym dane te są zachowywane, a nie usuwane, i stają się ponownie dostępne, jeżeli ponownie wykupisz subskrypcję), **Starter** i **Pro** (Starter i Pro różnią się wyłącznie liczbą kont społecznościowych, które możesz połączyć; wszystkie pozostałe funkcje są identyczne). Aktualne szczegóły planów i ceny są pokazane w aplikacji oraz na naszej stronie z cennikiem.' },
+            { kind: 'p', text: 'Usługa jest oferowana w trzech planach: **Free** (na tym planie łączenie nowych kont społecznościowych i publikowanie są niedostępne; jeżeli wcześniej korzystałeś z planu płatnego albo z miejsca w wersji beta, wcześniej połączone konta, historia postów i statystyki pozostają dla Ciebie widoczne w trybie podglądu. Dane te są zachowywane, a nie usuwane, a pełny dostęp wraca, jeżeli wykupisz subskrypcję), **Starter** i **Pro** (Starter i Pro różnią się wyłącznie liczbą kont społecznościowych, które możesz połączyć; wszystkie pozostałe funkcje są identyczne). Aktualne szczegóły planów i ceny są pokazane w aplikacji oraz na naszej stronie z cennikiem.' },
             { kind: 'p', text: 'Nie wszystkie funkcje opisane w niniejszym Regulaminie są dostępne w każdym planie. Możemy zmodyfikować Usługę w zakresie, w jakim nie jest to niezbędne do zachowania jej zgodności z umową, **wyłącznie z ważnej przyczyny wskazanej tutaj**: aby zapewnić zgodność z prawem albo z orzeczeniem sądu lub decyzją organu; aby utrzymać lub przywrócić bezpieczeństwo; aby odzwierciedlić zmianę w platformach zewnętrznych, z którymi się integrujemy; albo aby zastąpić funkcję funkcją równoważną lub lepszą. Jeżeli modyfikacja negatywnie i w stopniu więcej niż nieznacznym wpływa na Twój dostęp do Usługi lub korzystanie z niej, powiadomimy Cię o tym z wyprzedzeniem na trwałym nośniku (na przykład e-mailem), opisując zmianę oraz termin jej wejścia w życie, a **jeżeli jesteś konsumentem, możesz wypowiedzieć umowę bez ponoszenia kosztów w terminie 30 dni od późniejszej z dat: dnia dokonania zmiany albo dnia poinformowania Cię o niej**, z proporcjonalnym zwrotem Opłat zapłaconych z góry za niewykorzystany okres. Dotyczy to zarówno planu płatnego, jak i planu Free oraz prywatnej wersji beta.' },
         ],
     },
@@ -50,7 +50,7 @@ exports.TERMS_SECTIONS_PL = [
             { kind: 'ul', items: [
                     { text: 'Wersja beta jest **bezpłatna**. Nie jest należna żadna płatność, nie zbieramy metody płatności, a Twoje miejsce w wersji beta nigdy nie przekształca się automatycznie w plan płatny.' },
                     { text: 'Wersja beta trwa przez **okres oznaczony**, podany Ci przed jej przyjęciem i potwierdzony w wiadomości, którą wysyłamy Ci w chwili przyjęcia. Dostęp rozpoczyna się z chwilą przyjęcia i **kończy się automatycznie w podanym dniu zakończenia**. Ten dzień zakończenia to uzgodniony czas trwania wersji beta, a nie zmiana, której dokonujemy w umowie później.' },
-                    { text: 'Gdy okres wersji beta się kończy, **Twoje konto przechodzi na plan Free**. Nic nie zostaje pobrane i nic nie zostaje usunięte. Na planie Free łączenie nowych kont społecznościowych i publikowanie są niedostępne, a konta społecznościowe, historia postów i statystyki z okresu wersji beta stają się niedostępne, dopóki pozostajesz na planie Free. Dane te są **zachowywane, a nie usuwane**, i stają się ponownie dostępne, jeżeli wykupisz plan płatny. Możesz też w każdej chwili poprosić nas o ich wyeksportowanie, nie tylko w chwili odejścia (sekcja 12).' },
+                    { text: 'Gdy okres wersji beta się kończy, **Twoje konto przechodzi na plan Free**. Nic nie zostaje pobrane i nic nie zostaje usunięte. Na planie Free łączenie nowych kont społecznościowych i publikowanie są niedostępne, ale konta społecznościowe, historia postów i statystyki z okresu wersji beta **pozostają dla Ciebie widoczne w trybie podglądu**. Dane te są zachowywane, a nie usuwane, a pełny dostęp wraca, jeżeli wykupisz plan płatny. Możesz też w każdej chwili poprosić nas o ich wyeksportowanie, nie tylko w chwili odejścia (sekcja 12).' },
                     { text: 'Przypomnimy Ci o zbliżającym się końcu okresu wersji beta i poinformujemy Cię, gdy ten okres się zakończy. Żadna z tych wiadomości nie jest warunkiem skuteczności dnia zakończenia: dzień zakończenia jest już częścią niniejszego Regulaminu.' },
                     { text: 'Możesz opuścić wersję beta w każdej chwili, z dowolnego powodu i bez żadnych kosztów, zamykając konto (sekcja 12) lub pisząc do nas na {EMAIL}.' },
                     { text: 'Twoje **ustawowe prawo odstąpienia od umowy (sekcja 8a) ma w pełni zastosowanie do umowy dotyczącej wersji beta**, dokładnie tak samo jak do planu płatnego. Nic w niniejszej sekcji go nie ogranicza.' },

package/dist/types/scheduling/I_SchedulingPost.d.ts

@@ -28,8 +28,28 @@ export declare class SchedulingPlatformTargetDTO {
 export declare class SchedulingMediaItemDTO {
     type: 'image' | 'video';
     url: string;
+    /**
+     * Per-image accessibility text (spec 121 US3). Applied by the vendor on the
+     * platforms that support it (IG feed/FB/Threads/X ≤1000/LinkedIn/Bluesky/
+     * Pinterest ≤500); images only — video items never carry it.
+     */
+    altText?: string;
     constructor(data?: Partial<SchedulingMediaItemDTO>);
 }
+/** TikTok commercial-content disclosure choice (spec 121 US2). Wire values = vendor enum. */
+export type SchedulingTikTokCommercialContentType = 'none' | 'brand_organic' | 'brand_content';
+/**
+ * The compose disclosure state (spec 121, AD2-1302): ONE model on the post,
+ * mapped per-platform at publish time (IG isAiGenerated / TikTok
+ * videoMadeWithAi / YouTube containsSyntheticMedia). Absent-when-off: an unset
+ * flag sends no vendor field at all.
+ */
+export declare class SchedulingPostDisclosureDTO {
+    /** The media contains AI-generated content (media, not captions). */
+    aiGenerated?: boolean;
+    tiktokCommercial?: SchedulingTikTokCommercialContentType;
+    constructor(data?: Partial<SchedulingPostDisclosureDTO>);
+}
 /** Input DTO for creating a new scheduled or immediate post. */
 export declare class SchedulingCreatePostDTO {
     content: string;
@@ -39,6 +59,7 @@ export declare class SchedulingCreatePostDTO {
     mediaItems?: SchedulingMediaItemDTO[];
     platformSpecificData?: Record<string, Record<string, unknown>>;
     tiktokSettings?: Record<string, unknown>;
+    disclosure?: SchedulingPostDisclosureDTO;
     constructor(data?: Partial<SchedulingCreatePostDTO>);
 }
 /** Input DTO for updating an existing post's content or scheduled time. */
@@ -134,6 +155,12 @@ export declare class SchedulingPostDTO {
     likes?: number;
     comments?: number;
     shares?: number;
+    /**
+     * What was SENT at publish time (spec 121) — the persisted disclosure state,
+     * never inferred. Absent on posts created before the feature or with no
+     * disclosure chosen.
+     */
+    disclosure?: SchedulingPostDisclosureDTO;
     constructor(data: SchedulingPostDTO);
 }
 /** Query parameters for listing posts with optional filters. */

package/dist/types/scheduling/I_SchedulingPost.js

@@ -6,7 +6,7 @@
  * and the media items attached to a post.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SchedulingContentCalendarDTO = exports.SchedulingPostListParamsDTO = exports.SchedulingPostDTO = exports.SchedulingPostTargetDTO = exports.SchedulingPostMediaItemDTO = exports.SchedulingUpdatePostDTO = exports.SchedulingCreatePostDTO = exports.SchedulingMediaItemDTO = exports.SchedulingPlatformTargetDTO = exports.SchedulingPostStatus = void 0;
+exports.SchedulingContentCalendarDTO = exports.SchedulingPostListParamsDTO = exports.SchedulingPostDTO = exports.SchedulingPostTargetDTO = exports.SchedulingPostMediaItemDTO = exports.SchedulingUpdatePostDTO = exports.SchedulingCreatePostDTO = exports.SchedulingPostDisclosureDTO = exports.SchedulingMediaItemDTO = exports.SchedulingPlatformTargetDTO = exports.SchedulingPostStatus = void 0;
 // ── Enums ─────────────────────────────────────────────────────────────────────
 var SchedulingPostStatus;
 (function (SchedulingPostStatus) {
@@ -41,9 +41,25 @@ class SchedulingMediaItemDTO {
             return;
         this.type = data.type;
         this.url = data.url;
+        this.altText = data.altText;
     }
 }
 exports.SchedulingMediaItemDTO = SchedulingMediaItemDTO;
+/**
+ * The compose disclosure state (spec 121, AD2-1302): ONE model on the post,
+ * mapped per-platform at publish time (IG isAiGenerated / TikTok
+ * videoMadeWithAi / YouTube containsSyntheticMedia). Absent-when-off: an unset
+ * flag sends no vendor field at all.
+ */
+class SchedulingPostDisclosureDTO {
+    constructor(data) {
+        if (!data)
+            return;
+        this.aiGenerated = data.aiGenerated;
+        this.tiktokCommercial = data.tiktokCommercial;
+    }
+}
+exports.SchedulingPostDisclosureDTO = SchedulingPostDisclosureDTO;
 // ── SchedulingCreatePostDTO ───────────────────────────────────────────────────
 /** Input DTO for creating a new scheduled or immediate post. */
 class SchedulingCreatePostDTO {
@@ -57,6 +73,7 @@ class SchedulingCreatePostDTO {
         this.mediaItems = data.mediaItems;
         this.platformSpecificData = data.platformSpecificData;
         this.tiktokSettings = data.tiktokSettings;
+        this.disclosure = data.disclosure;
     }
 }
 exports.SchedulingCreatePostDTO = SchedulingCreatePostDTO;
@@ -138,6 +155,7 @@ class SchedulingPostDTO {
         this.likes = data.likes;
         this.comments = data.comments;
         this.shares = data.shares;
+        this.disclosure = data.disclosure;
     }
 }
 exports.SchedulingPostDTO = SchedulingPostDTO;

package/package.json

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

package/src/analytics/index.test.ts

@@ -8,8 +8,14 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 
-import { EVENTS, PERSON_PROPS } from "./index";
-import type { EventProperties, EmailEventProperties, TriggerSource, PublishFailureReason } from "./index";
+import { EVENTS, PERSON_PROPS, EMAIL_PROPS } from "./index";
+import type {
+  EventProperties,
+  EmailEventProperties,
+  EmailEventBaseProperties,
+  TriggerSource,
+  PublishFailureReason,
+} from "./index";
 
 const SNAKE_CASE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
 
@@ -66,11 +72,18 @@ const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E]
   [EVENTS.FREE_SKILLS_REQUESTED]: { source: "landing" },
   [EVENTS.ACCOUNT_CONNECT_BLOCKED]: {},
   [EVENTS.MCP_POST_BLOCKED_FREE_TIER]: {},
+  [EVENTS.EMAIL_SENT]: {},
   [EVENTS.EMAIL_DELIVERED]: {},
   [EVENTS.EMAIL_OPENED]: {},
   [EVENTS.EMAIL_CLICKED]: {},
   [EVENTS.EMAIL_BOUNCED]: {},
   [EVENTS.EMAIL_COMPLAINED]: {},
+  [EVENTS.EMAIL_FAILED]: {},
+  [EVENTS.EMAIL_DELIVERY_DELAYED]: {},
+  [EVENTS.EMAIL_UNSUBSCRIBED]: {},
+  [EVENTS.EMAIL_SUPPRESSED]: {},
+  [EVENTS.PLAYBOOK_OPENED]: {},
+  [EVENTS.PLAYBOOK_DOWNLOADED]: {},
   [EVENTS.SIGNED_UP]: { method: "email", role: "creator" },
   [EVENTS.PROFILE_COMPLETED]: { role: "creator" },
   [EVENTS.LOGGED_IN]: {},
@@ -141,10 +154,20 @@ test("the 5 EMAIL_* events are locked and share the EmailEventProperties shape (
     "email_complained",
   ]);
 
-  // The shared shape exposes only email_id / subject / link (all optional).
-  const allowedKeys = ["email_id", "link", "subject"];
+  // Spec 120 WIDENED the shared shape with the EmailEventBaseProperties set
+  // (additive; the AD2-894 trio of keys is unchanged and still allowed).
+  const allowedKeys = [
+    "email_id",
+    "email_stream",
+    "has_attachment",
+    "link",
+    "subject",
+    "trigger_key",
+    "unjoined",
+    "variant",
+  ];
   const sample: EmailEventProperties = { email_id: "re_1", subject: "Welcome", link: "https://ad2.app" };
-  assert.deepEqual(Object.keys(sample).sort(), allowedKeys);
+  assert.deepEqual(Object.keys(sample).sort(), ["email_id", "link", "subject"]);
   for (const event of emailEvents) {
     const witness = EVENT_PROPERTY_WITNESS[event];
     for (const key of Object.keys(witness)) {
@@ -339,3 +362,89 @@ test("POST_PUBLISHED gains optional per-platform properties (AD2-1154 FR-5 lib p
   assert.equal(perPlatform.outcome, "failed");
   assert.equal(perPlatform.reason_class, "media");
 });
+
+// ── spec 120 T002: email program v2 — events + canonical property names ────────
+// The tests assert against contracts/email-event-properties.md (promised =
+// asserted, the 012 lesson). Wire values are FINAL once shipped.
+
+test("120 email-program event wire names are locked", () => {
+  assert.deepEqual(
+    [
+      EVENTS.EMAIL_SENT,
+      EVENTS.EMAIL_FAILED,
+      EVENTS.EMAIL_DELIVERY_DELAYED,
+      EVENTS.EMAIL_UNSUBSCRIBED,
+      EVENTS.EMAIL_SUPPRESSED,
+      EVENTS.PLAYBOOK_OPENED,
+      EVENTS.PLAYBOOK_DOWNLOADED,
+    ],
+    [
+      "email_sent",
+      "email_failed",
+      "email_delivery_delayed",
+      "email_unsubscribed",
+      "email_suppressed",
+      "playbook_opened",
+      "playbook_downloaded",
+    ],
+  );
+});
+
+test("120 EMAIL_PROPS canonical property keys match the T001 contract table", () => {
+  assert.deepEqual(EMAIL_PROPS, {
+    EMAIL_STREAM: "email_stream",
+    TRIGGER_KEY: "trigger_key",
+    VARIANT: "variant",
+    HAS_ATTACHMENT: "has_attachment",
+    EMAIL_ID: "email_id",
+    UNJOINED: "unjoined",
+    SUBJECT: "subject",
+    LINK: "link",
+    BOUNCE_TYPE: "bounce_type",
+    MPP_SUSPECTED: "mpp_suspected",
+    REASON: "reason",
+    MECHANISM: "mechanism",
+    HOURS_SINCE_SEND: "hours_since_send",
+    EDITION_VERSION: "edition_version",
+    FORMAT: "format",
+  });
+});
+
+test("120 email base properties ride every email event; event-specific fields type-check", () => {
+  const base: EmailEventBaseProperties = {
+    email_stream: "nurture",
+    trigger_key: "welcome",
+    variant: "default",
+    has_attachment: false,
+    email_id: "re_1",
+    unjoined: false,
+  };
+  const sent: EventProperties[typeof EVENTS.EMAIL_SENT] = { ...base, subject: "Welcome to ad2app" };
+  const opened: EventProperties[typeof EVENTS.EMAIL_OPENED] = { ...base, mpp_suspected: true };
+  const bounced: EventProperties[typeof EVENTS.EMAIL_BOUNCED] = { ...base, bounce_type: "hard" };
+  const failed: EventProperties[typeof EVENTS.EMAIL_FAILED] = { ...base, reason: "rejected" };
+  const delayed: EventProperties[typeof EVENTS.EMAIL_DELIVERY_DELAYED] = { ...base };
+  const unsub: EventProperties[typeof EVENTS.EMAIL_UNSUBSCRIBED] = {
+    ...base,
+    mechanism: "one_click",
+    hours_since_send: 4,
+  };
+  const suppressed: EventProperties[typeof EVENTS.EMAIL_SUPPRESSED] = { ...base, reason: "hard_bounce" };
+  assert.equal(sent.subject, "Welcome to ad2app");
+  assert.equal(opened.mpp_suspected, true);
+  assert.equal(bounced.bounce_type, "hard");
+  assert.equal(failed.reason, "rejected");
+  assert.equal(delayed.email_stream, "nurture");
+  assert.equal(unsub.mechanism, "one_click");
+  assert.equal(suppressed.reason, "hard_bounce");
+});
+
+test("120 playbook events carry the edition stamp", () => {
+  const opened: EventProperties[typeof EVENTS.PLAYBOOK_OPENED] = { edition_version: "2026.08" };
+  const downloaded: EventProperties[typeof EVENTS.PLAYBOOK_DOWNLOADED] = {
+    edition_version: "2026.08",
+    format: "pdf",
+  };
+  assert.equal(opened.edition_version, "2026.08");
+  assert.equal(downloaded.format, "pdf");
+});

package/src/analytics/index.ts

@@ -20,12 +20,24 @@ export const EVENTS = {
   ACCOUNT_CONNECT_BLOCKED: 'account_connect_blocked', // free user hits the connect wall (AD2-892)
   MCP_POST_BLOCKED_FREE_TIER: 'mcp_post_blocked_free_tier', // free user tries to post in the MCP (AD2-898)
 
-  // Email lifecycle (Resend webhook -> PostHog, AD2-894)
+  // Email lifecycle (Resend webhook -> PostHog, AD2-894; extended by spec 120:
+  // send-time denominator + failure/delay mappings + list-hygiene events, all
+  // carrying the EmailEventBaseProperties set per
+  // specs/120-email-program-v2/contracts/email-event-properties.md)
+  EMAIL_SENT: 'email_sent', // send-time, at the ResendService choke points (the denominator)
   EMAIL_DELIVERED: 'email_delivered',
   EMAIL_OPENED: 'email_opened',
   EMAIL_CLICKED: 'email_clicked',
   EMAIL_BOUNCED: 'email_bounced',
   EMAIL_COMPLAINED: 'email_complained',
+  EMAIL_FAILED: 'email_failed', // webhook email.failed
+  EMAIL_DELIVERY_DELAYED: 'email_delivery_delayed', // webhook email.delivery_delayed
+  EMAIL_UNSUBSCRIBED: 'email_unsubscribed', // one-click header or footer link
+  EMAIL_SUPPRESSED: 'email_suppressed', // suppression-list upsert (hard bounce / complaint)
+
+  // Posting Playbook (spec 120 US2) — hosted artifact engagement
+  PLAYBOOK_OPENED: 'playbook_opened',
+  PLAYBOOK_DOWNLOADED: 'playbook_downloaded',
 
   // Activation (web app)
   SIGNED_UP: 'signed_up', // server-owned (backend, on user creation)
@@ -97,13 +109,62 @@ export const EVENTS = {
 
 export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
 
-/** Shared shape for the Resend email lifecycle events (AD2-894). */
-export interface EmailEventProperties {
-  email_id?: string;
+/** Which email program a send belongs to (spec 120). Wire values — do not rename. */
+export type EmailStream = 'transactional' | 'nurture' | 'broadcast';
+
+/** How an unsubscribe arrived (spec 120). */
+export type UnsubscribeMechanism = 'one_click' | 'footer_link';
+
+/** Why an address entered the suppression list (spec 120). */
+export type SuppressionReason = 'hard_bounce' | 'complaint';
+
+/**
+ * BASE property set every email event carries (spec 120 T001 contract). All
+ * fields are optional AT THE TYPE LEVEL only because legacy tag-less sends
+ * resolve by email lookup and legitimately lack stream/trigger context (they
+ * carry `unjoined: true` instead); the backend tests enforce the full set on
+ * every NEW send. Identity (distinct_id) rides the capture call, not this shape.
+ */
+export interface EmailEventBaseProperties {
+  email_stream?: EmailStream;
+  trigger_key?: string; // e.g. 'welcome', 'winback_canceled', 'consent_copy'
+  variant?: string; // A/B arm id, default 'default'
+  has_attachment?: boolean;
+  email_id?: string; // Resend id
+  unjoined?: boolean; // identity resolution failed — anonymous distinct_id
+}
+
+/**
+ * Shared shape for the Resend email lifecycle events (AD2-894; widened by spec
+ * 120 to carry the base set — additive, wire names unchanged).
+ */
+export interface EmailEventProperties extends EmailEventBaseProperties {
   subject?: string;
   link?: string;
 }
 
+/**
+ * Canonical email event property KEYS (spec 120 T001). Emitters and tests
+ * reference these instead of retyping strings — the single home for the names.
+ */
+export const EMAIL_PROPS = {
+  EMAIL_STREAM: 'email_stream',
+  TRIGGER_KEY: 'trigger_key',
+  VARIANT: 'variant',
+  HAS_ATTACHMENT: 'has_attachment',
+  EMAIL_ID: 'email_id',
+  UNJOINED: 'unjoined',
+  SUBJECT: 'subject',
+  LINK: 'link',
+  BOUNCE_TYPE: 'bounce_type',
+  MPP_SUSPECTED: 'mpp_suspected',
+  REASON: 'reason',
+  MECHANISM: 'mechanism',
+  HOURS_SINCE_SEND: 'hours_since_send',
+  EDITION_VERSION: 'edition_version',
+  FORMAT: 'format',
+} as const;
+
 /**
  * Where a paywall / upgrade / checkout moment was triggered from (080). A named,
  * stable, closed set so the revenue funnel can attribute conversions to their
@@ -161,11 +222,23 @@ export interface EventProperties {
   [EVENTS.FREE_SKILLS_REQUESTED]: { source: string };
   [EVENTS.ACCOUNT_CONNECT_BLOCKED]: { platform?: string };
   [EVENTS.MCP_POST_BLOCKED_FREE_TIER]: { target_count?: number };
+  [EVENTS.EMAIL_SENT]: EmailEventProperties;
   [EVENTS.EMAIL_DELIVERED]: EmailEventProperties;
-  [EVENTS.EMAIL_OPENED]: EmailEventProperties;
+  // mpp_suspected: Apple privacy proxy or <60s after send — EXCLUDED from every
+  // success metric (spec 120 contract).
+  [EVENTS.EMAIL_OPENED]: EmailEventProperties & { mpp_suspected?: boolean };
   [EVENTS.EMAIL_CLICKED]: EmailEventProperties;
-  [EVENTS.EMAIL_BOUNCED]: EmailEventProperties;
+  [EVENTS.EMAIL_BOUNCED]: EmailEventProperties & { bounce_type?: string };
   [EVENTS.EMAIL_COMPLAINED]: EmailEventProperties;
+  [EVENTS.EMAIL_FAILED]: EmailEventProperties & { reason?: string };
+  [EVENTS.EMAIL_DELIVERY_DELAYED]: EmailEventProperties;
+  [EVENTS.EMAIL_UNSUBSCRIBED]: EmailEventProperties & {
+    mechanism?: UnsubscribeMechanism;
+    hours_since_send?: number;
+  };
+  [EVENTS.EMAIL_SUPPRESSED]: EmailEventProperties & { reason?: SuppressionReason };
+  [EVENTS.PLAYBOOK_OPENED]: { edition_version?: string };
+  [EVENTS.PLAYBOOK_DOWNLOADED]: { edition_version?: string; format?: string };
   [EVENTS.SIGNED_UP]: { method: 'email' | 'google'; role: string };
   [EVENTS.PROFILE_COMPLETED]: { role: string };
   [EVENTS.LOGGED_IN]: { method?: 'email' | 'google' };
@@ -340,12 +413,32 @@ type Expect<T extends true> = T;
 // property shape, no orphan or typo'd key (1:1).
 type _EventsAreOneToOneWithProperties = Expect<Equal<EventName, keyof EventProperties>>;
 
-// AC3: the five EMAIL_* lifecycle events all carry the shared EmailEventProperties
-// shape (the Resend -> PostHog bridge contract, AD2-894).
+// AC3 (AD2-894, widened by spec 120): every EMAIL_* lifecycle event carries the
+// shared EmailEventProperties shape; opened/bounced/failed/unsubscribed/
+// suppressed layer their event-specific fields ON TOP of it, never instead of it.
 type EmailLifecycleEvent =
+  | (typeof EVENTS)['EMAIL_SENT']
   | (typeof EVENTS)['EMAIL_DELIVERED']
   | (typeof EVENTS)['EMAIL_OPENED']
   | (typeof EVENTS)['EMAIL_CLICKED']
   | (typeof EVENTS)['EMAIL_BOUNCED']
-  | (typeof EVENTS)['EMAIL_COMPLAINED'];
-type _EmailEventsUseSharedShape = Expect<Equal<EventProperties[EmailLifecycleEvent], EmailEventProperties>>;
+  | (typeof EVENTS)['EMAIL_COMPLAINED']
+  | (typeof EVENTS)['EMAIL_FAILED']
+  | (typeof EVENTS)['EMAIL_DELIVERY_DELAYED']
+  | (typeof EVENTS)['EMAIL_UNSUBSCRIBED']
+  | (typeof EVENTS)['EMAIL_SUPPRESSED'];
+type _EmailEventsCarryTheSharedShape = Expect<
+  EventProperties[EmailLifecycleEvent] extends EmailEventProperties ? true : false
+>;
+// The unchanged AD2-894 trio still equals the shared shape exactly.
+type _UnwidenedEmailEventsUseSharedShapeExactly = Expect<
+  Equal<
+    EventProperties[
+      | (typeof EVENTS)['EMAIL_SENT']
+      | (typeof EVENTS)['EMAIL_DELIVERED']
+      | (typeof EVENTS)['EMAIL_CLICKED']
+      | (typeof EVENTS)['EMAIL_COMPLAINED']
+      | (typeof EVENTS)['EMAIL_DELIVERY_DELAYED']],
+    EmailEventProperties
+  >
+>;

package/src/api/apiDriver.test.ts

@@ -10,7 +10,7 @@ import { ApiError, apiDriver, configureApiDriver, fetchCall } from "./apiDriver"
 
 configureApiDriver({ apiUrl: "https://default.test" });
 
-let calls: { url: string }[] = [];
+let calls: { url: string; init?: RequestInit }[] = [];
 let body: string | null = JSON.stringify({ ok: true });
 let status = 200;
 const realFetch = globalThis.fetch;
@@ -20,8 +20,8 @@ beforeEach(() => {
   body = JSON.stringify({ ok: true });
   status = 200;
   // Fresh Response per call — a body can only be read once.
-  globalThis.fetch = (async (url: unknown) => {
-    calls.push({ url: String(url) });
+  globalThis.fetch = (async (url: unknown, init?: RequestInit) => {
+    calls.push({ url: String(url), init });
     return new Response(body, { status });
   }) as typeof fetch;
 });
@@ -126,3 +126,26 @@ test("an empty error body still carries the status, not just a generic message",
   assert.equal(err.status, 502);
   assert.match(err.message, /502/);
 });
+
+/**
+ * AD2-1297: the frontend needs the backend's HttpOnly session cookie to ride
+ * along on every request, which `fetch` only does when explicitly told to via
+ * `credentials`. Regression: before this, `DriverConfig` had no `credentials`
+ * field at all, so there was no way for a consumer to opt in — the cookie
+ * would silently never be sent and every request would 401.
+ */
+test("configureApiDriver's credentials option is forwarded to fetch", async () => {
+  configureApiDriver({ apiUrl: "https://default.test", credentials: "include" });
+  try {
+    await fetchCall({ path: "x", method: "get" });
+    assert.equal(calls[0]?.init?.credentials, "include");
+  } finally {
+    // Restore the module-level CONFIG other tests in this file rely on.
+    configureApiDriver({ apiUrl: "https://default.test" });
+  }
+});
+
+test("credentials is omitted (not forced to a value) when the driver isn't configured with one", async () => {
+  await fetchCall({ path: "x", method: "get" });
+  assert.equal(calls[0]?.init?.credentials, undefined);
+});

package/src/api/apiDriver.ts

@@ -9,6 +9,14 @@ type HttpMethod = "get" | "post" | "put" | "PATCH" | "delete";
 interface DriverConfig {
   apiUrl: string;
   getHeaders?: () => HeadersInit;
+  /**
+   * Forwarded verbatim to `fetch`'s own `credentials` option on every call
+   * (AD2-1297: the frontend needs `'include'` so the backend's HttpOnly
+   * session cookie actually rides along on a cross-subdomain request).
+   * Undefined preserves the previous, unconfigured behavior (the browser's
+   * `fetch` default, `'same-origin'`) for any other consumer of this driver.
+   */
+  credentials?: RequestCredentials;
 }
 
 /**
@@ -77,6 +85,7 @@ export async function fetchCall<T, Q>(args: FetchCallArgs<Q>): Promise<T> {
   const init: RequestInit = {
     method,
     headers,
+    ...(CONFIG?.credentials ? { credentials: CONFIG.credentials } : {}),
   };
 
   if (params?.body) {

package/src/brand/v5-accent-tokens.test.ts

@@ -0,0 +1,145 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+
+// spec 124 US2 (playbook visual restyle): the landing's v5 accent ramp joins the
+// canonical brand source so no consumer ever re-types a hex. Values must equal
+// ad2app-landing globals.css EXACTLY — this fixture IS those values, copied once;
+// if the landing ramp ever changes, both move together through brand.mjs.
+//
+// This hardcoded snapshot is a FLOOR, not the whole story: it only catches brand.mjs
+// drifting from what was true when the fixture was copied. The tests further down
+// additionally read ad2app-landing/src/app/globals.css directly (when that sibling
+// repo is checked out) so real drift between the two repos actually fails CI/local
+// runs, not just drift from a frozen copy. brand.mjs is plain ESM with no build step,
+// so `tsx --test` (this repo's `npm test`) imports it as-is; the resolver finds the
+// hand-maintained brand.d.ts alongside it, so no `@ts-ignore` is needed here.
+import { color } from '../../brand/brand.mjs';
+
+const LANDING_V5 = {
+	magenta: '#ff2d78',
+	magentaHi: '#ff5c95',
+	magentaLo: '#e0175f',
+	magentaTint: '#fff0f5',
+	violet: '#7c3aed',
+	violetHi: '#9d6ff5',
+	violetLo: '#6323d0',
+	lime: '#d9f24b',
+	limeHi: '#e9fa74',
+	limeLo: '#becc25',
+	aqua: '#4dd6f5',
+	aquaHi: '#7ce4fa',
+	aquaLo: '#22b8dd',
+	borderStrong: '#8e8e9a',
+};
+
+test('brand.mjs carries the v5 accent group with the exact landing values', () => {
+	assert.ok(color.v5, 'color.v5 accent group missing from brand.mjs');
+	assert.deepEqual(color.v5, LANDING_V5);
+});
+
+test('the pre-existing v5 base tokens still match the landing', () => {
+	assert.equal(color.surfaceMuted, '#f0f1fa');
+	assert.equal(color.primaryTint, '#eaf0ff');
+	assert.equal(color.primary, '#0042ff');
+});
+
+// ---- Live cross-repo check against ad2app-landing (when checked out as a sibling) ----
+//
+// In local dev both repos live side by side under the same parent directory
+// (…/ad2app/ad2app-lib and …/ad2app/ad2app-landing — this is how Maciej reviews), so we
+// can read the actual source of truth instead of trusting a copy-pasted fixture. CI and
+// npm-published contexts won't have the sibling checked out, so that case is skipped
+// with a clear note rather than failed — the hardcoded assertions above still run and
+// still protect those contexts, just against a snapshot instead of the live file.
+const LANDING_GLOBALS_CSS = path.resolve(__dirname, '../../../ad2app-landing/src/app/globals.css');
+
+/** Extracts `--custom-property: #hex;` declarations from a CSS file's text. */
+function readCssHexTokens(cssText: string): Record<string, string> {
+	const tokens: Record<string, string> = {};
+	const re = /--([a-z0-9-]+):\s*(#[0-9a-fA-F]{3,8})\s*[;]/g;
+	let match: RegExpExecArray | null;
+	while ((match = re.exec(cssText)) !== null) {
+		tokens[match[1]] = match[2];
+	}
+	return tokens;
+}
+
+// ad2app-landing CSS custom property name -> brand.mjs color.v5 key
+const V5_CSS_VAR_TO_KEY: Record<string, keyof typeof LANDING_V5> = {
+	magenta: 'magenta',
+	'magenta-hi': 'magentaHi',
+	'magenta-lo': 'magentaLo',
+	'magenta-tint': 'magentaTint',
+	violet: 'violet',
+	'violet-hi': 'violetHi',
+	'violet-lo': 'violetLo',
+	lime: 'lime',
+	'lime-hi': 'limeHi',
+	'lime-lo': 'limeLo',
+	aqua: 'aqua',
+	'aqua-hi': 'aquaHi',
+	'aqua-lo': 'aquaLo',
+	'border-strong': 'borderStrong',
+};
+
+// ad2app-landing CSS custom property name -> brand.mjs color.<key>
+const BASE_CSS_VAR_TO_KEY: Record<string, 'surfaceMuted' | 'primaryTint' | 'primary'> = {
+	'surface-muted': 'surfaceMuted',
+	'primary-tint': 'primaryTint',
+	primary: 'primary',
+};
+
+test('brand.mjs v5 accent group matches the LIVE ad2app-landing globals.css', (t) => {
+	if (!fs.existsSync(LANDING_GLOBALS_CSS)) {
+		console.log(
+			`[v5-accent-tokens.test] ad2app-landing sibling repo not found at ${LANDING_GLOBALS_CSS} — ` +
+				'skipping the live cross-repo check (expected in CI / outside a local sibling checkout). ' +
+				'The hardcoded LANDING_V5 snapshot above still ran as a floor.',
+		);
+		t.skip('ad2app-landing not checked out as a sibling repo');
+		return;
+	}
+
+	const cssTokens = readCssHexTokens(fs.readFileSync(LANDING_GLOBALS_CSS, 'utf8'));
+	const liveV5 = {} as typeof LANDING_V5;
+	for (const [cssVar, v5Key] of Object.entries(V5_CSS_VAR_TO_KEY)) {
+		assert.ok(
+			cssTokens[cssVar],
+			`--${cssVar} not found in ad2app-landing globals.css (renamed or removed?) at ${LANDING_GLOBALS_CSS}`,
+		);
+		liveV5[v5Key] = cssTokens[cssVar];
+	}
+
+	assert.deepEqual(
+		color.v5,
+		liveV5,
+		'brand.mjs color.v5 has drifted from the live ad2app-landing globals.css — update brand.mjs (and the LANDING_V5 fixture above) to match',
+	);
+});
+
+test('brand.mjs base tokens match the LIVE ad2app-landing globals.css', (t) => {
+	if (!fs.existsSync(LANDING_GLOBALS_CSS)) {
+		console.log(
+			`[v5-accent-tokens.test] ad2app-landing sibling repo not found at ${LANDING_GLOBALS_CSS} — ` +
+				'skipping the live cross-repo check (expected in CI / outside a local sibling checkout). ' +
+				'The hardcoded base-token assertions above still ran as a floor.',
+		);
+		t.skip('ad2app-landing not checked out as a sibling repo');
+		return;
+	}
+
+	const cssTokens = readCssHexTokens(fs.readFileSync(LANDING_GLOBALS_CSS, 'utf8'));
+	for (const [cssVar, colorKey] of Object.entries(BASE_CSS_VAR_TO_KEY)) {
+		assert.ok(
+			cssTokens[cssVar],
+			`--${cssVar} not found in ad2app-landing globals.css (renamed or removed?) at ${LANDING_GLOBALS_CSS}`,
+		);
+		assert.equal(
+			color[colorKey],
+			cssTokens[cssVar],
+			`brand.mjs color.${colorKey} has drifted from the live ad2app-landing --${cssVar}`,
+		);
+	}
+});

package/src/legal/terms.pl.ts

@@ -37,7 +37,7 @@ export const TERMS_SECTIONS_PL: LegalSection[] = [
         { text: 'Zarządzanie plikami multimedialnymi i treściami.' },
         { text: 'Opcjonalne podłączenie zewnętrznych asystentów AI i narzędzi obsługujących Model Context Protocol (MCP), pozwalające Ci zarządzać planowaniem, publikowaniem i statystykami z poziomu wybranego przez Ciebie narzędzia. Zobacz sekcję 13 oraz naszą {PRIVACY}.' },
       ] },
-      { kind: 'p', text: 'Usługa jest oferowana w trzech planach: **Free** (na tym planie łączenie nowych kont społecznościowych i publikowanie są niedostępne; jeżeli wcześniej korzystałeś z planu płatnego, wcześniej połączone konta, historia postów i statystyki również stają się niedostępne, dopóki pozostajesz na planie Free, przy czym dane te są zachowywane, a nie usuwane, i stają się ponownie dostępne, jeżeli ponownie wykupisz subskrypcję), **Starter** i **Pro** (Starter i Pro różnią się wyłącznie liczbą kont społecznościowych, które możesz połączyć; wszystkie pozostałe funkcje są identyczne). Aktualne szczegóły planów i ceny są pokazane w aplikacji oraz na naszej stronie z cennikiem.' },
+      { kind: 'p', text: 'Usługa jest oferowana w trzech planach: **Free** (na tym planie łączenie nowych kont społecznościowych i publikowanie są niedostępne; jeżeli wcześniej korzystałeś z planu płatnego albo z miejsca w wersji beta, wcześniej połączone konta, historia postów i statystyki pozostają dla Ciebie widoczne w trybie podglądu. Dane te są zachowywane, a nie usuwane, a pełny dostęp wraca, jeżeli wykupisz subskrypcję), **Starter** i **Pro** (Starter i Pro różnią się wyłącznie liczbą kont społecznościowych, które możesz połączyć; wszystkie pozostałe funkcje są identyczne). Aktualne szczegóły planów i ceny są pokazane w aplikacji oraz na naszej stronie z cennikiem.' },
       { kind: 'p', text: 'Nie wszystkie funkcje opisane w niniejszym Regulaminie są dostępne w każdym planie. Możemy zmodyfikować Usługę w zakresie, w jakim nie jest to niezbędne do zachowania jej zgodności z umową, **wyłącznie z ważnej przyczyny wskazanej tutaj**: aby zapewnić zgodność z prawem albo z orzeczeniem sądu lub decyzją organu; aby utrzymać lub przywrócić bezpieczeństwo; aby odzwierciedlić zmianę w platformach zewnętrznych, z którymi się integrujemy; albo aby zastąpić funkcję funkcją równoważną lub lepszą. Jeżeli modyfikacja negatywnie i w stopniu więcej niż nieznacznym wpływa na Twój dostęp do Usługi lub korzystanie z niej, powiadomimy Cię o tym z wyprzedzeniem na trwałym nośniku (na przykład e-mailem), opisując zmianę oraz termin jej wejścia w życie, a **jeżeli jesteś konsumentem, możesz wypowiedzieć umowę bez ponoszenia kosztów w terminie 30 dni od późniejszej z dat: dnia dokonania zmiany albo dnia poinformowania Cię o niej**, z proporcjonalnym zwrotem Opłat zapłaconych z góry za niewykorzystany okres. Dotyczy to zarówno planu płatnego, jak i planu Free oraz prywatnej wersji beta.' },
     ],
   },
@@ -49,7 +49,7 @@ export const TERMS_SECTIONS_PL: LegalSection[] = [
       { kind: 'ul', items: [
         { text: 'Wersja beta jest **bezpłatna**. Nie jest należna żadna płatność, nie zbieramy metody płatności, a Twoje miejsce w wersji beta nigdy nie przekształca się automatycznie w plan płatny.' },
         { text: 'Wersja beta trwa przez **okres oznaczony**, podany Ci przed jej przyjęciem i potwierdzony w wiadomości, którą wysyłamy Ci w chwili przyjęcia. Dostęp rozpoczyna się z chwilą przyjęcia i **kończy się automatycznie w podanym dniu zakończenia**. Ten dzień zakończenia to uzgodniony czas trwania wersji beta, a nie zmiana, której dokonujemy w umowie później.' },
-        { text: 'Gdy okres wersji beta się kończy, **Twoje konto przechodzi na plan Free**. Nic nie zostaje pobrane i nic nie zostaje usunięte. Na planie Free łączenie nowych kont społecznościowych i publikowanie są niedostępne, a konta społecznościowe, historia postów i statystyki z okresu wersji beta stają się niedostępne, dopóki pozostajesz na planie Free. Dane te są **zachowywane, a nie usuwane**, i stają się ponownie dostępne, jeżeli wykupisz plan płatny. Możesz też w każdej chwili poprosić nas o ich wyeksportowanie, nie tylko w chwili odejścia (sekcja 12).' },
+        { text: 'Gdy okres wersji beta się kończy, **Twoje konto przechodzi na plan Free**. Nic nie zostaje pobrane i nic nie zostaje usunięte. Na planie Free łączenie nowych kont społecznościowych i publikowanie są niedostępne, ale konta społecznościowe, historia postów i statystyki z okresu wersji beta **pozostają dla Ciebie widoczne w trybie podglądu**. Dane te są zachowywane, a nie usuwane, a pełny dostęp wraca, jeżeli wykupisz plan płatny. Możesz też w każdej chwili poprosić nas o ich wyeksportowanie, nie tylko w chwili odejścia (sekcja 12).' },
         { text: 'Przypomnimy Ci o zbliżającym się końcu okresu wersji beta i poinformujemy Cię, gdy ten okres się zakończy. Żadna z tych wiadomości nie jest warunkiem skuteczności dnia zakończenia: dzień zakończenia jest już częścią niniejszego Regulaminu.' },
         { text: 'Możesz opuścić wersję beta w każdej chwili, z dowolnego powodu i bez żadnych kosztów, zamykając konto (sekcja 12) lub pisząc do nas na {EMAIL}.' },
         { text: 'Twoje **ustawowe prawo odstąpienia od umowy (sekcja 8a) ma w pełni zastosowanie do umowy dotyczącej wersji beta**, dokładnie tak samo jak do planu płatnego. Nic w niniejszej sekcji go nie ogranicza.' },

package/src/legal/terms.ts

@@ -22,7 +22,7 @@ export const TERMS_SECTIONS: LegalSection[] = [
         { text: 'Media and content file management.' },
         { text: 'Optional connection of third-party AI assistants and tools that support the Model Context Protocol (MCP), letting you manage scheduling, posting, and analytics from within a tool of your choice. See Section 13 and our {PRIVACY}.' },
       ] },
-      { kind: 'p', text: 'The Service is offered on three plans: **Free** (connecting new social accounts and publishing are not available on this plan; if you previously had a paid plan, your previously-connected accounts, post history, and analytics also become inaccessible while you are on the Free plan. That data is retained, not deleted, and becomes available again if you resubscribe), **Starter**, and **Pro** (Starter and Pro differ only in how many social accounts you may connect; all other features are identical). Current plan details and pricing are shown in the app and on our pricing page.' },
+      { kind: 'p', text: 'The Service is offered on three plans: **Free** (connecting new social accounts and publishing are not available on this plan; if you previously had a paid plan or a beta place, your previously-connected accounts, post history, and analytics remain visible to you in read-only form. That data is retained, not deleted, and full access returns if you subscribe), **Starter**, and **Pro** (Starter and Pro differ only in how many social accounts you may connect; all other features are identical). Current plan details and pricing are shown in the app and on our pricing page.' },
       { kind: 'p', text: 'Not all features described in these Terms are available in every plan. We may modify the Service where this is not necessary to keep it conforming with the contract **only for a valid reason stated here**: to comply with law or a decision of a court or authority; to maintain or restore security; to reflect a change in the third-party platforms we integrate with; or to replace a feature with an equivalent or better one. Where a modification negatively and more than minorly affects your access to or use of the Service, we will notify you on a durable medium (such as email) in advance, describing the change and when it takes effect, and, **if you are a consumer, you may terminate the contract free of charge within 30 days of the later of the date the change is made and the date you are informed of it**, with a pro-rata refund of any prepaid Fees for the unused period. This applies whether you are on a paid plan, the Free plan or the private beta.' },
     ],
   },
@@ -34,7 +34,7 @@ export const TERMS_SECTIONS: LegalSection[] = [
       { kind: 'ul', items: [
         { text: 'The beta is **free of charge**. No payment is due, no payment method is collected, and your beta place never converts into a paid plan automatically.' },
         { text: 'The beta runs for a **fixed period**, stated to you before you accept and confirmed in the message we send you when you accept. Access begins when you accept and **ends automatically on the stated end date**. That end date is the agreed duration of the beta, not a change we make to the contract later.' },
-        { text: 'When the beta period ends, **your account moves to the Free plan**. Nothing is charged and nothing is deleted. On the Free plan, connecting new social accounts and publishing are unavailable, and the social accounts, post history and analytics from your beta period become inaccessible while you remain on the Free plan. That data is **retained, not deleted**, and becomes available again if you subscribe to a paid plan. You can also ask us to export it at any time, not only when you leave (Section 12).' },
+        { text: 'When the beta period ends, **your account moves to the Free plan**. Nothing is charged and nothing is deleted. On the Free plan, connecting new social accounts and publishing are unavailable, but the social accounts, post history and analytics from your beta period **remain visible to you in read-only form**. That data is retained, not deleted, and full access returns if you subscribe to a paid plan. You can also ask us to export it at any time, not only when you leave (Section 12).' },
         { text: 'We will remind you before the beta period ends and tell you when it has ended. Neither message is a condition of the end date taking effect: the end date is already part of these Terms.' },
         { text: 'You may leave the beta at any time, for any reason, at no cost, by closing your account (Section 12) or by writing to us at {EMAIL}.' },
         { text: 'Your **statutory right of withdrawal (Section 8a) applies to the beta contract in full**, exactly as it applies to a paid plan. Nothing in this section limits it.' },

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

@@ -126,3 +126,19 @@ test('SchedulingPostDTO platformRetryCounts is absent by default (backward compa
   const post = basePost();
   assert.equal(post.platformRetryCounts, undefined);
 });
+
+// ── spec 121: disclosure + per-image alt text ride the create DTO ─────────────
+test('121: disclosure + altText carry through the DTO constructors (absent when unset)', () => {
+  const { SchedulingCreatePostDTO, SchedulingMediaItemDTO, SchedulingPostDisclosureDTO } = require('./I_SchedulingPost');
+  const dto = new SchedulingCreatePostDTO({
+    content: 'hello',
+    platforms: [{ platform: 'instagram', accountId: 'a1' }],
+    mediaItems: [new SchedulingMediaItemDTO({ type: 'image', url: 'https://x/1.jpg', altText: 'A creator at a desk' })],
+    disclosure: new SchedulingPostDisclosureDTO({ aiGenerated: true, tiktokCommercial: 'brand_organic' }),
+  });
+  assert.equal(dto.disclosure.aiGenerated, true);
+  assert.equal(dto.disclosure.tiktokCommercial, 'brand_organic');
+  assert.equal(dto.mediaItems[0].altText, 'A creator at a desk');
+  const bare = new SchedulingCreatePostDTO({ content: 'x', platforms: [] });
+  assert.equal(bare.disclosure, undefined);
+});

package/src/types/scheduling/I_SchedulingPost.ts

@@ -53,11 +53,44 @@ export class SchedulingPlatformTargetDTO {
 export class SchedulingMediaItemDTO {
   type: 'image' | 'video';
   url: string;
+  /**
+   * Per-image accessibility text (spec 121 US3). Applied by the vendor on the
+   * platforms that support it (IG feed/FB/Threads/X ≤1000/LinkedIn/Bluesky/
+   * Pinterest ≤500); images only — video items never carry it.
+   */
+  altText?: string;
 
   constructor(data?: Partial<SchedulingMediaItemDTO>) {
     if (!data) return;
     this.type = data.type;
     this.url = data.url;
+    this.altText = data.altText;
+  }
+}
+
+// ── SchedulingPostDisclosureDTO ───────────────────────────────────────────────
+
+/** TikTok commercial-content disclosure choice (spec 121 US2). Wire values = vendor enum. */
+export type SchedulingTikTokCommercialContentType =
+  | 'none'
+  | 'brand_organic'
+  | 'brand_content';
+
+/**
+ * The compose disclosure state (spec 121, AD2-1302): ONE model on the post,
+ * mapped per-platform at publish time (IG isAiGenerated / TikTok
+ * videoMadeWithAi / YouTube containsSyntheticMedia). Absent-when-off: an unset
+ * flag sends no vendor field at all.
+ */
+export class SchedulingPostDisclosureDTO {
+  /** The media contains AI-generated content (media, not captions). */
+  aiGenerated?: boolean;
+  tiktokCommercial?: SchedulingTikTokCommercialContentType;
+
+  constructor(data?: Partial<SchedulingPostDisclosureDTO>) {
+    if (!data) return;
+    this.aiGenerated = data.aiGenerated;
+    this.tiktokCommercial = data.tiktokCommercial;
   }
 }
 
@@ -72,6 +105,7 @@ export class SchedulingCreatePostDTO {
   mediaItems?: SchedulingMediaItemDTO[];
   platformSpecificData?: Record<string, Record<string, unknown>>;
   tiktokSettings?: Record<string, unknown>;
+  disclosure?: SchedulingPostDisclosureDTO;
 
   constructor(data?: Partial<SchedulingCreatePostDTO>) {
     if (!data) return;
@@ -82,6 +116,7 @@ export class SchedulingCreatePostDTO {
     this.mediaItems = data.mediaItems;
     this.platformSpecificData = data.platformSpecificData;
     this.tiktokSettings = data.tiktokSettings;
+    this.disclosure = data.disclosure;
   }
 }
 
@@ -208,6 +243,12 @@ export class SchedulingPostDTO {
   likes?: number;
   comments?: number;
   shares?: number;
+  /**
+   * What was SENT at publish time (spec 121) — the persisted disclosure state,
+   * never inferred. Absent on posts created before the feature or with no
+   * disclosure chosen.
+   */
+  disclosure?: SchedulingPostDisclosureDTO;
 
   constructor(data: SchedulingPostDTO) {
     this.id = data.id;
@@ -232,6 +273,7 @@ export class SchedulingPostDTO {
     this.likes = data.likes;
     this.comments = data.comments;
     this.shares = data.shares;
+    this.disclosure = data.disclosure;
   }
 }