@pixelume/sdk 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ conter mudanças incompatíveis, sempre listadas em **Changed/Removed**.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-13
+
+### Added
+
+- Entry point opt-in `@pixelume/sdk/ui` com `mountPixelumeWidget()`, Shadow DOM aberto e controlador
+  `hide()`, `show()` e `destroy()`.
+- Widget oficial responsivo com estados de visitante, carregamento, autenticado e erro; login/logout
+  reutilizam exclusivamente `client.auth`.
+- Posição, distância das bordas, container e `z-index` configuráveis, incluindo safe areas mobile.
+- Navegação por teclado, Escape com devolução de foco, foco visível, região de status e isolamento de
+  eventos pointer/touch/teclado do jogo.
+- Testes DOM do widget e validação dos dois entrypoints no consumidor empacotado.
+
+### Changed
+
+- O exemplo Vite agora monta também o widget oficial, mantendo os controles headless para demonstrar os
+  dois modos de consumo.
+
+## [0.2.0] - 2026-10-13
+
+### Added
+
+- `Pixelume` como alias conciso e `PixelumeClient.initialize()` idempotente.
+- `client.auth` com Authorization Code + PKCE S256: login por redirecionamento, callback validado,
+  consulta de jogador, revogação/logout, estado observável e assinatura cancelável.
+- Restauração após recarga por nova autorização SSO, sem persistir access token; somente um marcador
+  não sensível e o estado PKCE transitório ficam em `sessionStorage`.
+- Configuração tipada de `clientId`, `redirectUri`, `authUrl`, `restoreSession` e adaptador de browser.
+- Exemplo Vite com fluxo de autenticação completo e auditoria/documentação do contrato real.
+
+### Changed
+
+- O `kind` de `PixelumeError` ganhou o valor aditivo `auth`; consumidores `0.x` com `switch`
+  exaustivo devem tratar esse novo caso.
+- O cliente HTTP interno passou a serializar formulários OAuth URL-encoded.
+
 ## [0.1.1] - 2026-10-13
 
 ### Changed
