Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

14.5 KB
Raw Blame
// Analytics — PostHog identity + a typed, documented event taxonomy.
//
// The snippet injected by vite.config.js auto-captures pageviews, clicks and
// session replays anonymously. This module adds:
//   1. Identity      — identifyUser() / resetIdentity() (call after auth resolves).
//   2. Event catalog  — ANALYTICS_EVENTS: the single source of truth for every
//                       product-meaningful event name + its documented props.
//   3. track()        — a validating facade. Unknown events are rejected (and
//                       surfaced in dev) so the taxonomy can't silently drift.
//   4. Funnels        — trackFunnelStep() for ordered conversion journeys
//                       (landing → connect-wallet → action → success).
//   5. Errors         — trackError() to capture handled boundary failures with
//                       context, so reliability shows up alongside behaviour.
//
// Privacy: never pass raw wallet addresses or other PII as props — use
// shortWallet() to truncate. Every call is a no-op when window.posthog isn't
// loaded (embed pages, ad-blockers) so callers can fire-and-forget and analytics
// can never break the app.

// ─────────────────────────────────────────────────────────────────────────────
// Event taxonomy — the documented catalog. Keys are stable event names sent to
// PostHog; comments describe the props each event should carry. Group by journey.
// ─────────────────────────────────────────────────────────────────────────────

import { shortAddress as shortWallet } from './shared/address.js';

export const ANALYTICS_EVENTS = Object.freeze({
	// ── Acquisition ──────────────────────────────────────────────────────────
	/** Landing/home surfaced. props: { referrer?, utm_source?, path? } */
	LANDING_VIEWED: 'landing_viewed',
	/** A primary CTA was clicked. props: { cta: string, location: string } */
	CTA_CLICKED: 'cta_clicked',

	// ── Activation ───────────────────────────────────────────────────────────
	/** Wallet connect initiated. props: { provider?: string } */
	WALLET_CONNECT_STARTED: 'wallet_connect_started',
	/** Wallet connected. props: { provider?, wallet_short?, chain? } */
	WALLET_CONNECT_SUCCEEDED: 'wallet_connect_succeeded',
	/** Wallet connect failed. props: { provider?, reason? } */
	WALLET_CONNECT_FAILED: 'wallet_connect_failed',
	/** An agent was created. props: { agent_id?, source? } */
	AGENT_CREATED: 'agent_created',
	/** A recorded voice sample was cloned onto the agent. props: { agent_id?, billing?, source? } */
	VOICE_CLONE_BOUND: 'agent_voice_clone_bound',
	/** First embed/snippet generated for an agent. props: { agent_id?, embed_kind? } */
	EMBED_GENERATED: 'embed_generated',

	// ── $THREE holder funnel (ordered — see FUNNELS.three) ───────────────────
	/** $THREE token page viewed. props: { price_usd? } */
	TOKEN_PAGE_VIEWED: 'token_page_viewed',
	/** Buy/swap intent clicked. props: { source? } */
	TOKEN_BUY_CLICKED: 'token_buy_clicked',
	/** A swap quote was shown. props: { amount_usd?, out_amount? } */
	TOKEN_QUOTE_SHOWN: 'token_quote_shown',
	/** Swap submitted/confirmed by the user. props: { amount_usd? } */
	TOKEN_SWAP_CONFIRMED: 'token_swap_confirmed',
	/** Swap settled successfully. props: { amount_usd?, tx_short? } */
	TOKEN_SWAP_SUCCEEDED: 'token_swap_succeeded',

	// ── Upgrade / paywall funnel (ordered — see FUNNELS.upgrade) ─────────────
	/** A holder-gate / paywall upsell was shown at a free-lane limit. props:
	 *  { feature?, required_tier?, held_tier?, reason?, has_pay_per_use?, pay_per_use_usd? } */
	UPGRADE_GATE_SHOWN: 'upgrade_gate_shown',
	/** User chose the "Get $THREE" path from the gate. props: { feature?, required_tier? } */
	UPGRADE_GET_THREE_CLICKED: 'upgrade_get_three_clicked',
	/** User chose the contextual "Pay per use" path from the gate. props:
	 *  { feature?, action?, pay_per_use_usd? } */
	UPGRADE_PAY_PER_USE_CLICKED: 'upgrade_pay_per_use_clicked',
	/** The gated action completed after a gate was shown — the conversion. props:
	 *  { feature?, path: 'hold'|'pay_per_use', usd? } */
	UPGRADE_CONVERTED: 'upgrade_converted',

	// ── Engagement ───────────────────────────────────────────────────────────
	/** Marketplace search/filter used. props: { query_len?, filters? } */
	MARKETPLACE_SEARCHED: 'marketplace_searched',
	/** An agent profile was opened. props: { agent_id? } */
	AGENT_PROFILE_VIEWED: 'agent_profile_viewed',
	/** Visualizer/dashboard surface opened. props: { surface: string } — name
	 *  surfaces as `category:name` (e.g. 'dashboard:monetize', 'visualizer:galaxy')
	 *  so insights group cleanly across surfaces. */
	SURFACE_OPENED: 'surface_opened',

	// ── Creator monetization funnel (ordered — see FUNNELS.creator) ──────────
	/** Creator dashboard opened / "become a creator" intent. props: { agent_count?, has_prices? } */
	CREATOR_ONBOARDING_STARTED: 'creator_onboarding_started',
	/** A skill price (or pricing rule) was saved. props: { agent_id?, skill?, price_usdc?, gate_type?, is_first? } */
	CREATOR_PRICE_SET: 'creator_price_set',
	/** A payout wallet was configured for an agent. props: { agent_id?, network? } */
	CREATOR_PAYOUT_CONFIGURED: 'creator_payout_configured',
	/** The creator's first observed sale surfaced in the dashboard. props: { agent_id?, revenue_usd? } */
	CREATOR_FIRST_SALE: 'creator_first_sale',

	// ── Share (this module's own instrumentation surface) ────────────────────
	/** Share card flow opened. props: { kind: string, entity_id? } */
	SHARE_CARD_OPENED: 'share_card_opened',
	/** A share action fired. props: { kind, channel: 'copy'|'download'|'native'|'x', entity_id? } */
	SHARE_CARD_ACTION: 'share_card_action',

	// ── Errors ───────────────────────────────────────────────────────────────
	/** A handled error at a boundary. props: { context, message, code?, status? } */
	ERROR_OCCURRED: 'error_occurred',
});

