@pixelume/sdk 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,65 @@ conter mudanças incompatíveis, sempre listadas em **Changed/Removed**.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-16
+
+### Added
+
+- `pixelume.analytics` (opt-in): `track`, `startSession`/`endSession` (sessão de **jogo**, idempotentes),
+  `levelStarted`/`levelCompleted`/`levelFailed`, `setConsent`, `isEnabled` e os estados `consent`,
+  `status` e `sessionId`. Catálogo estável: `game_session_started`, `game_session_ended` (com
+  `duration_ms` e `visible_duration_ms`), `level_started`, `level_completed`, `level_failed`. Todo
+  evento leva `game_id`, `game_version`, `sdk_version`, `session_id` e `platform: 'web'`, protegidos
+  contra sobrescrita; nomes e propriedades são validados e limitados.
+- Opção `analytics: { posthog: { projectToken, host }, gameVersion, rememberConsent, onIssue }`, campo
+  `config.analytics` e tipos `PixelumeAnalyticsApi`, `PixelumeAnalyticsOptions`, `PixelumePostHogOptions`,
+  `PixelumeAnalyticsConsent`, `PixelumeAnalyticsStatus`, `PixelumeAnalyticsProperties`,
+  `PixelumeAnalyticsIssue`. Token, host ou `gameVersion` vazios (variável de build definida sem valor)
+  equivalem a ausentes: analytics fica no-op, ou o evento sai sem `game_version`.
+- Provider PostHog: `posthog-js` (`1.435.8`, exata) carregado por `import()` dinâmico **somente após o
+  consentimento**, em chunk separado (~52 KB gzip); instância própria com storage prefixado; autocapture,
+  pageviews, replay, exceções, surveys, flags/remote config e scripts externos desligados; URLs sem query
+  string. Revogar descarta o que estava pendente (inclusive o lote interno do PostHog), reseta a
+  identidade e apaga somente os identificadores do próprio jogo (outro jogo na mesma origem, mesmo com
+  `gameId` de mesmo prefixo, não é afetado). Login identifica com `player.id`; logout/expiração separam.
+
+### Changed
+
+- O pacote passa a ter uma dependência de runtime (`posthog-js`), baixada pelo navegador apenas com
+  analytics configurado e consentido. Sem a opção `analytics`, o comportamento é idêntico ao da 0.5.0
+  (no-op: sem rede, storage ou listeners); o chunk principal cresce ~5 KB gzip.
+
+## [0.5.0] - 2026-10-14
+
+### Added
+
+- `restoreAcrossSessions` (opt-in, padrão `false`): recupera a conta numa **aba nova ou após reabrir o
+  navegador** enquanto a sessão central da Pixelume for válida, sem pedir senha. Após um login, o SDK
+  guarda em `localStorage` só um indício não secreto (`pixelume.oauth.restore.<clientId>`: versão,
+  escopo concedido e data) e, num início sem sessão em memória, faz **no máximo uma** autorização
+  `prompt=none` (ida e volta de topo, sem tela). Requer a Pixelume API com `prompt=none`
+  (implantada em 14/10/2026). `true` usa 30 dias; `{ maxAgeDays }` aceita de 1 a 90.
+- Estado `redirecting`/`exchanging` com `restoring: true` durante a tentativa silenciosa.
+- Motivos anônimos `session_ended` (a API respondeu `login_required`/`consent_required`/
+  `interaction_required`: o indício é removido e nada é tentado de novo automaticamente) e `offline`
+  (sem conexão para tentar ou concluir a recuperação: o indício é mantido).
+- `PixelumeAuthError` com `reason: 'restore_rejected'` quando a recuperação é recusada por outro
+  motivo (por exemplo, `saves` deixou de ser permitido: o indício passa a pedir só `profile`).
+- `PixelumeBrowserAdapter.persistentStorage` e `isOnline()` opcionais; tipo
+  `PixelumeCrossSessionRestoreOptions`; `config.restoreAcrossSessions`.
+- Widget: “Conectando à sua conta Pixelume…” durante a recuperação e textos para sessão encerrada e
+  falta de conexão.
+
+### Changed
+
+- Com `restoreAcrossSessions`, o reload da mesma aba também usa `prompt=none` em vez de passar pelo
+  portal: se a sessão central tiver acabado, o jogador continua como visitante em vez de ver a tela de
+  login. Sem a opção, o comportamento é idêntico ao da 0.4.0 (um indício deixado por uma versão com a
+  opção ligada é apenas removido).
+- Proteções contra loop: uma tentativa por início, marcador por aba que impede nova tentativa por
+  10 minutos se a anterior não voltar, callback repetido recusado sem troca de código, retorno do
+  back/forward cache durante a tentativa vira visitante. Tokens continuam só em memória.
+
 ## [0.4.0] - 2026-10-14
 
 ### Added
@@ -106,7 +165,9 @@ conter mudanças incompatíveis, sempre listadas em **Changed/Removed**.
   `invalid_response`) e `isPixelumeError()`.
 - Build ESM + `.d.ts`, CI e workflow de publicação via npm Trusted Publishing.
 
-[Unreleased]: https://github.com/ericksonnascimento/pixelume-sdk/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/ericksonnascimento/pixelume-sdk/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/ericksonnascimento/pixelume-sdk/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/ericksonnascimento/pixelume-sdk/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/ericksonnascimento/pixelume-sdk/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/ericksonnascimento/pixelume-sdk/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/ericksonnascimento/pixelume-sdk/compare/v0.1.1...v0.2.0

