ad2app-lib 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to `ad2app-lib` are documented here. The analytics taxonomy
+is the single source of truth across all surfaces; the matching spec lives in
+`ad2appus/docs/posthog-implementation.md` (§3).
+
+## 1.9.0
+
+### Added
+
+- Free Tier analytics (epic AD2-887):
+  - `EVENTS.FREE_SKILLS_REQUESTED` (`free_skills_requested`), shape `{ source: string }` — email submitted for the free skills (AD2-889).
+  - `EVENTS.ACCOUNT_CONNECT_BLOCKED` (`account_connect_blocked`), shape `{ platform?: string }` — free user hits the connect wall (AD2-892).
+  - `EVENTS.MCP_POST_BLOCKED_FREE_TIER` (`mcp_post_blocked_free_tier`), shape `{ target_count?: number }` — free user tries to post in the MCP (AD2-898).
+  - `'free_skills'` added to the `LANDING_CTA_CLICKED` location union.
+- Email lifecycle events (Resend webhook -> PostHog, AD2-894):
+  `EVENTS.EMAIL_DELIVERED` / `EMAIL_OPENED` / `EMAIL_CLICKED` / `EMAIL_BOUNCED` /
+  `EMAIL_COMPLAINED`, all sharing `EmailEventProperties` (`{ email_id?, subject?, link? }`).
+
+## 1.8.0
+
+### Added
+
+- `EVENTS.CONNECT_ARTIFACT_COPIED` (`connect_artifact_copied`) with property
+  shape `{ target: 'app' | 'ask' | 'terminal' | 'editor' }` — fired when the
+  `/connect` install snippet is copied.
+- `'ai_connector'` added to the `LANDING_CTA_CLICKED` location union
+  (`hero | pricing | final_cta | nav | ai_connector`).
+
+### Removed
+
+- `EVENTS.TRIAL_STARTED` (`trial_started`) and its `EventProperties` shape.
+- `PERSON_PROPS.TRIAL_ENDS_AT` (`trial_ends_at`).
+- `'trial'` removed from the documented `PLAN` person-property values, which now
+  match the canonical `SchedulingSubscriptionTier` (`free | starter | pro`).
+
+  ad2app is a paid-only product with no trial, so these events never fired.
+  Verified that no consumer (frontend, backend, landing, mcp) referenced them.
+
+> **Semver note:** removing exported symbols is technically breaking. It is
+> released as a minor because no consumer referenced the removed tokens and all
+> consumers pin `^1.7.x`, so they upgrade frictionlessly. If you prefer strict
+> semver, retag as `2.0.0` and bump the consumer ranges deliberately.

package/dist/types/I_User.d.ts

@@ -44,3 +44,8 @@ export declare class I_UserFindOneDTO {
 export declare class I_UserAuthenticateDTO {
     accessToken: string;
 }
+export declare class I_WebSocialSignInDTO {
+    idToken: string;
+    termsAccepted?: boolean;
+    privacyPolicyAccepted?: boolean;
+}

package/dist/types/I_User.js

@@ -9,7 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.I_UserAuthenticateDTO = exports.I_UserFindOneDTO = exports.I_UserSignUpDTO = exports.I_UserSignInDTO = exports.I_UserCreateDTO = exports.UserRoles = exports.I_SignedUser = exports.I_User = void 0;
+exports.I_WebSocialSignInDTO = exports.I_UserAuthenticateDTO = exports.I_UserFindOneDTO = exports.I_UserSignUpDTO = exports.I_UserSignInDTO = exports.I_UserCreateDTO = exports.UserRoles = exports.I_SignedUser = exports.I_User = void 0;
 const class_validator_1 = require("class-validator");
 class I_User {
 }
@@ -90,3 +90,21 @@ __decorate([
     (0, class_validator_1.IsNotEmpty)(),
     __metadata("design:type", String)
 ], I_UserAuthenticateDTO.prototype, "accessToken", void 0);
+class I_WebSocialSignInDTO {
+}
+exports.I_WebSocialSignInDTO = I_WebSocialSignInDTO;
+__decorate([
+    (0, class_validator_1.IsNotEmpty)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], I_WebSocialSignInDTO.prototype, "idToken", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], I_WebSocialSignInDTO.prototype, "termsAccepted", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], I_WebSocialSignInDTO.prototype, "privacyPolicyAccepted", void 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -34,7 +34,8 @@
     }
   },
   "scripts": {
-    "build": "npx tsc"
+    "build": "npx tsc",
+    "test": "node --import tsx --test $(find src -name '*.test.ts')"
   },
   "keywords": [],
   "author": "Maciej Górski@ad2.app",