const _eventValues = new Set(Object.values(ANALYTICS_EVENTS));

/**
 * Ordered conversion funnels. Each is a list of event names from
 * ANALYTICS_EVENTS; trackFunnelStep() tags events with their funnel + step index
 * so PostHog funnel insights line up without per-call configuration.
 */
export const FUNNELS = Object.freeze({
	activation: [
		ANALYTICS_EVENTS.LANDING_VIEWED,
		ANALYTICS_EVENTS.WALLET_CONNECT_STARTED,
		ANALYTICS_EVENTS.WALLET_CONNECT_SUCCEEDED,
		ANALYTICS_EVENTS.AGENT_CREATED,
	],
	three: [
		ANALYTICS_EVENTS.TOKEN_PAGE_VIEWED,
		ANALYTICS_EVENTS.TOKEN_BUY_CLICKED,
		ANALYTICS_EVENTS.TOKEN_QUOTE_SHOWN,
		ANALYTICS_EVENTS.TOKEN_SWAP_CONFIRMED,
		ANALYTICS_EVENTS.TOKEN_SWAP_SUCCEEDED,
	],
	// Supply-side proof: a creator lands on the dashboard, sets a price, wires a
	// payout wallet, and earns. Each step is the lever that turns a viewer into a
	// paid creator — the flywheel three.ws optimizes for.
	creator: [
		ANALYTICS_EVENTS.CREATOR_ONBOARDING_STARTED,
		ANALYTICS_EVENTS.CREATOR_PRICE_SET,
		ANALYTICS_EVENTS.CREATOR_PAYOUT_CONFIGURED,
		ANALYTICS_EVENTS.CREATOR_FIRST_SALE,
	],
	// Contextual upgrade moment at a free-lane limit → conversion. This array is
	// the primary "hold" path (acquire $THREE, whose acquisition tail is the
	// `three` funnel). The alternate "pay per use" branch is its own catalog event
	// (UPGRADE_PAY_PER_USE_CLICKED) — both branches terminate at UPGRADE_CONVERTED
	// when the gated action finally completes, so conversion is measurable for each.
	upgrade: [
		ANALYTICS_EVENTS.UPGRADE_GATE_SHOWN,
		ANALYTICS_EVENTS.UPGRADE_GET_THREE_CLICKED,
		ANALYTICS_EVENTS.UPGRADE_CONVERTED,
	],
});

// ─────────────────────────────────────────────────────────────────────────────
// PostHog plumbing
// ─────────────────────────────────────────────────────────────────────────────

function ph() {
	if (typeof window === 'undefined') return null;
	if (window.__posthog_blocked) return null;
	const p = window.posthog;
	if (!p || typeof p.capture !== 'function') return null;
	return p;
}

const _isDev =
	typeof import.meta !== 'undefined' && import.meta.env ? Boolean(import.meta.env.DEV) : false;

let _lastDistinctId = null;

/**
 * Tie subsequent events to a stable user.
 * @param {{ id: string, username?: string, email?: string, display_name?: string, created_at?: string }} user
 */
