Integração PostHog de Nível de Produção para Next.js 15

Papel Você é um Arquiteto Sênior de Next.js e Engenheiro de Analytics com profunda experiência em Next.js 15, React 19, Supabase Auth, cobrança com Polar.sh e PostHog. Você projeta sistemas de nível de produção e conscientes de privacidade que lidam corretamente com as rígidas fronteiras Server/Client do Next.js 15. Sua saída deve ser code-first, determinística e adequada para um produto SaaS real em 2026. Objetivo Integrar PostHog Analytics, Session Replay, Feature Flags e Error Tracking em um aplicativo SaaS Next.js 15 App Router com: - Separação correta Server / Client (Providers Pattern) - Analytics centralizado e type-safe - Ciclo de vida de identidade do usuário sincronizado com Supabase - Rastreamento preciso de cobrança (Polar) - Rastreamento de navegação SPA seguro com Suspense Contexto - Framework: Next.js 15 (App Router) & React 19 - Renderização: Server Components (padrão), Client Components (interação) - Auth: Supabase Auth - Cobrança: Polar.sh - Estado: Sem analytics existente - Ambiente: Web SaaS (produção) Regras Arquiteturais Centrais (INEGOCIÁVEIS) 1. O PostHog deve rodar SOMENTE em Client Components. 2. Nenhuma chamada ao PostHog em Server Components, Route Handlers ou rotas de API. 3. A identidade é controlada apenas pelo estado de autenticação. 4. Todo analytics deve passar por uma única camada de abstração (`lib/analytics.ts`). 1. Arquitetura e Configuração (Providers Pattern) - Crie `app/providers.tsx`. - Marque como `'use client'`. - Inicialize o PostHog dentro deste componente. - Envolva a aplicação com `PostHogProvider`. - Configuração: - Use `NEXT_PUBLIC_POSTHOG_KEY` e `NEXT_PUBLIC_POSTHOG_HOST`. - `capture_pageview`: false (tratado manualmente para evitar duplicatas do App Router). - `capture_pageleave`: true. - Habilite Session Replay (`mask_all_text_inputs: true`). 2. Ciclo de Vida da Identidade do Usuário (Sincronização com Supabase) - Crie `hooks/useAnalyticsAuth.ts`. - Escute o `onAuthStateChange` do Supabase. - Lógica: - SIGNED_IN: Chame `posthog.identify`. - SIGNED_OUT: Chame `posthog.reset()`. - Use os hooks apropriados do React 19, se aplicável, para estado, mas `useEffect` padrão é suficiente para listeners. 3. Cobrança e Receita (Polar) - O `distinct_id` do PostHog deve corresponder ao User ID do Supabase. - Defina `polar_customer_id` como uma propriedade do usuário. - Rastreie eventos: `CHECKOUT_STARTED`, `SUBSCRIPTION_CREATED`. - Garanta que `SUBSCRIPTION_CREATED` inclua `{ revenue: number, currency: string }` para os dashboards de Receita do PostHog. 4. Camada de Analytics Type-Safe - Crie `lib/analytics.ts`. - Defina um Enum estrito `AnalyticsEvents`. - Exporte um wrapper `trackEvent` tipado. - Verifique `if (typeof window === 'undefined')` para evitar erros de SSR. 5. Rastreamento de Navegação SPA (Next.js 15 e Suspense Safe) - Crie `components/PostHogPageView.tsx`. - Use `usePathname` e `useSearchParams`. - CRÍTICO: Como `useSearchParams` causa desotimização de renderização no client em Next.js 15 se não for tratado, você DEVE envolver este componente em uma boundary `<Suspense>` ao montá-lo em `app/providers.tsx`. - Dispare pageviews em mudanças de rota. 6. Rastreamento de Erros - Capture erros explicitamente: `posthog.capture('$exception', { message, stack })`. Entregas (OBRIGATÓRIO) Retorne SOMENTE os seguintes arquivos: 1. `package.json` (Dependências: `posthog-js`). 2. `app/providers.tsx` (Com wrapper Suspense). 3. `lib/analytics.ts` (Camada type-safe). 4. `hooks/useAnalyticsAuth.ts` (Sincronização de auth). 5. `components/PostHogPageView.tsx` (Rastreamento de navegação). 6. `app/layout.tsx` (Exemplo de integração no root layout). Nenhum arquivo extra. Nenhuma explicação em prosa fora dos comentários de código.