@@ -45,5 +46,8 @@
     "date-fns": "^3.5.0",
     "date-fns-tz": "^3.2.0",
     "typescript": "^5.8.3"
+  },
+  "devDependencies": {
+    "tsx": "^4.22.4"
   }
 }

package/src/analytics/index.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Contract tests for the canonical PostHog analytics taxonomy. These lock the
+ * wire format every emitter (frontend / backend / landing / MCP) depends on:
+ * renames do not migrate historical data, so an accidental rename or typo must
+ * fail the build, not silently break dashboards. Written as structural
+ * invariants so legitimately ADDING new events stays green (AD2-952).
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { EVENTS, PERSON_PROPS } from "./index";
+
+const SNAKE_CASE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+
+test("every EVENTS value is a unique, non-empty snake_case string", () => {
+  const values = Object.values(EVENTS);
+  assert.equal(new Set(values).size, values.length, "duplicate event name");
+  for (const value of values) assert.match(value, SNAKE_CASE, `not snake_case: ${value}`);
+});
+
+test("every EVENTS value equals the lower-case of its key (no copy-paste drift)", () => {
+  // Convention: KEY is SCREAMING_SNAKE, value is its lower-case wire name. This
+  // auto-enforces correct naming for current AND future events.
+  for (const [key, value] of Object.entries(EVENTS)) {
+    assert.equal(value, key.toLowerCase(), `EVENTS.${key} should be '${key.toLowerCase()}', got '${value}'`);
+  }
+});
+
+test("every PERSON_PROPS value is a unique, non-empty snake_case string", () => {
+  const values = Object.values(PERSON_PROPS);
+  assert.equal(new Set(values).size, values.length, "duplicate person prop");
+  for (const value of values) assert.match(value, SNAKE_CASE, `not snake_case: ${value}`);
+});
+
+test("critical event wire names are locked (renaming breaks historical data)", () => {
+  // Core funnel + revenue events: a rename silently breaks every dashboard.
+  assert.equal(EVENTS.SIGNED_UP, "signed_up");
+  assert.equal(EVENTS.LOGGED_IN, "logged_in");
+  assert.equal(EVENTS.SOCIAL_ACCOUNT_CONNECTED, "social_account_connected");
+  assert.equal(EVENTS.POST_PUBLISHED, "post_published");
+  assert.equal(EVENTS.LANDING_CTA_CLICKED, "landing_cta_clicked");
+  assert.equal(EVENTS.CHECKOUT_STARTED, "checkout_started");
+  assert.equal(EVENTS.SUBSCRIPTION_STARTED, "subscription_started");
+  assert.equal(EVENTS.SUBSCRIPTION_CANCELED, "subscription_canceled");
+});
+
+test("critical person property keys are locked", () => {
+  assert.equal(PERSON_PROPS.EMAIL, "email");
+  assert.equal(PERSON_PROPS.PLAN, "plan");
+  assert.equal(PERSON_PROPS.ROLE, "role");
+});

package/src/analytics/index.ts

@@ -3,7 +3,7 @@
  *
  * Single source of truth for event names, event property shapes, and person
  * property keys across ALL surfaces (frontend, backend, landing, future MCP).
- * Spec: ad2appus/docs/posthog-implementation.md §3.
+ * Spec: ad2app-specs/analytics-posthog/posthog-implementation.md §3.
  *
  * Naming convention: snake_case, object_verb_past_tense.
  * Do NOT rename events after they ship — historical data does not migrate.