export function identifyUser(user) {
	if (!user?.id) return;
	const p = ph();
	if (!p || typeof p.identify !== 'function') return;
	// Avoid re-identifying on every getMe() call (most pages call it on load).
	if (_lastDistinctId === user.id) return;
	_lastDistinctId = user.id;
	try {
		p.identify(String(user.id), {
			username: user.username || undefined,
			email: user.email || undefined,
			name: user.display_name || user.username || undefined,
			created_at: user.created_at || undefined,
		});
	} catch {
		/* swallow — analytics must never break the app */
	}
}

/** Wipe the cookie-stored distinct_id so the next visit isn't tied to the user. */
export function resetIdentity() {
	_lastDistinctId = null;
	const p = ph();
	if (!p || typeof p.reset !== 'function') return;
	try {
		p.reset();
	} catch {
		/* swallow */
	}
}

// ─────────────────────────────────────────────────────────────────────────────
// track() — the validating facade every call site uses
// ─────────────────────────────────────────────────────────────────────────────

/**
 * Capture a product-meaningful event. Reserve for actions in the catalog above —
 * most behaviour is already auto-captured. Unknown event names are rejected so
 * the taxonomy can't silently drift; in dev the rejection is logged.
 *
 * @param {string} event — must be a value from ANALYTICS_EVENTS.
 * @param {Record<string, any>} [props]
 * @returns {boolean} whether the event was accepted + sent.
 */
export function track(event, props = {}) {
	if (!_eventValues.has(event)) {
		if (_isDev && typeof console !== 'undefined') {
			console.warn(
				`[analytics] rejected unknown event "${event}" — add it to ANALYTICS_EVENTS in src/analytics.js`,
			);
		}
		return false;
	}
	const p = ph();
	if (!p) return false;
	try {
		p.capture(event, sanitizeProps(props));
		return true;
	} catch {
		/* swallow — analytics must never break the app */
		return false;
	}
}

/**
 * Track one step of a named conversion funnel. Stamps the event with
 * `funnel` + `funnel_step` (1-based) so funnel insights align in PostHog.
 *
 * @param {keyof typeof FUNNELS} funnel
 * @param {string} event — must belong to FUNNELS[funnel].
 * @param {Record<string, any>} [props]
 * @returns {boolean}
 */
export function trackFunnelStep(funnel, event, props = {}) {
	const steps = FUNNELS[funnel];
	if (!steps) {
		if (_isDev && typeof console !== 'undefined') {
			console.warn(`[analytics] unknown funnel "${funnel}"`);
		}
		return false;
	}
	const idx = steps.indexOf(event);
	if (idx < 0) {
		if (_isDev && typeof console !== 'undefined') {
			console.warn(`[analytics] event "${event}" is not a step of funnel "${funnel}"`);
		}
		return false;
	}
	return track(event, { ...props, funnel, funnel_step: idx + 1 });
}

/**
 * Capture a handled error at a boundary (network, user input, parse) with
 * enough context to triage without leaking internals. Errors are non-fatal to
 * the app — this is observability, not control flow.
 *
 * @param {string} context — where it happened, e.g. 'share_card.generate'.
 * @param {unknown} err — the caught error / value.
 * @param {Record<string, any>} [extra] — additional safe context.
 */
export function trackError(context, err, extra = {}) {
	const message =
		err instanceof Error ? err.message : typeof err === 'string' ? err : String(err ?? 'unknown');
	const code = err && typeof err === 'object' ? err.code : undefined;
	const status = err && typeof err === 'object' ? err.status : undefined;
	return track(ANALYTICS_EVENTS.ERROR_OCCURRED, {
		context,
		message: String(message).slice(0, 300),
		...(code != null ? { code: String(code) } : {}),
		...(status != null ? { status: Number(status) } : {}),
		...extra,
	});
}

// ─────────────────────────────────────────────────────────────────────────────
// Helpers
// ─────────────────────────────────────────────────────────────────────────────

/**
 * Truncate a wallet address for analytics props so a raw public key never lands
 * in an event payload: "FeMb…Jpump".
 * @param {string} addr
 * @returns {string}
 */
export { shortWallet };

// Defensive: strip obvious full-length wallet/PII shapes from props so a careless
// call site can't leak a raw address. Values are kept otherwise as-is.
const _BASE58_WALLET = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
const _EVM_ADDRESS = /^0x[a-fA-F0-9]{40}$/;
function sanitizeProps(props) {
	if (!props || typeof props !== 'object') return {};
	const out = {};
	for (const [k, v] of Object.entries(props)) {
		if (v == null) continue;
		if (typeof v === 'string' && (_BASE58_WALLET.test(v) || _EVM_ADDRESS.test(v))) {
			out[k] = shortWallet(v);
		} else {
			out[k] = v;
		}
	}
	return out;
}