ad2app-lib 1.5.0 → 1.6.0

package/index.ts

@@ -1,5 +1,6 @@
 import * as types from './src/types';
 import * as utils from './src/utils';
 import * as api from './src/api/apiDriver';
+import * as analytics from './src/analytics';
 
-export { types, utils, api };
+export { types, utils, api, analytics };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ad2app-lib",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "commonjs",
@@ -8,7 +8,8 @@
     "./utils": "./dist/utils/index.js",
     "./types": "./dist/types/index.js",
     "./api": "./dist/api/index.js",
-    "./legal": "./dist/legal/index.js"
+    "./legal": "./dist/legal/index.js",
+    "./analytics": "./dist/analytics/index.js"
   },
   "typesVersions": {
     "*": {
@@ -24,6 +25,9 @@
       "legal": [
         "dist/legal/index.d.ts"
       ],
+      "analytics": [
+        "dist/analytics/index.d.ts"
+      ],
       "*": [
         "dist/index.d.ts"
       ]

package/src/analytics/index.ts

@@ -0,0 +1,91 @@
+/**
+ * Canonical PostHog analytics taxonomy for ad2app.
+ *
+ * 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.
+ *
+ * Naming convention: snake_case, object_verb_past_tense.
+ * Do NOT rename events after they ship — historical data does not migrate.
+ */
+
+/** Canonical PostHog event names. */
+export const EVENTS = {
+  // Acquisition (landing)
+  LANDING_CTA_CLICKED: 'landing_cta_clicked',
+
+  // Activation (web app)
+  SIGNED_UP: 'signed_up', // server-owned (backend, on user creation)
+  PROFILE_COMPLETED: 'profile_completed', // the /complete-profile step (influencers)
+  LOGGED_IN: 'logged_in',
+  SOCIAL_ACCOUNT_CONNECTED: 'social_account_connected',
+  COMPOSE_STARTED: 'compose_started',
+  POST_SCHEDULED: 'post_scheduled',
+  POST_PUBLISHED: 'post_published', // server-confirmed (backend)
+  ANALYTICS_VIEWED: 'analytics_viewed',
+
+  // Revenue (backend = source of truth)
+  TRIAL_STARTED: 'trial_started',
+  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',
+  SUBSCRIPTION_STARTED: 'subscription_started',
+  SUBSCRIPTION_CANCELED: 'subscription_canceled',
+} as const;
+
+export type EventName = (typeof EVENTS)[keyof typeof EVENTS];
+
+/** Property shape per event. Keeps emitters honest across repos. */
+export interface EventProperties {
+  [EVENTS.LANDING_CTA_CLICKED]: {
+    location: 'hero' | 'pricing' | 'final_cta' | 'nav';
+  };
+  [EVENTS.SIGNED_UP]: { method: 'email' | 'google'; role: string };
+  [EVENTS.PROFILE_COMPLETED]: { role: string };
+  [EVENTS.LOGGED_IN]: { method?: 'email' | 'google' };
+  [EVENTS.SOCIAL_ACCOUNT_CONNECTED]: {
+    platform: string;
+    account_count?: number;
+  };
+  [EVENTS.COMPOSE_STARTED]: { source?: 'wizard' | 'quick' };
+  [EVENTS.POST_SCHEDULED]: {
+    platforms: string[];
+    platform_count: number;
+    scheduled_for?: string;
+  };
+  [EVENTS.POST_PUBLISHED]: {
+    platforms: string[];
+    platform_count: number;
+    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;
+    cap: number;
+  };
+  [EVENTS.UPGRADE_CLICKED]: {
+    from_plan?: string;
+    to_plan?: string;
+    surface: string;
+  };
+  [EVENTS.CHECKOUT_STARTED]: { plan: string };
+  [EVENTS.SUBSCRIPTION_STARTED]: {
+    plan: string;
+    mrr?: number;
+    accounts_included?: number;
+  };
+  [EVENTS.SUBSCRIPTION_CANCELED]: { plan: string; reason?: string };
+}
+
+/** Canonical person property keys (set via identify / $set). */
+export const PERSON_PROPS = {
+  EMAIL: 'email',
+  ROLE: 'role',
+  PLAN: 'plan', // 'trial' | 'starter' | 'all_platforms' | 'free'
+  ACCOUNT_COUNT: 'account_count',
+  TRIAL_ENDS_AT: 'trial_ends_at',
+} as const;
+
+export type PersonPropKey = (typeof PERSON_PROPS)[keyof typeof PERSON_PROPS];

package/src/legal/meta.ts

@@ -1,5 +1,5 @@
 export const LEGAL_META = {
-  lastUpdated: '26 May 2025',
+  lastUpdated: '10 June 2026',
   contactEmail: 'kontakt@ad2.app',
   controllerName: 'Ad2app sp. z o.o.',
   controllerAddress: 'ul. Juliana Smulikowskiego 4A/21, 00-389 Warszawa, Poland',

package/src/legal/privacy.ts

@@ -46,7 +46,8 @@ export const PRIVACY_SECTIONS: LegalSection[] = [
           { text: '**Post content & scheduled posts:** the content you compose, schedule, and publish through the Service — including post text, captions, hashtags, links, scheduling times, and the images, videos, and other media you upload for those posts — together with the publishing status and metadata of each post.' },
           { text: '**Published-post analytics:** performance and engagement metrics for posts you have published through the Service to your connected accounts (e.g. views, impressions, likes, comments, shares, reach, and other statistics), as provided by the connected platform\'s API.' },
           { text: '**Media & content:** files you upload (images, videos, documents) for posts, campaigns, or your profile.' },
-          { text: '**Technical & usage data:** IP address, browser type and version, operating system, pages visited, referral URLs, timestamps, crash reports, and usage events (e.g. feature interactions tracked via Google Analytics 4).' },
+          { text: '**Technical & usage data:** anonymised IP address, browser type and version, operating system, pages visited, referral URLs, timestamps, error and crash reports, and usage events (e.g. feature interactions such as button clicks and page views, tracked via PostHog — see Sections 6 and 9). Usage tracking starts only after you give consent via the cookie banner.' },
+          { text: '**Session replay data:** with your consent (see Section 9), we record replays of your interactions with the Service (mouse movement, scrolling, clicks, page navigation) to diagnose usability problems and errors. All text you type into input fields is masked before recording and never leaves your browser in readable form. Recordings are retained for 30 days.' },
           { text: '**Billing data:** billing address and payment reference. Payment card details are handled exclusively by Stripe and are never stored by ad2app.' },
           { text: '**Waitlist data:** if you submit your email address via our waitlist form before registering, we store that email address to notify you when access is available.' },
           { text: '**Feedback data:** free-text feedback submitted via the in-app feedback form. This may incidentally contain personal data you choose to include.' },
@@ -73,7 +74,7 @@ export const PRIVACY_SECTIONS: LegalSection[] = [
           ['Complying with legal obligations (tax, accounting, record-keeping)', 'Art. 6(1)(c) — legal obligation: Polish Accounting Act (Ustawa o rachunkowości), Tax Ordinance (Ordynacja podatkowa), VAT Act (Ustawa o VAT).'],
           ['Waitlist email: notifying you when platform access is available', 'Art. 6(1)(a) — consent (given at the point of waitlist submission; withdrawable at any time).'],
           ['Processing in-app feedback', 'Art. 6(1)(f) — legitimate interests: ad2app\'s interest in improving the Service through user feedback.'],
-          ['Improving and developing the Service (usage analytics via Google Analytics 4)', 'Art. 6(1)(f) — legitimate interests: ad2app\'s interest in understanding usage patterns to improve product quality, balanced against minimal privacy impact through pseudonymisation. Where analytics cookies are used, Art. 6(1)(a) consent applies.'],
+          ['Improving and developing the Service (usage analytics, session replay, and error tracking via PostHog)', 'Art. 6(1)(a) — consent, given via the cookie consent banner and withdrawable at any time. No analytics events are captured and no analytics cookies are set before you make a choice. Supplemented by Art. 6(1)(f) — legitimate interests — for aggregate, pseudonymised product statistics.'],
           ['Security, fraud prevention, and abuse detection', 'Art. 6(1)(f) — legitimate interests: ad2app\'s interest in maintaining platform integrity and protecting users from harm, which overrides the minimal intrusiveness of security logging.'],
           ['Transfer of personal data in a merger, acquisition, or business asset sale', 'Art. 6(1)(f) — legitimate interests: ad2app\'s legitimate interest in completing lawful business restructuring, balanced against data subjects\' interests. Data subjects will be notified before their data is subject to a materially different privacy policy.'],
           ['Sending marketing communications', 'Art. 6(1)(a) — consent (withdrawable at any time without affecting prior processing).'],
@@ -97,6 +98,8 @@ export const PRIVACY_SECTIONS: LegalSection[] = [
           { text: '**Inbox data (DMs and comments):** retained for the duration of your account; deleted with your account data.' },
           { text: '**Invoices and billing records:** 5 years from the end of the fiscal year (Polish Accounting Act).' },
           { text: '**Technical logs:** up to 90 days.' },
+          { text: '**Product analytics events (PostHog):** retained in pseudonymised form for the operation of our analytics; deleted within 30 days of an erasure request or consent withdrawal.' },
+          { text: '**Session replay recordings (PostHog):** 30 days, then automatically deleted.' },
           { text: '**Marketing consent records:** until consent is withdrawn plus 3 years for compliance evidence.' },
           { text: '**Waitlist emails:** until you register for an account or request deletion, or 24 months from submission if you do not register — whichever comes first.' },
           { text: '**In-app feedback:** up to 24 months from submission.' },
@@ -119,7 +122,7 @@ export const PRIVACY_SECTIONS: LegalSection[] = [
             sub: [
               { text: '**Zernio (ARBICHAT, S.L.)** — social media API aggregation: we pass OAuth tokens, post content, media files, and inbox data to Zernio solely to execute publishing and inbox operations on your behalf. Zernio is incorporated in Spain (EEA); however, data is processed on infrastructure with residency in North America (United States). This constitutes an international data transfer covered by Standard Contractual Clauses (Commission Decision 2021/914).' },
               { text: '**Stripe** — payment processing: billing address, email, and payment reference are shared with Stripe to process subscription payments. Stripe is located in the United States and operates under the EU–US Data Privacy Framework.' },
-              { text: '**Google Analytics 4** — product analytics: pseudonymised usage event data (feature interactions, session data, device/browser info) is sent to Google only after you have given explicit analytics consent. Google is located in the United States and participates in the EU–US Data Privacy Framework.' },
+              { text: '**PostHog (PostHog, Inc.)** — product analytics, session replay, and error tracking: pseudonymised usage event data (feature interactions, page views, device/browser info), masked session recordings, and error reports are processed only after you have given explicit analytics consent via the cookie banner. Our PostHog instance is **PostHog Cloud EU, hosted in Frankfurt, Germany** — analytics data is stored and processed within the EEA. PostHog, Inc. is incorporated in the United States; any residual access from outside the EEA is governed by a Data Processing Agreement incorporating Standard Contractual Clauses (Commission Decision 2021/914).' },
               { text: '**Vercel Inc.** — backend API hosting and compute: server-side application code, API requests, and associated request logs are processed on Vercel\'s infrastructure. Vercel is located in the United States and transfers are covered by Standard Contractual Clauses (Commission Decision 2021/914).' },
               { text: '**Neon Inc.** — PostgreSQL database hosting: all structured platform data (accounts, campaigns, collaborations, social account metadata) is stored in a Neon-hosted PostgreSQL database. Neon is located in the United States and transfers are covered by Standard Contractual Clauses (Commission Decision 2021/914).' },
               { text: '**Google Firebase (Firebase Authentication)** — authentication token verification: authentication tokens issued to users may be verified against Firebase Authentication to validate active sessions. Firebase is a Google service located in the United States and operates under the EU–US Data Privacy Framework.' },
@@ -136,7 +139,7 @@ export const PRIVACY_SECTIONS: LegalSection[] = [
     id: 's7',
     title: '7. International Data Transfers',
     blocks: [
-      { kind: 'p', text: 'Your data is primarily processed within the European Economic Area (EEA). We use certain processors located outside the EEA, including processors based in the United States (currently: Vercel, Neon, Google Firebase, Stripe, Google Analytics 4, and Zernio). For all such transfers we ensure adequate safeguards through one or more of the following mechanisms:' },
+      { kind: 'p', text: 'Your data is primarily processed within the European Economic Area (EEA). Product analytics data (PostHog) is stored and processed on EU servers in Frankfurt, Germany. We use certain processors located outside the EEA, including processors based in the United States (currently: Vercel, Neon, Google Firebase, Stripe, and Zernio; plus residual support access by PostHog, Inc.). For all such transfers we ensure adequate safeguards through one or more of the following mechanisms:' },
       {
         kind: 'ul',
         items: [
@@ -180,10 +183,10 @@ export const PRIVACY_SECTIONS: LegalSection[] = [
         items: [
           { text: '**Strictly necessary cookies:** required for authentication sessions and core platform functionality. Cannot be disabled without breaking the Service. Legal basis: Art. 6(1)(b) — contract performance; no consent required. Duration: session cookies expire when you close your browser; authentication cookies expire after 30 days of inactivity.' },
           { text: '**Functional cookies:** set only in direct response to an action you take (e.g. selecting a language or theme preference), and strictly necessary to deliver that specific function you have requested. They do not track you across sessions beyond preserving your chosen setting. Legal basis: strictly necessary to fulfil your explicit request under Art. 173 of the Polish Telecommunications Act (ePrivacy); no separate consent required. Duration: up to 12 months, or cleared when you clear your browser data.' },
-          { text: '**Analytics cookies (Google Analytics 4):** collect pseudonymised usage event data to help us understand how the Service is used. Legal basis: Art. 6(1)(a) — consent. No analytics cookies are set prior to your affirmative consent via the cookie consent banner shown on first visit. The `_ga` cookie set by Google Analytics expires after 2 years; `_ga_*` expires after 2 years. Data is sent to Google LLC (United States) under the EU–US Data Privacy Framework.' },
+          { text: '**Analytics cookies (PostHog):** collect pseudonymised usage event data, enable session replay (with all typed input masked), and capture error reports to help us understand and improve how the Service is used. Legal basis: Art. 6(1)(a) — consent. **No analytics cookies are set and no analytics events are captured before you make a choice** in the cookie consent banner shown on first visit. If you accept, PostHog sets a first-party cookie (name beginning `ph_`) on the `ad2.app` domain, valid for up to 1 year, shared between our website and the app so you are not asked twice. If you decline, no analytics cookie is set and no events are collected. Analytics data is processed on PostHog Cloud EU servers in Frankfurt, Germany (see Section 6).' },
         ],
       },
-      { kind: 'p', text: 'You may withdraw or update your cookie consent at any time through the consent management panel accessible via the cookie settings link in the footer. Withdrawing analytics consent does not affect platform functionality.' },
+      { kind: 'p', text: 'You may withdraw or update your cookie consent at any time via the "Cookie settings" link in the footer of our website, or on this Privacy Policy page in the app. Withdrawing analytics consent does not affect platform functionality.' },
       { kind: 'subheading', text: 'Browser local storage' },
       { kind: 'p', text: 'In addition to cookies, we use browser local storage to preserve application state between sessions. This includes: your language and theme preferences; a cached copy of your subscription tier and status (retained for up to 30 days then invalidated); and draft campaign deadline data. Local storage data is stored on your device only and is not transmitted to our servers independently of your normal usage. It is cleared when you clear your browser data or log out.' },
     ],

package/src/legal/terms.ts

@@ -216,6 +216,7 @@ export const TERMS_SECTIONS: LegalSection[] = [
     title: '13. Data Protection',
     blocks: [
       { kind: 'p', text: 'Our collection and use of personal data is governed by our {PRIVACY}, which forms part of these Terms. By accepting these Terms, you acknowledge that you have read and understood our Privacy Policy.' },
+      { kind: 'p', text: 'The Service uses third-party data processors — including EU-hosted product analytics (PostHog Cloud EU), payment processing (Stripe), and social media API aggregation (Zernio) — as listed and described in the Privacy Policy. Usage analytics and session replay operate only with your consent, which you may give or withdraw at any time via the cookie consent controls described in the Privacy Policy.' },
       { kind: 'p', text: 'Where you, as an Advertiser, use the Service to access, communicate with, or manage Influencer personal data through the platform, ad2app acts as a **data processor** on your behalf under Article 28 GDPR, and you act as the **data controller** for that processing. Our Data Processing Agreement (available on request at kontakt@ad2.app) governs that relationship. You remain solely responsible for ensuring you have a valid legal basis for any personal data processing you direct through the platform and for your own compliance with GDPR in your capacity as controller.' },
     ],
   },