@@ -13,6 +13,19 @@
 export const EVENTS = {
   // Acquisition (landing)
   LANDING_CTA_CLICKED: 'landing_cta_clicked',
+  CONNECT_ARTIFACT_COPIED: 'connect_artifact_copied', // /connect install-snippet copy
+
+  // Free Tier (skills lead magnet + connect wall)
+  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_DELIVERED: 'email_delivered',
+  EMAIL_OPENED: 'email_opened',
+  EMAIL_CLICKED: 'email_clicked',
+  EMAIL_BOUNCED: 'email_bounced',
+  EMAIL_COMPLAINED: 'email_complained',
 
   // Activation (web app)
   SIGNED_UP: 'signed_up', // server-owned (backend, on user creation)
@@ -24,8 +37,7 @@ export const EVENTS = {
   POST_PUBLISHED: 'post_published', // server-confirmed (backend)
   ANALYTICS_VIEWED: 'analytics_viewed',
 
-  // Revenue (backend = source of truth)
-  TRIAL_STARTED: 'trial_started',
+  // Revenue (backend = source of truth). Paid-only product: no trial.
   LIMIT_REACHED: 'limit_reached', // cap hit (e.g. X link-post cap) — the upsell trigger
   UPGRADE_CLICKED: 'upgrade_clicked', // client intent
   CHECKOUT_STARTED: 'checkout_started',
@@ -35,11 +47,35 @@ 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;
+  subject?: string;
+  link?: string;
+}
+
 /** Property shape per event. Keeps emitters honest across repos. */
 export interface EventProperties {
   [EVENTS.LANDING_CTA_CLICKED]: {
-    location: 'hero' | 'pricing' | 'final_cta' | 'nav';
+    location:
+      | 'hero'
+      | 'pricing'
+      | 'final_cta'
+      | 'nav'
+      | 'ai_connector'
+      | 'free_skills';
+  };
+  [EVENTS.CONNECT_ARTIFACT_COPIED]: {
+    target: 'app' | 'ask' | 'terminal' | 'editor';
   };
+  [EVENTS.FREE_SKILLS_REQUESTED]: { source: string };
+  [EVENTS.ACCOUNT_CONNECT_BLOCKED]: { platform?: string };
+  [EVENTS.MCP_POST_BLOCKED_FREE_TIER]: { target_count?: number };
+  [EVENTS.EMAIL_DELIVERED]: EmailEventProperties;
+  [EVENTS.EMAIL_OPENED]: EmailEventProperties;
+  [EVENTS.EMAIL_CLICKED]: EmailEventProperties;
+  [EVENTS.EMAIL_BOUNCED]: EmailEventProperties;
+  [EVENTS.EMAIL_COMPLAINED]: EmailEventProperties;
   [EVENTS.SIGNED_UP]: { method: 'email' | 'google'; role: string };
   [EVENTS.PROFILE_COMPLETED]: { role: string };
   [EVENTS.LOGGED_IN]: { method?: 'email' | 'google' };
@@ -59,7 +95,6 @@ export interface EventProperties {
     status: 'success' | 'partial' | 'failed';
   };
   [EVENTS.ANALYTICS_VIEWED]: { scope?: 'overview' | 'account' | 'post' };
-  [EVENTS.TRIAL_STARTED]: { plan: string };
   [EVENTS.LIMIT_REACHED]: {
     limit: 'x_link_posts' | 'accounts';
     plan: string;
@@ -83,9 +118,8 @@ export interface EventProperties {
 export const PERSON_PROPS = {
   EMAIL: 'email',
   ROLE: 'role',
-  PLAN: 'plan', // 'trial' | 'starter' | 'all_platforms' | 'free'
+  PLAN: 'plan', // 'free' | 'starter' | 'pro' (SchedulingSubscriptionTier)
   ACCOUNT_COUNT: 'account_count',
-  TRIAL_ENDS_AT: 'trial_ends_at',
 } as const;
 
 export type PersonPropKey = (typeof PERSON_PROPS)[keyof typeof PERSON_PROPS];

package/src/api/apiDriver.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Unit tests for the shared HTTP layer (apiDriver / fetchCall). Mocks global
+ * fetch. Covers the two bugs fixed in AD2-947: PUT dropping baseUrl, and the
+ * broken non-JSON / error-body response handling.
+ */
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, test } from "node:test";
+
+import { apiDriver, configureApiDriver, fetchCall } from "./apiDriver";
+
+configureApiDriver({ apiUrl: "https://default.test" });
+
+let calls: { url: string }[] = [];
+let body: string | null = JSON.stringify({ ok: true });
+let status = 200;
+const realFetch = globalThis.fetch;
+
+beforeEach(() => {
+  calls = [];
+  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) });
+    return new Response(body, { status });
+  }) as typeof fetch;
+});
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+const VERBS = ["get", "post", "put", "patch", "delete"] as const;
+
+test("every verb forwards the driver baseUrl (regression: PUT used to drop it)", async () => {
+  const api = apiDriver("https://other.test");
+  for (const verb of VERBS) {
+    calls = [];
+    await (api[verb] as (path: string) => Promise<unknown>)("thing");
+    assert.ok(
+      calls[0]?.url.startsWith("https://other.test/thing"),
+      `${verb} should target other.test, got ${calls[0]?.url}`
+    );
+  }
+});
+
+test("PUT to a non-default baseUrl does not fall back to CONFIG.apiUrl", async () => {
+  await apiDriver("https://other.test").put("x");
+  assert.ok(
+    calls[0]?.url.startsWith("https://other.test/"),
+    `PUT routed to ${calls[0]?.url}`
+  );
+});
+
+test("fetchCall parses a JSON 2xx body", async () => {
+  body = JSON.stringify({ a: 1 });
+  const result = await fetchCall<{ a: number }, unknown>({ path: "x", method: "get" });
+  assert.deepEqual(result, { a: 1 });
+});
+
+test("fetchCall returns text for a non-JSON 2xx body (no rejected promise)", async () => {
+  body = "plain text";
+  const result = await fetchCall<string, unknown>({ path: "x", method: "get" });
+  assert.equal(result, "plain text");
+});
+
+test("fetchCall returns undefined for an empty 2xx body", async () => {
+  body = null;
+  status = 204;
+  const result = await fetchCall<undefined, unknown>({ path: "x", method: "get" });
+  assert.equal(result, undefined);
+});
+
+test("fetchCall throws with a plain-text error body (does not assume JSON)", async () => {
+  body = "Service Unavailable";
+  status = 503;
+  await assert.rejects(() => fetchCall({ path: "x", method: "get" }), /Service Unavailable/);
+});
+
+test("fetchCall surfaces a JSON error body in the thrown message", async () => {
+  body = JSON.stringify({ error: "nope" });
+  status = 400;
+  await assert.rejects(() => fetchCall({ path: "x", method: "get" }), /nope/);
+});