@@ -29,6 +65,8 @@ 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.1.1...HEAD
+[Unreleased]: https://github.com/ericksonnascimento/pixelume-sdk/compare/v0.3.0...HEAD
+[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
 [0.1.1]: https://github.com/ericksonnascimento/pixelume-sdk/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/ericksonnascimento/pixelume-sdk/releases/tag/v0.1.0

package/README.md

@@ -1,27 +1,9 @@
 # @pixelume/sdk
 
-SDK TypeScript dos jogos web do estúdio **Pixelume**. Fornece um cliente tipado, seguro e sem
-dependências de runtime para a [Pixelume API](https://api.pixelume.com.br), independente de framework ou
-engine (funciona com Vite, Three.js, React, JavaScript puro, SSR e workers).
-
-> **Status: Fase 1 — fundação.** Esta versão oferece configuração, cliente HTTP, erros padronizados e a
-> checagem de disponibilidade da API. Login, sessão, cloud saves e analytics **ainda não existem** e
-> serão adicionados quando os contratos da API estiverem prontos (veja o [roadmap](docs/roadmap.md)).
-
-## Capacidades
-
-| Capacidade                                   | Fase 1 | Observação                                              |
-| -------------------------------------------- | :----: | ------------------------------------------------------- |
-| `PixelumeClient` com configuração validada   |   ✅   | `apiUrl`, `gameId`, `timeoutMs`, `credentials`, `fetch` |
-| `client.health.check()` (`GET /health`)      |   ✅   | sem CORS na API: servidor/mesma origem (ver abaixo)     |
-| Erros padronizados, timeout e cancelamento   |   ✅   | `PixelumeError` + `kind`                                |
-| Autenticação / Pixelume Auth                 |   —    | aguarda portal central e contratos de redirect          |
-| Cloud saves, analytics, rankings, conquistas |   —    | aguardam contratos na API                               |
-
-## Pré-requisitos
-
-- Navegadores modernos (Chrome/Edge 98+, Firefox 97+, Safari 15.4+) ou Node.js 22+, Deno, Bun, Workers.
-- Projeto ESM (o pacote é ESM-only, com tipos incluídos). Em CommonJS use `await import('@pixelume/sdk')`.
+SDK TypeScript para jogos web da Pixelume. O core headless continua sendo o padrão; a versão 0.3 adiciona
+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. Não há dependências de runtime, senha no jogo nem
+`client_secret`.
 
 ## Instalação
 
@@ -29,91 +11,185 @@ engine (funciona com Vite, Three.js, React, JavaScript puro, SSR e workers).
 npm install @pixelume/sdk
 ```
 
-Publicado no npm: [`@pixelume/sdk`](https://www.npmjs.com/package/@pixelume/sdk) (versão atual `0.1.0`).
+O pacote é ESM-only, inclui tipos e funciona em Vite, JavaScript/TypeScript puro e engines web. Em
+CommonJS, use `await import('@pixelume/sdk')`.
+
+## Configuração obrigatória no backend
+
+Antes de integrar um jogo, registre na Pixelume API:
 
-## Uso
+- um `client_id` público, normalmente igual ao `gameId`;
+- o escopo `profile`;
+- cada callback completo por igualdade exata de scheme, host, porta, path e query.
+
+Não são aceitos curingas, prefixos ou callbacks enviados dinamicamente. O cliente local já cadastrado é
+`pixelume-local-dev`, exclusivamente com `http://localhost:4173/oauth/callback` e
+`http://127.0.0.1:4173/oauth/callback`. Jogos publicados exigem migration/configuração revisada na API.
+
+## Uso headless
 
 ```ts
-import { PixelumeClient } from '@pixelume/sdk';
+import { Pixelume, isPixelumeError } from '@pixelume/sdk';
+
+const pixelume = new Pixelume({
+  gameId: 'rail-puzzle',
+  // Use clientId somente quando for diferente do gameId.
+  // clientId: 'rail-puzzle.web',
+  // Padrão no browser: `${location.origin}/oauth/callback`.
+  redirectUri: 'https://rail-puzzle.pixelume.com.br/oauth/callback',
+});
 
-const pixelume = new PixelumeClient({
-  apiUrl: 'https://api.pixelume.com.br', // padrão
-  gameId: 'rail-puzzle', // opcional nesta fase
+const initial = await pixelume.initialize();
+// `initialize()` nunca impede o jogo de abrir: falhas de callback viram estado anonymous/error.
+
+const unsubscribe = pixelume.auth.subscribe((state, previous) => {
+  if (state.status !== previous.status) renderAccountState(state);
 });
 
-const health = await pixelume.health.check();
-// { status: 'ok', registration: 'email-verification', release: 'd99d195…' }
-```
+const player = await pixelume.auth.getPlayer(); // PixelumePlayer | null
 
-Saída real obtida pelo exemplo em 2026-10-13 (Node.js, pacote instalado via `npm pack`):
+loginButton.addEventListener('click', () => {
+  void pixelume.auth.login(); // navegação de topo para a API e o portal Auth
+});
 
-```json
-{
-  "sdk": "0.1.0",
-  "apiUrl": "https://api.pixelume.com.br",
-  "health": {
-    "status": "ok",
-    "registration": "email-verification",
-    "release": "d99d19543620f09309268f67d959e874ddc78ecf"
+logoutButton.addEventListener('click', async () => {
+  try {
+    await pixelume.auth.logout(); // revoga somente o token deste jogo
+  } catch (error) {
+    if (!isPixelumeError(error)) throw error;
+    showRecoverableError(error.kind);
   }
-}
+});
+
+// Ao desmontar a tela:
+unsubscribe();
 ```
 
-### `health.check()` no navegador
+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.
 
-A API ainda **não envia cabeçalhos CORS em `/health`** (só em `/v1/*`). Em uma página servida por outra
-origem, o navegador bloqueia a resposta e o SDK rejeita com `PixelumeNetworkError`. Use `health.check()`
-no servidor (Node/SSR/workers), em ferramentas, ou na mesma origem via proxy — o
-[exemplo Vite](examples/vite-basic) usa o proxy do `vite dev`. A correção depende da API
-([auditoria](docs/api-contract-audit.md)).
+## Widget opcional
 
-### Configuração
+```ts
+import { Pixelume } from '@pixelume/sdk';
+import { mountPixelumeWidget } from '@pixelume/sdk/ui';
 
-| Opção               | Padrão                        | Descrição                                                                                    |
-| ------------------- | ----------------------------- | -------------------------------------------------------------------------------------------- |
-| `apiUrl`            | `https://api.pixelume.com.br` | `https:` obrigatório; `http:` aceito só para `localhost`/`127.0.0.1`/`[::1]`/`*.localhost`.  |
-| `gameId`            | —                             | slug público (`a-z`, `0-9`, `-`, até 64). Identifica o jogo; **não** é credencial.           |
-| `timeoutMs`         | `10000`                       | tempo máximo de cada operação, incluindo leitura do corpo.                                   |
-| `credentials`       | `'omit'`                      | política de cookies do `fetch` para módulos futuros. O SDK não presume cookies cross-origin. |
-| `fetch`             | `globalThis.fetch`            | implementação injetável (testes, SSR, instrumentação).                                       |
-| `allowInsecureHttp` | `false`                       | permite `http:` em hosts não-loopback (ex.: IP da LAN). Nunca em produção.                   |
+const pixelume = new Pixelume({
+  gameId: 'rail-puzzle',
+  redirectUri: 'https://rail-puzzle.pixelume.com.br/oauth/callback',
+});
 
-Opções inválidas lançam `PixelumeConfigError` no construtor. Cada operação aceita
-`{ signal?: AbortSignal; timeoutMs?: number }`.
+await pixelume.initialize();
 
-### Erros
+const widget = mountPixelumeWidget(pixelume, {
+  position: 'bottom-right',
+  offset: 16,
+  theme: 'pixel',
+});
 
-Todas as falhas são `PixelumeError` com um `kind` estável:
+// Ao esconder controles, pausar ou trocar de tela:
+widget.hide();
+widget.show();
+
+// Ao encerrar a tela/jogo:
+widget.destroy();
+```
+
+O painel usa Shadow DOM aberto, não aplica CSS global e chama somente `pixelume.auth.login()` e
+`pixelume.auth.logout()`. Entrar sempre redireciona ao portal Pixelume Auth; o widget não exibe campos de
+e-mail ou senha. Para overlays próprios ou canvas fullscreen, passe `container`, ajuste `position`,
+`offset` e `zIndex`. Veja o [guia completo do widget](docs/phase-03-widget.md).
+
+`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.
+
+### Visitante, recarga e expiração
+
+- Sem login ou callback, `initialize()` termina como visitante e não faz requisição.
+- O access token opaco dura 10 minutos e fica **somente em memória**.
+- Após autenticar, o SDK guarda em `sessionStorage` apenas o marcador não secreto de que aquela aba
+  tinha uma sessão. Em uma recarga, inicia uma nova autorização; enquanto a sessão central da API
+  continuar válida, o portal retorna sem pedir senha. `restoreSession: false` desliga esse comportamento.
+- 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.
+- `logout()` limpa o estado local imediatamente e chama `/v1/oauth/revoke`. A sessão central do portal
+  continua existente por desenho; entrar novamente pode ser imediato.
+
+## 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 |
+| `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                                                 |
+
+`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
+API. Isso evita transformar o SDK em fonte de open redirect.
+
+## Desenvolvimento local e produção
+
+| Ambiente         | Cliente/callback                                                                | API/portal                                                      |
+| ---------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| exemplo local    | `pixelume-local-dev` + `http://localhost:4173/oauth/callback`                   | produção por padrão; callbacks loopback já cadastrados          |
+| API/Auth locais  | cadastrar o mesmo callback no banco local e configurar as origens do portal/API | `apiUrl` pode ser loopback; o portal é escolhido pela API local |
+| jogo em produção | cliente próprio + callback HTTPS exato                                          | `https://api.pixelume.com.br` → `https://auth.pixelume.com.br`  |
+
+Execute `npm run example:prepare`, `npm run example:build` e depois
+`npm --prefix examples/vite-basic run dev`. O exemplo tem botões de login, consulta e logout e é apenas
+uma ferramenta de teste, não UI oficial.
+
+## Segurança e confiança
+
+- O fluxo não é OIDC: não há ID Token, discovery, refresh token nem `client_secret`.
+- A sessão central é cookie `HttpOnly`, `Secure`, `SameSite=Lax` e host-only da API. O jogo nunca a lê.
+- Requests OAuth do jogo usam Bearer curto e `credentials: 'omit'`; `credentials: 'include'` pertence
+  apenas ao portal ao consultar/concluir a sessão central.
+- `crypto.getRandomValues` e Web Crypto SHA-256 geram `state`, verifier e challenge; não há
+  `Math.random`.
+- Access token, código e verifier não são registrados. Tokens não vão para `localStorage`, cookies ou URL.
+- 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.
+
+## Erros
+
+Todo erro lançado diretamente pelo SDK é `PixelumeError`. Os `kind` estáveis são `config`, `auth`,
+`http`, `network`, `timeout`, `aborted` e `invalid_response`. `initialize()` captura falhas para permitir
+o modo visitante; consulte `pixelume.auth.state.error`. Métodos chamados explicitamente (`login`,
+`getPlayer`, `logout`) rejeitam normalmente.
+
+O SDK não faz retry automático. Para 400/401/403/429/5xx, use `PixelumeHttpError.status`, `code` e
+`requestId`; para cancelamento do chamador, use `AbortSignal`.
+
+## Health check
 
 ```ts
-import { isPixelumeError } from '@pixelume/sdk';
-
-const controller = new AbortController();
-try {
-  await pixelume.health.check({ signal: controller.signal, timeoutMs: 5_000 });
-} catch (error) {
-  if (!isPixelumeError(error)) throw error;
-  switch (error.kind) {
-    case 'http': // error.status, error.code ('RATE_LIMITED'…), error.requestId
-    case 'network': // offline, DNS/TLS ou bloqueio de CORS
-    case 'timeout': // error.timeoutMs
-    case 'aborted': // cancelado pelo AbortSignal
-    case 'invalid_response': // a API respondeu fora do contrato
-    case 'config': // configuração inválida
-  }
-}
+const health = await pixelume.health.check();
 ```
 
-Mensagens de erro não incluem corpo, cookies, cabeçalhos nem query string. O corpo bruto fica em
-`PixelumeHttpError.payload`, propriedade não enumerável (não aparece em `JSON.stringify`). O SDK nunca
-escreve no console.
+`GET /health` ainda não expõe CORS em produção, então funciona em Node/SSR/worker, mesma origem ou proxy
+local, mas não diretamente de outro domínio no browser.
+
+## Compatibilidade
 
-## Segurança
+| SDK     | Pixelume API                                         | Pixelume Auth                  | Recursos                                        |
+| ------- | ---------------------------------------------------- | ------------------------------ | ----------------------------------------------- |
+| `0.3.x` | OpenAPI `0.4.0`, release SSO `3846479` ou compatível | Fase 2 `3a1ded4` ou compatível | Widget opt-in, SSO PKCE, perfil, logout, health |
+| `0.2.x` | OpenAPI `0.4.0`, release SSO `3846479` ou compatível | Fase 2 `3a1ded4` ou compatível | SSO PKCE, perfil, logout, health                |
+| `0.1.x` | API anterior/atual para `/health`                    | não consumido                  | fundação e health apenas                        |
 
-- O SDK não contém nem aceita API keys, tokens administrativos ou senhas.
-- `gameId` é público; autorização sempre vem da API.
-- Não há fluxo de login com senha dentro do jogo — e não haverá: o login será feito pelo Pixelume Auth.
-- O SDK não define `Origin`/`Referer`/`Cookie` e não trata CORS como segurança.
+Como o pacote ainda está em `0.x`, mudanças incompatíveis usam incremento _minor_ e são listadas no
+[CHANGELOG](CHANGELOG.md).
 
 ## Desenvolvimento
 
@@ -121,26 +197,14 @@ Requer Node.js 24 (`.nvmrc`).
 
 ```bash
 npm ci
-npm run lint         # ESLint + Prettier
-npm run typecheck
-npm test             # unitários + integração com servidor HTTP local (sem rede)
-npm run build        # dist/ (ESM + .d.ts + sourcemaps)
-npm run check:package  # dist browser-safe, conteúdo do tarball, publint, attw
-npm run example:prepare && npm run example:build   # instala o .tgz no exemplo e compila
-npm run example:smoke  # exemplo Node contra a API real (rede)
-npm run test:live      # teste opcional contra a API real (rede)
-npm run verify       # tudo o que a CI executa
+npm run verify
+npm run example:smoke # leitura opcional da API real
 ```
 
-## Documentação
-
-- [Arquitetura e decisões técnicas](docs/architecture.md)
-- [Auditoria de contratos da API](docs/api-contract-audit.md)
-- [Publicação, CI/CD e rollback](docs/publishing.md)
-- [Roadmap](docs/roadmap.md)
-- [Changelog](CHANGELOG.md)
+Mais detalhes: [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
+[publicação](docs/publishing.md).
 
 ## Licença
 
-Proprietária — todos os direitos reservados. Veja [LICENSE](LICENSE). A disponibilidade pública no npm
-não concede direitos além dos descritos na licença.
+Proprietária — todos os direitos reservados. Veja [LICENSE](LICENSE).

package/dist/contracts/index.d.ts

@@ -16,6 +16,23 @@ export type ParseResult<T> = {
     readonly reason: string;
 };
 export type BodyParser<T> = (body: unknown) => ParseResult<T>;
+export interface PlayerWire {
+    id: string;
+    displayName: string;
+    avatarUrl: string | null;
+}
+export interface PlayerEnvelopeWire {
+    player: PlayerWire;
+}
+export declare const parsePlayerEnvelope: BodyParser<PlayerEnvelopeWire>;
+export interface OAuthTokenResponseWire {
+    access_token: string;
+    token_type: 'Bearer';
+    expires_in: number;
+    scope: 'profile';
+}
+export declare const parseOAuthTokenResponse: BodyParser<OAuthTokenResponseWire>;
+export declare const parseEmptyResponse: BodyParser<void>;
 /** `GET /health` → 200. OpenAPI: `{ status: 'ok', registration: enum, release?: /^[a-f0-9]{7,40}$/ }`. */
 export interface HealthResponseWire {
     status: 'ok';

package/dist/contracts/index.js

@@ -13,6 +13,42 @@ const fail = (reason) => ({ ok: false, reason });
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+export const parsePlayerEnvelope = (body) => {
+    if (!isRecord(body) || !isRecord(body.player)) {
+        return fail('expected a JSON object containing "player"');
+    }
+    const { id, displayName, avatarUrl } = body.player;
+    if (typeof id !== 'string' || id.length === 0)
+        return fail('expected "player.id" to be a string');
+    if (typeof displayName !== 'string')
+        return fail('expected "player.displayName" to be a string');
+    if (avatarUrl !== null && typeof avatarUrl !== 'string') {
+        return fail('expected "player.avatarUrl" to be a string or null');
+    }
+    return ok({ player: { id, displayName, avatarUrl } });
+};
+export const parseOAuthTokenResponse = (body) => {
+    if (!isRecord(body))
+        return fail('expected a JSON object');
+    if (typeof body.access_token !== 'string' ||
+        !/^[A-Za-z0-9_-]{43,128}$/u.test(body.access_token)) {
+        return fail('expected "access_token" to be a base64url token');
+    }
+    if (body.token_type !== 'Bearer')
+        return fail('expected "token_type" to be "Bearer"');
+    if (!Number.isInteger(body.expires_in) || body.expires_in <= 0) {
+        return fail('expected "expires_in" to be a positive integer');
+    }
+    if (body.scope !== 'profile')
+        return fail('expected "scope" to be "profile"');
+    return ok({
+        access_token: body.access_token,
+        token_type: 'Bearer',
+        expires_in: body.expires_in,
+        scope: 'profile',
+    });
+};
+export const parseEmptyResponse = (body) => body === undefined ? ok(undefined) : fail('expected an empty response body');
 export const parseHealthResponse = (body) => {
     if (!isRecord(body))
         return fail('expected a JSON object');

package/dist/contracts/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH,MAAM,EAAE,GAAG,CAAI,KAAQ,EAAkB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAClE,MAAM,IAAI,GAAG,CAAC,MAAc,EAAsB,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;AAE7E,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AASD,MAAM,CAAC,MAAM,mBAAmB,GAAmC,CAAC,IAAI,EAAE,EAAE;IAC1E,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,wBAAwB,CAAC,CAAC;IAC3D,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC,8BAA8B,CAAC,CAAC;IACtE,IAAI,OAAO,IAAI,CAAC,YAAY,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,wCAAwC,CAAC,CAAC;IACjG,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACnE,OAAO,IAAI,CAAC,gDAAgD,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,EAAE,CAAC;QACR,MAAM,EAAE,IAAI;QACZ,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,GAAG,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;KACjE,CAAC,CAAC;AACL,CAAC,CAAC;AAOF,qGAAqG;AACrG,MAAM,UAAU,kBAAkB,CAAC,IAAa;IAC9C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1D,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC;IAChD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC7F,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC;AACjD,CAAC","sourcesContent":["/**\n * Wire contracts of the Pixelume API used by the SDK, with hand-written runtime guards.\n *\n * Source of truth: `pixelume-api` (`docs/openapi.yaml` and `src/interfaces/http/app.ts`).\n * See `docs/api-contract-audit.md`. These types describe JSON on the wire and are internal;\n * public modules map them to SDK types so the API can evolve without breaking consumers.\n *\n * Validation is intentionally tolerant to *additive* changes (unknown fields are ignored,\n * unknown enum values are accepted as strings) and strict about the fields the SDK relies on.\n */\n\nexport type ParseResult<T> =\n  { readonly ok: true; readonly value: T } | { readonly ok: false; readonly reason: string };\n\nexport type BodyParser<T> = (body: unknown) => ParseResult<T>;\n\nconst ok = <T>(value: T): ParseResult<T> => ({ ok: true, value });\nconst fail = (reason: string): ParseResult<never> => ({ ok: false, reason });\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\n/** `GET /health` → 200. OpenAPI: `{ status: 'ok', registration: enum, release?: /^[a-f0-9]{7,40}$/ }`. */\nexport interface HealthResponseWire {\n  status: 'ok';\n  registration: string;\n  release?: string;\n}\n\nexport const parseHealthResponse: BodyParser<HealthResponseWire> = (body) => {\n  if (!isRecord(body)) return fail('expected a JSON object');\n  if (body.status !== 'ok') return fail('expected \"status\" to be \"ok\"');\n  if (typeof body.registration !== 'string') return fail('expected \"registration\" to be a string');\n  if (body.release !== undefined && typeof body.release !== 'string') {\n    return fail('expected \"release\" to be a string when present');\n  }\n  return ok({\n    status: 'ok',\n    registration: body.registration,\n    ...(body.release === undefined ? {} : { release: body.release }),\n  });\n};\n\n/** Error envelope returned by every API error: `{ error: { code, message, requestId } }`. */\nexport interface ErrorEnvelopeWire {\n  error: { code: string; message: string; requestId: string };\n}\n\n/** Returns the envelope when `body` matches it, `null` otherwise (e.g. an HTML 502 from a proxy). */\nexport function parseErrorEnvelope(body: unknown): ErrorEnvelopeWire | null {\n  if (!isRecord(body) || !isRecord(body.error)) return null;\n  const { code, message, requestId } = body.error;\n  if (typeof code !== 'string' || typeof message !== 'string' || typeof requestId !== 'string') {\n    return null;\n  }\n  return { error: { code, message, requestId } };\n}\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Wire contracts of the Pixelume API used by the SDK, with hand-written runtime guards.\n *\n * Source of truth: `pixelume-api` (`docs/openapi.yaml` and `src/interfaces/http/app.ts`).\n * See `docs/api-contract-audit.md`. These types describe JSON on the wire and are internal;\n * public modules map them to SDK types so the API can evolve without breaking consumers.\n *\n * Validation is intentionally tolerant to *additive* changes (unknown fields are ignored,\n * unknown enum values are accepted as strings) and strict about the fields the SDK relies on.\n */\n\nexport type ParseResult<T> =\n  { readonly ok: true; readonly value: T } | { readonly ok: false; readonly reason: string };\n\nexport type BodyParser<T> = (body: unknown) => ParseResult<T>;\n\nconst ok = <T>(value: T): ParseResult<T> => ({ ok: true, value });\nconst fail = (reason: string): ParseResult<never> => ({ ok: false, reason });\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nexport interface PlayerWire {\n  id: string;\n  displayName: string;\n  avatarUrl: string | null;\n}\n\nexport interface PlayerEnvelopeWire {\n  player: PlayerWire;\n}\n\nexport const parsePlayerEnvelope: BodyParser<PlayerEnvelopeWire> = (body) => {\n  if (!isRecord(body) || !isRecord(body.player)) {\n    return fail('expected a JSON object containing \"player\"');\n  }\n  const { id, displayName, avatarUrl } = body.player;\n  if (typeof id !== 'string' || id.length === 0) return fail('expected \"player.id\" to be a string');\n  if (typeof displayName !== 'string') return fail('expected \"player.displayName\" to be a string');\n  if (avatarUrl !== null && typeof avatarUrl !== 'string') {\n    return fail('expected \"player.avatarUrl\" to be a string or null');\n  }\n  return ok({ player: { id, displayName, avatarUrl } });\n};\n\nexport interface OAuthTokenResponseWire {\n  access_token: string;\n  token_type: 'Bearer';\n  expires_in: number;\n  scope: 'profile';\n}\n\nexport const parseOAuthTokenResponse: BodyParser<OAuthTokenResponseWire> = (body) => {\n  if (!isRecord(body)) return fail('expected a JSON object');\n  if (\n    typeof body.access_token !== 'string' ||\n    !/^[A-Za-z0-9_-]{43,128}$/u.test(body.access_token)\n  ) {\n    return fail('expected \"access_token\" to be a base64url token');\n  }\n  if (body.token_type !== 'Bearer') return fail('expected \"token_type\" to be \"Bearer\"');\n  if (!Number.isInteger(body.expires_in) || (body.expires_in as number) <= 0) {\n    return fail('expected \"expires_in\" to be a positive integer');\n  }\n  if (body.scope !== 'profile') return fail('expected \"scope\" to be \"profile\"');\n  return ok({\n    access_token: body.access_token,\n    token_type: 'Bearer',\n    expires_in: body.expires_in as number,\n    scope: 'profile',\n  });\n};\n\nexport const parseEmptyResponse: BodyParser<void> = (body) =>\n  body === undefined ? ok(undefined) : fail('expected an empty response body');\n\n/** `GET /health` → 200. OpenAPI: `{ status: 'ok', registration: enum, release?: /^[a-f0-9]{7,40}$/ }`. */\nexport interface HealthResponseWire {\n  status: 'ok';\n  registration: string;\n  release?: string;\n}\n\nexport const parseHealthResponse: BodyParser<HealthResponseWire> = (body) => {\n  if (!isRecord(body)) return fail('expected a JSON object');\n  if (body.status !== 'ok') return fail('expected \"status\" to be \"ok\"');\n  if (typeof body.registration !== 'string') return fail('expected \"registration\" to be a string');\n  if (body.release !== undefined && typeof body.release !== 'string') {\n    return fail('expected \"release\" to be a string when present');\n  }\n  return ok({\n    status: 'ok',\n    registration: body.registration,\n    ...(body.release === undefined ? {} : { release: body.release }),\n  });\n};\n\n/** Error envelope returned by every API error: `{ error: { code, message, requestId } }`. */\nexport interface ErrorEnvelopeWire {\n  error: { code: string; message: string; requestId: string };\n}\n\n/** Returns the envelope when `body` matches it, `null` otherwise (e.g. an HTML 502 from a proxy). */\nexport function parseErrorEnvelope(body: unknown): ErrorEnvelopeWire | null {\n  if (!isRecord(body) || !isRecord(body.error)) return null;\n  const { code, message, requestId } = body.error;\n  if (typeof code !== 'string' || typeof message !== 'string' || typeof requestId !== 'string') {\n    return null;\n  }\n  return { error: { code, message, requestId } };\n}\n"]}

package/dist/core/PixelumeClient.d.ts

@@ -1,3 +1,4 @@
+import { type PixelumeAuthApi, type PixelumeAuthState } from '../modules/auth/AuthModule.js';
 import { type PixelumeHealthApi } from '../modules/health/HealthModule.js';
 import type { PixelumeClientConfig, PixelumeClientOptions } from './types.js';
 /**
@@ -14,7 +15,16 @@ import type { PixelumeClientConfig, PixelumeClientOptions } from './types.js';
  * @throws {PixelumeConfigError} when the options are invalid.
  */
 export declare class PixelumeClient {
+    #private;
     readonly config: PixelumeClientConfig;
     readonly health: PixelumeHealthApi;
+    readonly auth: PixelumeAuthApi;
     constructor(options?: PixelumeClientOptions);
+    /**
+     * Initializes browser authentication once. Callback failures become an anonymous state so a
+     * game can always continue as a visitor; inspect `pixelume.auth.state.error` for diagnostics.
+     */
+    initialize(): Promise<PixelumeAuthState>;
 }
+/** Concise alias for new integrations; `PixelumeClient` remains supported. */
+export { PixelumeClient as Pixelume };

package/dist/core/PixelumeClient.js

@@ -1,4 +1,5 @@
 import { HttpClient } from '../http/HttpClient.js';
+import { AuthModule, } from '../modules/auth/AuthModule.js';
 import { HealthModule } from '../modules/health/HealthModule.js';
 import { resolveConfig } from './config.js';
 /**
@@ -17,11 +18,17 @@ import { resolveConfig } from './config.js';
 export class PixelumeClient {
     config;
     health;
+    auth;
+    #authModule;
     constructor(options = {}) {
         const resolved = resolveConfig(options);
         this.config = Object.freeze({
             apiUrl: resolved.apiUrl,
             gameId: resolved.gameId,
+            clientId: resolved.clientId,
+            redirectUri: resolved.redirectUri,
+            authUrl: resolved.authUrl,
+            restoreSession: resolved.restoreSession,
             timeoutMs: resolved.timeoutMs,
             credentials: resolved.credentials,
         });
@@ -32,6 +39,17 @@ export class PixelumeClient {
             credentials: resolved.credentials,
         });
         this.health = new HealthModule(http);
+        this.#authModule = new AuthModule(http, resolved);
+        this.auth = this.#authModule;
+    }
+    /**
+     * Initializes browser authentication once. Callback failures become an anonymous state so a
+     * game can always continue as a visitor; inspect `pixelume.auth.state.error` for diagnostics.
+     */
+    initialize() {
+        return this.#authModule.initialize();
     }
 }
+/** Concise alias for new integrations; `PixelumeClient` remains supported. */
+export { PixelumeClient as Pixelume };
 //# sourceMappingURL=PixelumeClient.js.map

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,EAAE,YAAY,EAA0B,MAAM,mCAAmC,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,cAAc;IAChB,MAAM,CAAuB;IAC7B,MAAM,CAAoB;IAEnC,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,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;IACvC,CAAC;CACF","sourcesContent":["import { HttpClient } from '../http/HttpClient.js';\nimport { HealthModule, type PixelumeHealthApi } from '../modules/health/HealthModule.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. Phase 1 ships only `health`; future modules\n * (authentication, saves…) will be added as new properties without changing existing ones.\n *\n * @throws {PixelumeConfigError} when the options are invalid.\n */\nexport class PixelumeClient {\n  readonly config: PixelumeClientConfig;\n  readonly health: PixelumeHealthApi;\n\n  constructor(options: PixelumeClientOptions = {}) {\n    const resolved = resolveConfig(options);\n    this.config = Object.freeze({\n      apiUrl: resolved.apiUrl,\n      gameId: resolved.gameId,\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  }\n}\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,UAAU,GAGX,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,YAAY,EAA0B,MAAM,mCAAmC,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,cAAc;IAChB,MAAM,CAAuB;IAC7B,MAAM,CAAoB;IAC1B,IAAI,CAAkB;IACtB,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,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;IAC/B,CAAC;IAED;;;OAGG;IACH,UAAU;QACR,OAAO,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC;IACvC,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 { 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. Phase 1 ships only `health`; future modules\n * (authentication, saves…) will be added as new properties without changing existing ones.\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  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      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  }\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/** Concise alias for new integrations; `PixelumeClient` remains supported. */\nexport { PixelumeClient as Pixelume };\n"]}

package/dist/core/config.d.ts

@@ -1,10 +1,17 @@
 import type { CredentialsPolicy, FetchLike } from '../http/types.js';
 import type { 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;
 export interface ResolvedConfig {
     apiUrl: string;
     gameId: string | null;
+    clientId: string | null;
+    redirectUri: string | null;
+    authUrl: string;
+    restoreSession: boolean;
+    allowInsecureHttp: boolean;
+    browser: PixelumeClientOptions['browser'];
     timeoutMs: number;
     credentials: CredentialsPolicy;
     fetch: FetchLike;
@@ -15,11 +22,13 @@ export declare function resolveConfig(options: PixelumeClientOptions): ResolvedC
  * `[::1]`). Other `http:` hosts (e.g. a LAN IP while testing on a phone) need `allowInsecureHttp`.
  */
 export declare function normalizeApiUrl(value: string, allowInsecureHttp: boolean): string;
+export declare function normalizeRedirectUri(value: string, allowInsecureHttp: boolean): string;
 /**
  * Game identifiers are public, non-secret slugs (e.g. `rail-puzzle`): lowercase letters, digits
  * and inner hyphens, 1–64 characters. They identify a game, they never authorize anything.
  */
 export declare function validateGameId(value: string): string;
+export declare function validateClientId(value: string): string;
 /** For feature modules that need a game context (future phases). */
 export declare function requireGameId(config: Pick<ResolvedConfig, 'gameId'>, feature: string): string;
 export declare function validateTimeout(value: number): number;