package/README.md

@@ -3,8 +3,10 @@
 SDK TypeScript para jogos web da Pixelume. O core headless continua sendo o padrão e há um widget
 oficial opt-in em `@pixelume/sdk/ui`. Os dois modos usam a mesma autenticação centralizada com OAuth 2.0
 Authorization Code + PKCE S256. A versão 0.4 adiciona **renovação automática de sessão** (refresh tokens
-rotativos, só em memória) e **Cloud Saves** (`pixelume.saves`). Não há dependências de runtime, senha
-no jogo nem `client_secret`.
+rotativos, só em memória) e **Cloud Saves** (`pixelume.saves`). A versão 0.6 acrescenta **analytics
+de gameplay opt-in** (`pixelume.analytics`), desacoplado do provider. Não há senha no jogo nem
+`client_secret`; a única dependência de runtime (`posthog-js`) só é baixada pelo navegador depois do
+consentimento do jogador, num chunk separado.
 
 ## Instalação
 
@@ -103,6 +105,34 @@ nunca sobrescreve, mescla ou reenvia sozinho, e não há fila offline. Saves sã
 verificados: não servem como prova de conquista, ranking ou prêmio. Guia completo:
 [Cloud Saves](docs/CLOUD_SAVES.md).
 
+## Analytics (opt-in, com consentimento)
+
+```ts
+const pixelume = new Pixelume({
+  gameId: 'rail-puzzle',
+  analytics: {
+    posthog: { projectToken: '<POSTHOG_PROJECT_TOKEN>', host: '<POSTHOG_INGESTION_HOST>' },
+    gameVersion: '1.0.0',
+  },
+});
+
+if (pixelume.analytics.consent === 'unknown') showConsentPrompt();
+consentButton.onclick = () => pixelume.analytics.setConsent(true); // false revoga e apaga ids
+
+pixelume.analytics.startSession(); // sessão de JOGO, não de login
+pixelume.analytics.levelStarted(3);
+pixelume.analytics.levelCompleted(3, { stars: 2 });
+pixelume.analytics.levelFailed(4, 'out_of_moves');
+pixelume.analytics.track('hint_used', { source: 'menu' });
+pixelume.analytics.endSession();
+```
+
+Sem a opção `analytics` (ou sem token/host), tudo é no-op: nenhuma rede, storage ou download. Com ela,
+nada é enviado, gravado nem baixado antes de `setConsent(true)`; autocapture, pageviews, replay, surveys,
+flags e scripts externos ficam desligados. Os jogos nunca importam `posthog-js` e nenhum método lança
+exceção nem bloqueia o jogo. Catálogo de eventos, identidade, privacidade, CSP e impacto no bundle:
+[guia de analytics](docs/ANALYTICS.md).
+
 Importar ou instanciar o core não cria elementos, não injeta estilos e não ativa UI. O health check
 também é totalmente independente: chamar `/health` nunca monta o widget.
 
@@ -141,8 +171,11 @@ avisos de conexão durante a renovação e, apenas depois de `saves.save()`/`sav
 status da nuvem.
 
 `pixelume.auth.state.status` é `uninitialized`, `redirecting`, `exchanging`, `anonymous` ou
-`authenticated`. O estado anônimo informa `reason` (`visitor`, `cancelled`, `expired`, `logged_out` ou
-`error`) e, em falha, um `PixelumeError`. Cancelar no portal resulta em visitante, não em exceção.
+`authenticated`. `redirecting`/`exchanging` trazem `restoring: true` durante a recuperação silenciosa
+entre sessões. O estado anônimo informa `reason` (`visitor`, `cancelled`, `expired`, `logged_out`,
+`session_ended`, `offline` ou `error`) e, em falha, um `PixelumeError`. Cancelar no portal resulta em
+visitante, não em exceção. `visitor` nunca significa “a sessão central acabou”: só que não havia o que
+recuperar nesta aba/navegador.
 
 ### Visitante, recarga e expiração
 
@@ -153,6 +186,7 @@ status da nuvem.
   tinha uma sessão (e o escopo concedido). Em uma recarga, inicia uma nova autorização com o mesmo
   escopo; enquanto a sessão central da API continuar válida, o portal retorna sem pedir senha.
   `restoreSession: false` desliga esse comportamento.
+- Aba nova ou navegador reaberto: veja [Recuperação entre sessões](#recuperação-entre-sessões-do-navegador-opt-in).
 - PKCE `state`/`code_verifier` ficam na sessão por no máximo 10 minutos e são removidos antes da troca.
 - Código expirado/repetido, `state` divergente, callback adulterado e 401 deixam o jogo utilizável como
   visitante. O jogo pode oferecer o login novamente.
@@ -160,21 +194,60 @@ status da nuvem.
   `/v1/oauth/revoke` (o que encerra todos os tokens daquela autorização). A sessão central do portal
   continua existente por desenho; entrar novamente pode ser imediato.
 
+### Recuperação entre sessões do navegador (opt-in)
+
+Sem a opção, uma aba nova ou o navegador reaberto começam como visitante, mesmo com a sessão central
+da Pixelume ainda válida (30 dias). Com `restoreAcrossSessions: true`:
+
+```ts
+const pixelume = new Pixelume({
+  gameId: 'meu-jogo',
+  scope: 'profile saves',
+  restoreAcrossSessions: true, // ou { maxAgeDays: 7 }
+});
+```
+
+1. Depois de um login, o SDK grava em `localStorage` somente `pixelume.oauth.restore.<clientId>` =
+   `{ version, scope, at }` — nenhum token, código, verifier, ID ou e-mail.
+2. Num início sem sessão em memória (aba nova, navegador reaberto ou reload), se esse indício existir
+   e tiver menos de `maxAgeDays` (padrão 30), `initialize()` publica
+   `{ status: 'redirecting', restoring: true }` e faz uma navegação de topo para
+   `/v1/oauth/authorize?…&prompt=none`. A API **não mostra tela**: devolve o `code` (PKCE S256 + `state`)
+   se a sessão central for válida, ou `error=login_required`.
+3. No retorno: sucesso → `authenticated` (o escopo pedido nunca passa do anterior nem do configurado), e o
+   SDK devolve a URL original (caminho, query e hash) com `history.replaceState`. `login_required` →
+   `anonymous/session_ended`, o indício é apagado e **nenhuma** tentativa automática se repete até um novo
+   login manual.
+4. Sem conexão no início → `anonymous/offline`, sem navegação, indício mantido (o próximo início tenta).
+
+**UX:** a tentativa é uma ida e volta de topo de poucas centenas de milissegundos; o jogo carrega duas
+vezes. Mostre “Conectando…” enquanto `status` for `uninitialized`/`redirecting`/`exchanging` e, se o jogo
+roteia pelo endereço, leia a rota depois de `initialize()` (ou guarde-a ao ver `redirecting`). Estado em
+memória do jogo antes de `initialize()` se perde na navegação.
+
+**Proteções:** uma tentativa por início; um marcador por aba (`sessionStorage`) impede nova tentativa por
+10 minutos se a anterior não voltar (erro de rede, botão Voltar, back/forward cache → `visitor`); callback
+repetido é recusado sem troca de código; cada aba usa seu próprio `state`/verifier; `logout()` em qualquer
+aba apaga o indício. Sem `localStorage` disponível (bloqueado, adaptador injetado sem
+`persistentStorage`), o comportamento é o da 0.4. Com a opção desligada, um indício antigo é removido.
+
 ## Configuração
 
-| Opção            | Padrão                               | Observação                                                                                |
-| ---------------- | ------------------------------------ | ----------------------------------------------------------------------------------------- |
-| `apiUrl`         | `https://api.pixelume.com.br`        | HTTPS; HTTP só em loopback ou com `allowInsecureHttp` explícito                           |
-| `authUrl`        | `https://auth.pixelume.com.br`       | Portal esperado; a API continua sendo a autoridade que escolhe o redirect                 |
-| `gameId`         | —                                    | slug público do jogo; também é o `clientId` padrão                                        |
-| `clientId`       | `gameId`                             | identificador OAuth público cadastrado; nunca é credencial                                |
-| `redirectUri`    | `<origin>/oauth/callback` no browser | deve coincidir exatamente com o cadastro e não pode conter fragmento nem parâmetros OAuth |
-| `scope`          | `profile`                            | `profile saves` para Cloud Saves (o cadastro do jogo precisa permitir `saves`)            |
-| `restoreSession` | `true`                               | reautoriza após reload da mesma aba sem persistir token                                   |
-| `timeoutMs`      | `10000`                              | cobre resposta e leitura do corpo                                                         |
-| `credentials`    | `omit`                               | política dos módulos genéricos; Auth força `omit` para token/userinfo/revoke              |
-| `fetch`          | `globalThis.fetch`                   | injetável para testes/instrumentação                                                      |
-| `browser`        | globals do browser                   | adaptador avançado para webviews e testes                                                 |
+| Opção                   | Padrão                               | Observação                                                                                                        |
+| ----------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `apiUrl`                | `https://api.pixelume.com.br`        | HTTPS; HTTP só em loopback ou com `allowInsecureHttp` explícito                                                   |
+| `authUrl`               | `https://auth.pixelume.com.br`       | Portal esperado; a API continua sendo a autoridade que escolhe o redirect                                         |
+| `gameId`                | —                                    | slug público do jogo; também é o `clientId` padrão                                                                |
+| `clientId`              | `gameId`                             | identificador OAuth público cadastrado; nunca é credencial                                                        |
+| `redirectUri`           | `<origin>/oauth/callback` no browser | deve coincidir exatamente com o cadastro e não pode conter fragmento nem parâmetros OAuth                         |
+| `scope`                 | `profile`                            | `profile saves` para Cloud Saves (o cadastro do jogo precisa permitir `saves`)                                    |
+| `restoreSession`        | `true`                               | reautoriza após reload da mesma aba sem persistir token                                                           |
+| `restoreAcrossSessions` | `false`                              | opt-in: recupera a conta em aba nova/navegador reaberto via `prompt=none` (indício não secreto em `localStorage`) |
+| `timeoutMs`             | `10000`                              | cobre resposta e leitura do corpo                                                                                 |
+| `credentials`           | `omit`                               | política dos módulos genéricos; Auth força `omit` para token/userinfo/revoke                                      |
+| `fetch`                 | `globalThis.fetch`                   | injetável para testes/instrumentação                                                                              |
+| `browser`               | globals do browser                   | adaptador avançado para webviews e testes                                                                         |
+| `analytics`             | —                                    | opt-in: `{ posthog: { projectToken: 'phc_…', host }, gameVersion }`; sem ele, no-op ([guia](docs/ANALYTICS.md))   |
 
 `authUrl` é informativo/configurável para ambientes, mas o SDK nunca concatena nem escolhe um retorno
 via portal: `/v1/oauth/authorize` valida o cliente/callback e redireciona para o portal configurado na