package/src/api/apiDriver.ts

@@ -65,12 +65,26 @@ export async function fetchCall<T, Q>(args: FetchCallArgs<Q>): Promise<T> {
 
   const res = await fetch(fullPath, init);
 
-  if (!res.ok) throw new Error(JSON.stringify(await res.json()));
+  // Read the body ONCE as text. res.json() returns a promise, so the old
+  // synchronous try/catch around it never caught a parse failure (the text()
+  // fallback was dead code), and a plain-text error body threw inside res.json().
+  const rawBody = await res.text();
+
+  if (!res.ok) {
+    let message = rawBody;
+    try {
+      message = JSON.stringify(JSON.parse(rawBody));
+    } catch {
+      // non-JSON error body: keep the raw text
+    }
+    throw new Error(message || `Request failed with status ${res.status}`);
+  }
 
+  if (!rawBody) return undefined as T;
   try {
-    return res.json() as Promise<T>;
+    return JSON.parse(rawBody) as T;
   } catch {
-    return res.text() as Promise<T>;
+    return rawBody as unknown as T;
   }
 }
 
@@ -100,6 +114,7 @@ export function apiDriver(baseUrl?: string) {
         ...args[1],
         path: args[0],
         method: "put",
+        baseUrl,
       }),
     patch: <T, Q>(...args: MethodCallArgs<Q>) =>
       fetchCall<T, Q>({

package/src/types/I_User.ts

@@ -1,4 +1,4 @@
-import { IsBoolean, IsNotEmpty } from 'class-validator';
+import { IsBoolean, IsNotEmpty, IsOptional, IsString } from 'class-validator';
 import { I_Influencer } from './I_Influencer';
 
 export class I_User {
@@ -75,3 +75,17 @@ export class I_UserAuthenticateDTO {
   @IsNotEmpty()
   accessToken: string;
 }
+
+export class I_WebSocialSignInDTO {
+  @IsNotEmpty()
+  @IsString()
+  idToken: string;
+
+  @IsOptional()
+  @IsBoolean()
+  termsAccepted?: boolean;
+
+  @IsOptional()
+  @IsBoolean()
+  privacyPolicyAccepted?: boolean;
+}

package/tsconfig.json

@@ -10,5 +10,6 @@
     "esModuleInterop": true,
     "outDir": "dist"
   },
-  "include": ["src/**/*"]
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }