ad2app-lib 1.9.3 → 1.11.0

package/.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: test
+
+on:
+  pull_request:
+  push:
+    branches: [master, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - name: typecheck
+        run: npx tsc --noEmit
+      - name: test
+        run: npm test

package/brand/brand.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Type declarations for `brand/brand.mjs` — the canonical ad2app brand source.
+ *
+ * Hand-maintained to mirror brand.mjs (plain ESM, imported buildless by the
+ * node scripts). Published via the `./brand` export so TS consumers (frontend,
+ * landing) can import these tokens + facts with types. Keep in sync with brand.mjs.
+ */
+
+export interface ColorTokens {
+	bg: string;
+	surface: string;
+	surfaceMuted: string;
+	text: string;
+	muted: string;
+	border: string;
+	primary: string;
+	primaryHover: string;
+	primaryTint: string;
+	primarySolidHover: string;
+	onPrimary: string;
+	success: string;
+	successText: string;
+	error: string;
+	/** The PRODUCT blue, deliberately distinct from the marketing primary. */
+	productPrimary: string;
+}
+export const color: ColorTokens;
+
+export interface FontTokens {
+	family: string;
+	fallback: string;
+}
+export const font: FontTokens;
+
+export interface CanvasSize {
+	width: number;
+	height: number;
+}
+export interface SizeTokens {
+	story: CanvasSize;
+	portrait: CanvasSize;
+	square: CanvasSize;
+	link: CanvasSize;
+	xLandscape: CanvasSize;
+	xPortrait: CanvasSize;
+}
+export const size: SizeTokens;
+
+export interface RadiusTokens {
+	card: number;
+	pill: number;
+	chip: number;
+}
+export const radius: RadiusTokens;
+
+export interface AestheticTokens {
+	feel: string[];
+	avoid: string[];
+	prefer: string[];
+	bannedCliches: string[];
+}
+export const aesthetic: AestheticTokens;
+
+/** A connectable social platform's canonical brand identity. */
+export interface PlatformBrand {
+	slug: string;
+	name: string;
+	/** Official brand color (hex). */
+	color: string;
+	/** On-dark override for marks that are near-black (invert to white in dark mode). */
+	darkColor?: string;
+}
+/** The connectable platforms, canonical order (largest-audience first). */
+export const PLATFORMS: PlatformBrand[];
+export const PLATFORM_COUNT: number;
+
+export interface PlanPricing {
+	usd: number;
+	note?: string;
+	accounts?: number;
+}
+export interface PricingTokens {
+	free: PlanPricing;
+	starter: PlanPricing;
+	pro: PlanPricing;
+}
+export const PRICING: PricingTokens;
+
+export const ENTITY_SENTENCE: string;

package/brand/brand.mjs

@@ -0,0 +1,91 @@
+// ad2app canonical brand source: design tokens + facts. Plain ESM on purpose, so the
+// on-device node scripts (graphics renderer, the marketing claims gate) import it directly
+// today with no build and no publish. The landing + product join via a typed, published
+// export under spec 009-design-system-hardening. Change a token or a fact HERE, once.
+// Values currently mirror ad2app-landing globals.css + the marketing positioning. _(scope: rule)_
+
+// ---- Design tokens ----
+export const color = {
+  bg: '#f7f8ff',
+  surface: '#ffffff',
+  surfaceMuted: '#f0f1fa',
+  text: '#1a1a1a',
+  muted: '#5f6672',
+  border: '#d0d0d8',
+  primary: '#0042ff',         // marketing primary
+  primaryHover: '#0036d6',
+  primaryTint: '#eaf0ff',
+  primarySolidHover: '#3366ff',
+  onPrimary: '#ffffff',
+  success: '#34c759',
+  successText: '#0f7a33',
+  error: '#ff3b30',
+  productPrimary: '#0000ff',   // the PRODUCT blue, deliberately distinct from marketing #0042ff
+};
+
+export const font = {
+  family: 'Funnel Sans',
+  fallback: '-apple-system, Segoe UI, Roboto, Helvetica Neue, sans-serif',
+};
+
+// Social canvas sizes (px), the canonical ad set.
+export const size = {
+  story: { width: 1080, height: 1920 },     // 9:16 TikTok/Reels/Shorts/Stories
+  portrait: { width: 1080, height: 1350 },  // 4:5 IG/FB feed
+  square: { width: 1080, height: 1080 },    // 1:1 Meta/X/Reddit feed
+  link: { width: 1200, height: 628 },       // 1.91:1 link/display
+  xLandscape: { width: 1200, height: 675 }, // X single image
+  xPortrait: { width: 1080, height: 1350 }, // back-compat alias of portrait
+};
+
+export const radius = { card: 28, pill: 999, chip: 12 };
+
+// Visual identity, machine-readable. The PRINCIPLES + art direction live in
+// ad2app-graphics/data/design-trends.md (the design source); this is the encoding the
+// graphics generate/critique loop consumes.
+export const aesthetic = {
+  // Look doctrine = ad2app-graphics/data/design-trends.md (4 directions: human/life-given-back [default],
+  // type-led minimalism, soft-3D, minimaximalism). North star: WHITE / light, calm, warm, intentional —
+  // NEVER the dark premium-dev/attention-economy look. Brand blue #0042ff is the HERO accent; oversized
+  // Funnel Sans type. Audience = creators + young founders, but the bar is warm + scroll-stopping, not "Linear".
+  feel: ['calm', 'intentional', 'warm', 'human', 'confident', 'spacious', 'crafted', 'present'],
+  avoid: ['dark / moody / premium-dev sterility (Linear-tier coldness) as a default', 'frantic, attention-economy energy', 'cluttered', 'growth-hack energy', 'busy collage', 'stock-photo gloss', 'golden-hour brunch / wellness-stock lifestyle', 'timid small centered type on an empty field'],
+  // Hero = confident oversized type + #0042ff on a calm light ground. Real product UI is fine and trust-building;
+  // invented metric/dashboard chrome is banned (use a real screenshot). Human shots show the life given back.
+  prefer: ['WHITE / light calm ground (#f7f8ff / #ffffff), not dark', 'confident OVERSIZED Funnel Sans type as the hero', 'exact brand blue #0042ff as the HERO accent — highlight blocks, blue fields — never navy or grey', 'minimaximalism: a sleek minimal base + a few vibrant, oversized accents', 'the life given back for human shots (closed laptop, free evening, off the phone)', 'generous, composed negative space', 'one idea per asset'],
+  bannedCliches: ['network nodes', 'circuit lines / digital-tech glow', 'floating app icons', 'AI brain', 'fake dashboards', 'invented metric chrome', 'emoji spam', 'dashes', 'dark moody tech sterility'],
+};
+
+// ---- Facts (stable, machine-consumable) ----
+// The 10 connectable platforms, canonical order (largest-audience first).
+// `color` is each platform's official brand spec; `darkColor` is the on-dark
+// override for marks that are near-black (they invert to white in dark mode).
+// These are the single source for per-platform brand color across product +
+// landing (the typed published export joins them under spec 009).
+export const PLATFORMS = [
+  { slug: 'instagram', name: 'Instagram', color: '#E1306C' },
+  { slug: 'tiktok', name: 'TikTok', color: '#000000', darkColor: '#ffffff' },
+  { slug: 'youtube', name: 'YouTube', color: '#FF0000' },
+  { slug: 'x-twitter', name: 'X (Twitter)', color: '#000000', darkColor: '#ffffff' },
+  { slug: 'facebook', name: 'Facebook', color: '#1877F2' },
+  { slug: 'linkedin', name: 'LinkedIn', color: '#0A66C2' },
+  { slug: 'threads', name: 'Threads', color: '#000000', darkColor: '#ffffff' },
+  { slug: 'pinterest', name: 'Pinterest', color: '#E60023' },
+  { slug: 'reddit', name: 'Reddit', color: '#FF4500' },
+  { slug: 'bluesky', name: 'Bluesky', color: '#0085FF' },
+];
+export const PLATFORM_COUNT = PLATFORMS.length; // 10
+
+// Pricing. free is view-only (NOT a trial). Plan keys: free / starter / pro.
+// NOTE: the landing FAQ currently labels pro as "All-Platforms" — a name drift to reconcile in 009.
+export const PRICING = {
+  free: { usd: 0, note: 'view-only, cannot connect accounts' },
+  starter: { usd: 16, accounts: 4 },
+  pro: { usd: 33, accounts: 10 },
+};
+
+// Canonical entity sentence (byte-identical across landing footer/JSON-LD/metadata/manifest).
+// Identity-aligned 2026-06-29. Still a clean factual sentence for SEO/AEO (keeps the 10-platform list);
+// the landing adopts this via spec 009 (today the landing still carries its own copy).
+export const ENTITY_SENTENCE =
+  'ad2app is a social scheduler and unified inbox for creators and founders: schedule and publish across 10 platforms (Instagram, TikTok, X, YouTube, LinkedIn, Facebook, Threads, Pinterest, Reddit, and Bluesky), then handle every comment and DM in one place. Social on purpose.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.9.3",
+  "version": "1.11.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -9,7 +9,8 @@
     "./types": "./dist/types/index.js",
     "./api": "./dist/api/index.js",
     "./legal": "./dist/legal/index.js",
-    "./analytics": "./dist/analytics/index.js"
+    "./analytics": "./dist/analytics/index.js",
+    "./brand": "./brand/brand.mjs"
   },
   "typesVersions": {
     "*": {
@@ -28,6 +29,9 @@
       "analytics": [
         "dist/analytics/index.d.ts"
       ],
+      "brand": [
+        "brand/brand.d.ts"
+      ],
       "*": [
         "dist/index.d.ts"
       ]

package/src/analytics/index.test.ts

@@ -9,6 +9,7 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 
 import { EVENTS, PERSON_PROPS } from "./index";
+import type { EventProperties, EmailEventProperties } from "./index";
 
 const SNAKE_CASE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
 
@@ -49,3 +50,72 @@ test("critical person property keys are locked", () => {
   assert.equal(PERSON_PROPS.PLAN, "plan");
   assert.equal(PERSON_PROPS.ROLE, "role");
 });
+
+/**
+ * AD2-952 — property-shape coverage. The compile-time 1:1 guarantee between EVENTS
+ * and EventProperties lives in index.ts (enforced by `tsc --noEmit`); these runtime
+ * tests lock the same contract under `npm test` and pin the email-lifecycle shape.
+ */
+
+// One witness payload per event, typed by EventProperties so the map is forced to
+// carry EXACTLY the EventProperties keys; the assertions below verify it stays 1:1
+// with the runtime EVENTS const.
+const EVENT_PROPERTY_WITNESS: { [E in keyof EventProperties]: EventProperties[E] } = {
+  [EVENTS.LANDING_CTA_CLICKED]: { location: "hero" },
+  [EVENTS.CONNECT_ARTIFACT_COPIED]: { target: "app" },
+  [EVENTS.FREE_SKILLS_REQUESTED]: { source: "landing" },
+  [EVENTS.ACCOUNT_CONNECT_BLOCKED]: {},
+  [EVENTS.MCP_POST_BLOCKED_FREE_TIER]: {},
+  [EVENTS.EMAIL_DELIVERED]: {},
+  [EVENTS.EMAIL_OPENED]: {},
+  [EVENTS.EMAIL_CLICKED]: {},
+  [EVENTS.EMAIL_BOUNCED]: {},
+  [EVENTS.EMAIL_COMPLAINED]: {},
+  [EVENTS.SIGNED_UP]: { method: "email", role: "creator" },
+  [EVENTS.PROFILE_COMPLETED]: { role: "creator" },
+  [EVENTS.LOGGED_IN]: {},
+  [EVENTS.SOCIAL_ACCOUNT_CONNECTED]: { platform: "instagram" },
+  [EVENTS.COMPOSE_STARTED]: {},
+  [EVENTS.POST_SCHEDULED]: { platforms: ["instagram"], platform_count: 1 },
+  [EVENTS.POST_PUBLISHED]: { platforms: ["instagram"], platform_count: 1, status: "success" },
+  [EVENTS.ANALYTICS_VIEWED]: {},
+  [EVENTS.LIMIT_REACHED]: { limit: "accounts", plan: "free", cap: 1 },
+  [EVENTS.UPGRADE_CLICKED]: { surface: "compose" },
+  [EVENTS.CHECKOUT_STARTED]: { plan: "starter" },
+  [EVENTS.SUBSCRIPTION_STARTED]: { plan: "starter" },
+  [EVENTS.SUBSCRIPTION_CANCELED]: { plan: "starter" },
+};
+
+test("EVENTS values are 1:1 with EventProperties keys (no missing or typo'd event)", () => {
+  const eventValues = Object.values(EVENTS).sort();
+  const propertyKeys = Object.keys(EVENT_PROPERTY_WITNESS).sort();
+  assert.deepEqual(propertyKeys, eventValues);
+});
+
+test("the 5 EMAIL_* events are locked and share the EmailEventProperties shape (AD2-894)", () => {
+  const emailEvents = [
+    EVENTS.EMAIL_DELIVERED,
+    EVENTS.EMAIL_OPENED,
+    EVENTS.EMAIL_CLICKED,
+    EVENTS.EMAIL_BOUNCED,
+    EVENTS.EMAIL_COMPLAINED,
+  ];
+  assert.deepEqual(emailEvents, [
+    "email_delivered",
+    "email_opened",
+    "email_clicked",
+    "email_bounced",
+    "email_complained",
+  ]);
+
+  // The shared shape exposes only email_id / subject / link (all optional).
+  const allowedKeys = ["email_id", "link", "subject"];
+  const sample: EmailEventProperties = { email_id: "re_1", subject: "Welcome", link: "https://ad2.app" };
+  assert.deepEqual(Object.keys(sample).sort(), allowedKeys);
+  for (const event of emailEvents) {
+    const witness = EVENT_PROPERTY_WITNESS[event];
+    for (const key of Object.keys(witness)) {
+      assert.ok(allowedKeys.includes(key), `unexpected key on ${event}: ${key}`);
+    }
+  }
+});

package/src/analytics/index.ts

@@ -123,3 +123,28 @@ export const PERSON_PROPS = {
 } as const;
 
 export type PersonPropKey = (typeof PERSON_PROPS)[keyof typeof PERSON_PROPS];
+
+/**
+ * Compile-time taxonomy contract (AD2-952). These are pure type-level assertions:
+ * if EVENTS and EventProperties ever drift, the `tsc --noEmit` CI gate fails the
+ * build — a renamed, typo'd, or unmapped event cannot ship silently. They emit no
+ * runtime code and, being non-exported, do not appear in the package's public types.
+ */
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
+  ? true
+  : false;
+type Expect<T extends true> = T;
+
+// AC2: every EVENTS value maps to exactly one EventProperties entry — no missing
+// 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).
+type EmailLifecycleEvent =
+  | (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>>;

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

@@ -0,0 +1,39 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  ANALYTICS_SOURCES,
+  SchedulingAnalyticsKpiDTO,
+} from './I_SchedulingAnalytics';
+
+// AD2-1045 — the analytics partial-failure signal: a KPI response can name
+// which sources were unavailable so a swallowed Zernio failure is never
+// presented as real zeros.
+
+test('ANALYTICS_SOURCES names the four analytics sources', () => {
+  assert.deepEqual(
+    [...ANALYTICS_SOURCES],
+    ['daily-metrics', 'follower-stats', 'content-decay', 'top-posts'],
+  );
+});
+
+test('SchedulingAnalyticsKpiDTO carries failedSources when provided', () => {
+  const kpi = new SchedulingAnalyticsKpiDTO({
+    impressions: 10,
+    reach: 5,
+    engagementRate: 1.2,
+    followerGrowth: 3,
+    failedSources: ['follower-stats'],
+  });
+  assert.deepEqual(kpi.failedSources, ['follower-stats']);
+});
+
+test('failedSources is optional and absent by default (backward compatible)', () => {
+  const kpi = new SchedulingAnalyticsKpiDTO({
+    impressions: 10,
+    reach: 5,
+    engagementRate: 1.2,
+    followerGrowth: 3,
+  });
+  assert.equal(kpi.failedSources, undefined);
+  assert.equal('failedSources' in JSON.parse(JSON.stringify(kpi)), false);
+});

package/src/types/scheduling/I_SchedulingAnalytics.ts

@@ -5,6 +5,21 @@
  * per-post timeline snapshots, content decay windows, and follower stats.
  */
 
+// ── Analytics sources (AD2-1045) ──────────────────────────────────────────────
+
+/**
+ * The upstream sources an analytics response aggregates. Used by
+ * `failedSources` to name which of them were unavailable.
+ */
+export const ANALYTICS_SOURCES = [
+  'daily-metrics',
+  'follower-stats',
+  'content-decay',
+  'top-posts',
+] as const;
+
+export type AnalyticsSource = (typeof ANALYTICS_SOURCES)[number];
+
 // ── SchedulingAnalyticsKpiDTO ─────────────────────────────────────────────────
 
 /**
@@ -16,12 +31,22 @@ export class SchedulingAnalyticsKpiDTO {
   reach: number;
   engagementRate: number;
   followerGrowth: number;
+  /**
+   * Sources that were unavailable when this response was assembled
+   * (AD2-1045). Absent/empty = all sources healthy. When present, the
+   * numeric fields contain only data from the healthy sources — a partial
+   * outage must never read as real zeros.
+   */
+  failedSources?: AnalyticsSource[];
 
   constructor(data: SchedulingAnalyticsKpiDTO) {
     this.impressions = data.impressions;
     this.reach = data.reach;
     this.engagementRate = data.engagementRate;
     this.followerGrowth = data.followerGrowth;
+    if (data.failedSources !== undefined) {
+      this.failedSources = data.failedSources;
+    }
   }
 }
 
@@ -131,7 +156,11 @@ export class SchedulingPostTimelineEntryDTO {
  * Returned by GET /social/analytics/content-decay.
  */
 export class SchedulingContentDecayDTO {
-  window: '1h' | '6h' | '24h' | '7d';
+  /**
+   * Zernio now returns aggregate bucket labels (e.g. "0-6h", "6-12h"), not
+   * the old fixed windows — widened accordingly (AD2-1061, 2026-07-03).
+   */
+  window: string;
   platform: string;
   /** Percentage of peak engagement remaining at this window */
   pct: number;