@@ -202,10 +275,14 @@ uma ferramenta de teste, não UI oficial.
 - `crypto.getRandomValues` e Web Crypto SHA-256 geram `state`, verifier e challenge; não há
   `Math.random`.
 - Access/refresh token, código e verifier não são registrados. Tokens não vão para `localStorage`,
-  `sessionStorage`, cookies, URL, estado observável ou mensagens de erro.
+  `sessionStorage`, cookies, URL, estado observável ou mensagens de erro. Com `restoreAcrossSessions`,
+  `localStorage` recebe apenas o indício `{ version, scope, at }`.
 - CORS/Origin não são considerados autenticação. PKCE, URI exata, state e vínculos persistidos pela API
   são os controles de segurança.
 - XSS ainda pode ler um token que esteja em memória; jogos devem manter CSP e dependências sob controle.
+- Analytics só transmite após consentimento explícito, usa o token **público** de projeto (`phc_…`; o SDK
+  recusa `phx_…`) e nunca recebe tokens, e-mail, nome, dados de save ou URLs com query string. O
+  identificador enviado após login é o `player.id` interno.
 - Cloud Saves sempre passam pela autorização do backend (token do próprio jogo + escopo `saves`); o SDK
   nunca envia `playerId`, e a UI nunca prova legitimidade de progresso.
 
@@ -253,7 +330,8 @@ npm run verify
 npm run example:smoke # leitura opcional da API real
 ```
 
-Mais detalhes: [renovação de sessão](docs/SESSION_RENEWAL.md), [Cloud Saves](docs/CLOUD_SAVES.md),
+Mais detalhes: [analytics](docs/ANALYTICS.md), [renovação de sessão](docs/SESSION_RENEWAL.md),
+[Cloud Saves](docs/CLOUD_SAVES.md),
 [auditoria da Fase 4](docs/PHASE_04_CONTRACT_AUDIT.md), [widget oficial](docs/phase-03-widget.md),
 [integração SSO](docs/SSO_INTEGRATION.md),
 [auditoria do contrato](docs/SSO_CONTRACT_AUDIT.md), [arquitetura](docs/architecture.md) e

package/dist/core/PixelumeClient.d.ts

@@ -1,3 +1,4 @@
+import { type PixelumeAnalyticsApi } from '../modules/analytics/AnalyticsModule.js';
 import { type PixelumeAuthApi, type PixelumeAuthState } from '../modules/auth/AuthModule.js';
 import { type PixelumeHealthApi } from '../modules/health/HealthModule.js';
 import { type PixelumeSavesApi } from '../modules/saves/SavesModule.js';
@@ -10,7 +11,7 @@ import type { PixelumeClientConfig, PixelumeClientOptions } from './types.js';
  * const health = await pixelume.health.check();
  * ```
  *
- * Feature modules are exposed as read-only properties: `health`, `auth` and `saves`. New modules are
+ * Feature modules are exposed as read-only properties: `health`, `auth`, `saves` and `analytics`. New modules are
  * added as new properties without changing existing ones. Nothing touches the DOM; the visual
  * widget lives in the opt-in `@pixelume/sdk/ui` entry point.
  *
@@ -23,6 +24,11 @@ export declare class PixelumeClient {
     readonly auth: PixelumeAuthApi;
     /** Cloud Saves of the signed-in player for `gameId` (requires the `saves` scope). */
     readonly saves: PixelumeSavesApi;
+    /**
+     * Gameplay analytics. A no-op unless the `analytics` option is configured, and silent until the
+     * player consents (`analytics.setConsent(true)`).
+     */
+    readonly analytics: PixelumeAnalyticsApi;
     constructor(options?: PixelumeClientOptions);
     /**
      * Initializes browser authentication once. Callback failures become an anonymous state so a
@@ -32,7 +38,9 @@ export declare class PixelumeClient {
     /**
      * Stops renewal timers and resume listeners and drops credentials from memory, without
      * contacting the API. Call it when the game is torn down (SPA route change, hot reload); call
-     * `auth.logout()` first to also revoke the authorization. The client is unusable afterwards.
+     * `auth.logout()` first to also revoke the authorization. Analytics stops delivering (an active
+     * game session is not ended; call `analytics.endSession()` first if play really ended). The
+     * client is unusable afterwards.
      */
     destroy(): void;
 }

package/dist/core/PixelumeClient.js

@@ -1,4 +1,5 @@
 import { HttpClient } from '../http/HttpClient.js';
+import { AnalyticsModule, } from '../modules/analytics/AnalyticsModule.js';
 import { AuthModule, } from '../modules/auth/AuthModule.js';
 import { HealthModule } from '../modules/health/HealthModule.js';
 import { SavesModule } from '../modules/saves/SavesModule.js';
@@ -11,7 +12,7 @@ import { resolveConfig } from './config.js';
  * const health = await pixelume.health.check();
  * ```
  *
- * Feature modules are exposed as read-only properties: `health`, `auth` and `saves`. New modules are
+ * Feature modules are exposed as read-only properties: `health`, `auth`, `saves` and `analytics`. New modules are
  * added as new properties without changing existing ones. Nothing touches the DOM; the visual
  * widget lives in the opt-in `@pixelume/sdk/ui` entry point.
  *
@@ -23,7 +24,13 @@ export class PixelumeClient {
     auth;
     /** Cloud Saves of the signed-in player for `gameId` (requires the `saves` scope). */
     saves;
+    /**
+     * Gameplay analytics. A no-op unless the `analytics` option is configured, and silent until the
+     * player consents (`analytics.setConsent(true)`).
+     */
+    analytics;
     #authModule;
+    #analyticsModule;
     constructor(options = {}) {
         const resolved = resolveConfig(options);
         this.config = Object.freeze({
@@ -34,8 +41,10 @@ export class PixelumeClient {
             scope: resolved.scope,
             authUrl: resolved.authUrl,
             restoreSession: resolved.restoreSession,
+            restoreAcrossSessions: resolved.crossSessionRestore !== null,
             timeoutMs: resolved.timeoutMs,
             credentials: resolved.credentials,
+            analytics: resolved.analytics === null ? null : resolved.analytics.provider.kind,
         });
         const http = new HttpClient({
             baseUrl: resolved.apiUrl,
@@ -47,6 +56,12 @@ export class PixelumeClient {
         this.#authModule = new AuthModule(http, resolved);
         this.auth = this.#authModule;
         this.saves = new SavesModule(this.#authModule.sessionManager, resolved);
+        this.#analyticsModule = new AnalyticsModule({
+            config: resolved.analytics,
+            auth: this.#authModule,
+            browser: resolved.browser,
+        });
+        this.analytics = this.#analyticsModule;
     }
     /**
      * Initializes browser authentication once. Callback failures become an anonymous state so a
@@ -58,9 +73,12 @@ export class PixelumeClient {
     /**
      * Stops renewal timers and resume listeners and drops credentials from memory, without
      * contacting the API. Call it when the game is torn down (SPA route change, hot reload); call
-     * `auth.logout()` first to also revoke the authorization. The client is unusable afterwards.
+     * `auth.logout()` first to also revoke the authorization. Analytics stops delivering (an active
+     * game session is not ended; call `analytics.endSession()` first if play really ended). The
+     * client is unusable afterwards.
      */
     destroy() {
+        this.#analyticsModule.dispose();
         this.#authModule.dispose();
     }
 }

package/dist/core/PixelumeClient.js.map

@@ -1 +1 @@
-{"version":3,"file":"PixelumeClient.js","sourceRoot":"","sources":["../../src/core/PixelumeClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EACL,UAAU,GAGX,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,YAAY,EAA0B,MAAM,mCAAmC,CAAC;AACzF,OAAO,EAAE,WAAW,EAAyB,MAAM,iCAAiC,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,cAAc;IAChB,MAAM,CAAuB;IAC7B,MAAM,CAAoB;IAC1B,IAAI,CAAkB;IAC/B,qFAAqF;IAC5E,KAAK,CAAmB;IACxB,WAAW,CAAa;IAEjC,YAAY,UAAiC,EAAE;QAC7C,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;YAC1B,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,cAAc,EAAE,QAAQ,CAAC,cAAc;YACvC,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,WAAW,EAAE,QAAQ,CAAC,WAAW;SAClC,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC;YAC1B,OAAO,EAAE,QAAQ,CAAC,MAAM;YACxB,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,WAAW,EAAE,QAAQ,CAAC,WAAW;SAClC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,WAAW,GAAG,IAAI,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IAC1E,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,OAAO;QACL,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;CACF;AAED,8EAA8E;AAC9E,OAAO,EAAE,cAAc,IAAI,QAAQ,EAAE,CAAC","sourcesContent":["import { HttpClient } from '../http/HttpClient.js';\nimport {\n  AuthModule,\n  type PixelumeAuthApi,\n  type PixelumeAuthState,\n} from '../modules/auth/AuthModule.js';\nimport { HealthModule, type PixelumeHealthApi } from '../modules/health/HealthModule.js';\nimport { SavesModule, type PixelumeSavesApi } from '../modules/saves/SavesModule.js';\nimport { resolveConfig } from './config.js';\nimport type { PixelumeClientConfig, PixelumeClientOptions } from './types.js';\n\n/**\n * Entry point of the SDK. Create one instance per API/game and share it.\n *\n * ```ts\n * const pixelume = new PixelumeClient({ gameId: 'rail-puzzle' });\n * const health = await pixelume.health.check();\n * ```\n *\n * Feature modules are exposed as read-only properties: `health`, `auth` and `saves`. New modules are\n * added as new properties without changing existing ones. Nothing touches the DOM; the visual\n * widget lives in the opt-in `@pixelume/sdk/ui` entry point.\n *\n * @throws {PixelumeConfigError} when the options are invalid.\n */\nexport class PixelumeClient {\n  readonly config: PixelumeClientConfig;\n  readonly health: PixelumeHealthApi;\n  readonly auth: PixelumeAuthApi;\n  /** Cloud Saves of the signed-in player for `gameId` (requires the `saves` scope). */\n  readonly saves: PixelumeSavesApi;\n  readonly #authModule: AuthModule;\n\n  constructor(options: PixelumeClientOptions = {}) {\n    const resolved = resolveConfig(options);\n    this.config = Object.freeze({\n      apiUrl: resolved.apiUrl,\n      gameId: resolved.gameId,\n      clientId: resolved.clientId,\n      redirectUri: resolved.redirectUri,\n      scope: resolved.scope,\n      authUrl: resolved.authUrl,\n      restoreSession: resolved.restoreSession,\n      timeoutMs: resolved.timeoutMs,\n      credentials: resolved.credentials,\n    });\n    const http = new HttpClient({\n      baseUrl: resolved.apiUrl,\n      fetch: resolved.fetch,\n      timeoutMs: resolved.timeoutMs,\n      credentials: resolved.credentials,\n    });\n    this.health = new HealthModule(http);\n    this.#authModule = new AuthModule(http, resolved);\n    this.auth = this.#authModule;\n    this.saves = new SavesModule(this.#authModule.sessionManager, resolved);\n  }\n\n  /**\n   * Initializes browser authentication once. Callback failures become an anonymous state so a\n   * game can always continue as a visitor; inspect `pixelume.auth.state.error` for diagnostics.\n   */\n  initialize(): Promise<PixelumeAuthState> {\n    return this.#authModule.initialize();\n  }\n\n  /**\n   * Stops renewal timers and resume listeners and drops credentials from memory, without\n   * contacting the API. Call it when the game is torn down (SPA route change, hot reload); call\n   * `auth.logout()` first to also revoke the authorization. The client is unusable afterwards.\n   */\n  destroy(): void {\n    this.#authModule.dispose();\n  }\n}\n\n/** Concise alias for new integrations; `PixelumeClient` remains supported. */\nexport { PixelumeClient as Pixelume };\n"]}
+{"version":3,"file":"PixelumeClient.js","sourceRoot":"","sources":["../../src/core/PixelumeClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EACL,eAAe,GAEhB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EACL,UAAU,GAGX,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,YAAY,EAA0B,MAAM,mCAAmC,CAAC;AACzF,OAAO,EAAE,WAAW,EAAyB,MAAM,iCAAiC,CAAC;AACrF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,cAAc;IAChB,MAAM,CAAuB;IAC7B,MAAM,CAAoB;IAC1B,IAAI,CAAkB;IAC/B,qFAAqF;IAC5E,KAAK,CAAmB;IACjC;;;OAGG;IACM,SAAS,CAAuB;IAChC,WAAW,CAAa;IACxB,gBAAgB,CAAkB;IAE3C,YAAY,UAAiC,EAAE;QAC7C,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;YAC1B,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,cAAc,EAAE,QAAQ,CAAC,cAAc;YACvC,qBAAqB,EAAE,QAAQ,CAAC,mBAAmB,KAAK,IAAI;YAC5D,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,SAAS,EAAE,QAAQ,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI;SACjF,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC;YAC1B,OAAO,EAAE,QAAQ,CAAC,MAAM;YACxB,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,WAAW,EAAE,QAAQ,CAAC,WAAW;SAClC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,WAAW,GAAG,IAAI,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;QACxE,IAAI,CAAC,gBAAgB,GAAG,IAAI,eAAe,CAAC;YAC1C,MAAM,EAAE,QAAQ,CAAC,SAAS;YAC1B,IAAI,EAAE,IAAI,CAAC,WAAW;YACtB,OAAO,EAAE,QAAQ,CAAC,OAAO;SAC1B,CAAC,CAAC;QACH,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC;IACzC,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACH,OAAO;QACL,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,CAAC;QAChC,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;IAC7B,CAAC;CACF;AAED,8EAA8E;AAC9E,OAAO,EAAE,cAAc,IAAI,QAAQ,EAAE,CAAC","sourcesContent":["import { HttpClient } from '../http/HttpClient.js';\nimport {\n  AnalyticsModule,\n  type PixelumeAnalyticsApi,\n} from '../modules/analytics/AnalyticsModule.js';\nimport {\n  AuthModule,\n  type PixelumeAuthApi,\n  type PixelumeAuthState,\n} from '../modules/auth/AuthModule.js';\nimport { HealthModule, type PixelumeHealthApi } from '../modules/health/HealthModule.js';\nimport { SavesModule, type PixelumeSavesApi } from '../modules/saves/SavesModule.js';\nimport { resolveConfig } from './config.js';\nimport type { PixelumeClientConfig, PixelumeClientOptions } from './types.js';\n\n/**\n * Entry point of the SDK. Create one instance per API/game and share it.\n *\n * ```ts\n * const pixelume = new PixelumeClient({ gameId: 'rail-puzzle' });\n * const health = await pixelume.health.check();\n * ```\n *\n * Feature modules are exposed as read-only properties: `health`, `auth`, `saves` and `analytics`. New modules are\n * added as new properties without changing existing ones. Nothing touches the DOM; the visual\n * widget lives in the opt-in `@pixelume/sdk/ui` entry point.\n *\n * @throws {PixelumeConfigError} when the options are invalid.\n */\nexport class PixelumeClient {\n  readonly config: PixelumeClientConfig;\n  readonly health: PixelumeHealthApi;\n  readonly auth: PixelumeAuthApi;\n  /** Cloud Saves of the signed-in player for `gameId` (requires the `saves` scope). */\n  readonly saves: PixelumeSavesApi;\n  /**\n   * Gameplay analytics. A no-op unless the `analytics` option is configured, and silent until the\n   * player consents (`analytics.setConsent(true)`).\n   */\n  readonly analytics: PixelumeAnalyticsApi;\n  readonly #authModule: AuthModule;\n  readonly #analyticsModule: AnalyticsModule;\n\n  constructor(options: PixelumeClientOptions = {}) {\n    const resolved = resolveConfig(options);\n    this.config = Object.freeze({\n      apiUrl: resolved.apiUrl,\n      gameId: resolved.gameId,\n      clientId: resolved.clientId,\n      redirectUri: resolved.redirectUri,\n      scope: resolved.scope,\n      authUrl: resolved.authUrl,\n      restoreSession: resolved.restoreSession,\n      restoreAcrossSessions: resolved.crossSessionRestore !== null,\n      timeoutMs: resolved.timeoutMs,\n      credentials: resolved.credentials,\n      analytics: resolved.analytics === null ? null : resolved.analytics.provider.kind,\n    });\n    const http = new HttpClient({\n      baseUrl: resolved.apiUrl,\n      fetch: resolved.fetch,\n      timeoutMs: resolved.timeoutMs,\n      credentials: resolved.credentials,\n    });\n    this.health = new HealthModule(http);\n    this.#authModule = new AuthModule(http, resolved);\n    this.auth = this.#authModule;\n    this.saves = new SavesModule(this.#authModule.sessionManager, resolved);\n    this.#analyticsModule = new AnalyticsModule({\n      config: resolved.analytics,\n      auth: this.#authModule,\n      browser: resolved.browser,\n    });\n    this.analytics = this.#analyticsModule;\n  }\n\n  /**\n   * Initializes browser authentication once. Callback failures become an anonymous state so a\n   * game can always continue as a visitor; inspect `pixelume.auth.state.error` for diagnostics.\n   */\n  initialize(): Promise<PixelumeAuthState> {\n    return this.#authModule.initialize();\n  }\n\n  /**\n   * Stops renewal timers and resume listeners and drops credentials from memory, without\n   * contacting the API. Call it when the game is torn down (SPA route change, hot reload); call\n   * `auth.logout()` first to also revoke the authorization. Analytics stops delivering (an active\n   * game session is not ended; call `analytics.endSession()` first if play really ended). The\n   * client is unusable afterwards.\n   */\n  destroy(): void {\n    this.#analyticsModule.dispose();\n    this.#authModule.dispose();\n  }\n}\n\n/** Concise alias for new integrations; `PixelumeClient` remains supported. */\nexport { PixelumeClient as Pixelume };\n"]}

package/dist/core/config.d.ts

@@ -1,8 +1,20 @@
 import type { CredentialsPolicy, FetchLike } from '../http/types.js';
-import type { PixelumeClientOptions } from './types.js';
+import type { PixelumeAnalyticsIssue, PixelumeClientOptions } from './types.js';
 export declare const DEFAULT_API_URL = "https://api.pixelume.com.br";
 export declare const DEFAULT_AUTH_URL = "https://auth.pixelume.com.br";
 export declare const DEFAULT_TIMEOUT_MS = 10000;
+/** Validated analytics configuration. `null` in `ResolvedConfig` means "no-op". */
+export interface ResolvedAnalyticsConfig {
+    readonly provider: {
+        readonly kind: 'posthog';
+        readonly token: string;
+        readonly host: string;
+    };
+    readonly gameId: string;
+    readonly gameVersion: string | null;
+    readonly rememberConsent: boolean;
+    readonly onIssue: ((issue: PixelumeAnalyticsIssue) => void) | null;
+}
 export interface ResolvedConfig {
     apiUrl: string;
     gameId: string | null;
@@ -11,11 +23,16 @@ export interface ResolvedConfig {
     scope: 'profile' | 'profile saves';
     authUrl: string;
     restoreSession: boolean;
+    /** `null` when cross-session restoration is disabled. */
+    crossSessionRestore: {
+        readonly maxAgeMs: number;
+    } | null;
     allowInsecureHttp: boolean;
     browser: PixelumeClientOptions['browser'];
     timeoutMs: number;
     credentials: CredentialsPolicy;
     fetch: FetchLike;
+    analytics: ResolvedAnalyticsConfig | null;
 }
 export declare function resolveConfig(options: PixelumeClientOptions): ResolvedConfig;
 /**

package/dist/core/config.js

@@ -6,6 +6,8 @@ const MAX_TIMEOUT_MS = 2_147_483_647; // setTimeout limit
 const GAME_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/u;
 const CLIENT_ID_PATTERN = /^[A-Za-z0-9._-]{1,128}$/u;
 const CREDENTIALS = ['omit', 'same-origin', 'include'];
+const POSTHOG_PROJECT_TOKEN_PATTERN = /^phc_[A-Za-z0-9_-]{8,128}$/u;
+const GAME_VERSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/u;
 export function resolveConfig(options) {
     const allowInsecureHttp = options.allowInsecureHttp === true;
     const gameId = options.gameId === undefined ? null : validateGameId(options.gameId);
@@ -17,13 +19,93 @@ export function resolveConfig(options) {
         redirectUri: resolveRedirectUri(options, allowInsecureHttp),
         scope: validateScope(options.scope ?? 'profile'),
         restoreSession: validateBoolean('restoreSession', options.restoreSession ?? true),
+        crossSessionRestore: resolveCrossSessionRestore(options.restoreAcrossSessions),
         allowInsecureHttp,
         browser: options.browser,
         timeoutMs: options.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : validateTimeout(options.timeoutMs),
         credentials: validateCredentials(options.credentials ?? 'omit'),
         fetch: resolveFetch(options.fetch),
+        analytics: resolveAnalytics(options.analytics, gameId, allowInsecureHttp),
     };
 }
+/**
+ * Missing configuration (no object, `enabled: false`, empty token or host) is a no-op, so a build
+ * without the variables keeps working. A value that is present but wrong fails fast, like every
+ * other option; a personal API key is always refused.
+ */
+function resolveAnalytics(value, gameId, allowInsecureHttp) {
+    if (value === undefined)
+        return null;
+    // Validated at runtime: JavaScript callers may pass anything.
+    const raw = value;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new PixelumeConfigError('analytics must be an object');
+    }
+    const enabled = validateBoolean('analytics.enabled', value.enabled ?? true);
+    const provider = value.provider ?? 'posthog';
+    if (provider !== 'posthog')
+        throw new PixelumeConfigError('analytics.provider must be "posthog"');
+    const rememberConsent = validateBoolean('analytics.rememberConsent', value.rememberConsent ?? true);
+    const onIssue = value.onIssue;
+    if (onIssue !== undefined && typeof onIssue !== 'function') {
+        throw new PixelumeConfigError('analytics.onIssue must be a function');
+    }
+    // Like token and host, an empty value (build variable defined but blank) means "not provided".
+    const rawGameVersion = optionalString('analytics.gameVersion', value.gameVersion);
+    const gameVersion = rawGameVersion === null ? null : validateGameVersion(rawGameVersion);
+    const posthog = value.posthog;
+    if (posthog !== undefined && (typeof posthog !== 'object' || posthog === null)) {
+        throw new PixelumeConfigError('analytics.posthog must be an object');
+    }
+    const token = optionalString('analytics.posthog.projectToken', value.posthog?.projectToken);
+    const host = optionalString('analytics.posthog.host', value.posthog?.host);
+    if (token !== null)
+        validatePostHogToken(token);
+    const normalizedHost = host === null ? null : normalizeAnalyticsHost(host, allowInsecureHttp);
+    if (!enabled || token === null || normalizedHost === null)
+        return null;
+    if (gameId === null) {
+        throw new PixelumeConfigError('analytics requires the client to be created with a gameId');
+    }
+    return Object.freeze({
+        provider: Object.freeze({ kind: 'posthog', token, host: normalizedHost }),
+        gameId,
+        gameVersion,
+        rememberConsent,
+        onIssue: onIssue ?? null,
+    });
+}
+function optionalString(name, value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== 'string')
+        throw new PixelumeConfigError(`${name} must be a string`);
+    const trimmed = value.trim();
+    return trimmed === '' ? null : trimmed;
+}
+function validatePostHogToken(token) {
+    if (/^phx_/u.test(token)) {
+        throw new PixelumeConfigError('analytics.posthog.projectToken must be the public project token (phc_...); personal API keys (phx_...) must never reach the browser');
+    }
+    if (!POSTHOG_PROJECT_TOKEN_PATTERN.test(token)) {
+        throw new PixelumeConfigError('analytics.posthog.projectToken must be a PostHog project token (phc_...)');
+    }
+}
+/** Same rules as `apiUrl`; a path is allowed for reverse proxies (e.g. `https://example.com/ingest`). */
+function normalizeAnalyticsHost(value, allowInsecureHttp) {
+    try {
+        return normalizeApiUrl(value, allowInsecureHttp);
+    }
+    catch {
+        throw new PixelumeConfigError('analytics.posthog.host must be an https: URL without credentials, query or fragment, e.g. https://us.i.posthog.com');
+    }
+}
+function validateGameVersion(value) {
+    if (typeof value !== 'string' || !GAME_VERSION_PATTERN.test(value)) {
+        throw new PixelumeConfigError('analytics.gameVersion must be 1-64 letters, digits, dots, plus signs, underscores or hyphens');
+    }
+    return value;
+}
 function resolveRedirectUri(options, allowInsecureHttp) {
     const value = options.redirectUri ?? defaultRedirectUri(options.browser);
     return value === null ? null : normalizeRedirectUri(value, allowInsecureHttp);
@@ -34,6 +116,23 @@ function validateScope(value) {
     }
     return value;
 }
+const DAY_MS = 24 * 60 * 60_000;
+function resolveCrossSessionRestore(value) {
+    if (value === undefined || value === false)
+        return null;
+    if (value === true)
+        return Object.freeze({ maxAgeMs: 30 * DAY_MS });
+    // Validated at runtime: JavaScript callers may pass anything.
+    const raw = value;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new PixelumeConfigError('restoreAcrossSessions must be a boolean or { maxAgeDays }');
+    }
+    const days = raw.maxAgeDays ?? 30;
+    if (typeof days !== 'number' || !Number.isInteger(days) || days < 1 || days > 90) {
+        throw new PixelumeConfigError('restoreAcrossSessions.maxAgeDays must be an integer from 1 to 90');
+    }
+    return Object.freeze({ maxAgeMs: days * DAY_MS });
+}
 function validateBoolean(name, value) {
     if (typeof value !== 'boolean')
         throw new PixelumeConfigError(`${name} must be a boolean`);