@pixelume/sdk 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,65 @@ conter mudanças incompatíveis, sempre listadas em **Changed/Removed**.
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-14
+
+### Added
+
+- Renovação automática de sessão com os refresh tokens rotativos da Pixelume API: renovação proativa
+  (`expires_in − 60 s`, com jitter), verificação ao retomar a aba (`visibilitychange`, `pageshow`,
+  `online`), single-flight por instância, uma renovação + um único retry após `401`, retry único após
+  falha de rede/5xx, backoff para `429`/offline sem logout e encerramento explícito em `invalid_grant`
+  (`session_expired`) ou `invalid_client` (`game_unavailable`). Tokens permanecem só em memória.
+- `pixelume.auth.session`, `auth.subscribeSession()` e `auth.refresh()` para interfaces próprias
+  (escopos, expiração, renovação em andamento e falha transitória, sem expor tokens).
+- `pixelume.saves` (Cloud Saves): `list()`, `load()`, `save()` e `delete()` sobre
+  `/v1/games/:gameId/saves`, com validação local de slot/versão/revisão/JSON, `PixelumeSaveConflictError`
+  (`409`, com `current` e `expectedRevision`), exclusão idempotente (`'deleted' | 'not_found'`) e
+  atividade observável (`saves.activity`, `saves.subscribe()`) sem dados do save.
+- Opção `scope` (`'profile' | 'profile saves'`) no cliente e em `auth.login()`; a restauração após
+  reload reutiliza o escopo concedido.
+- `PixelumeClient.destroy()` para liberar timers e listeners.
+- `PixelumeHttpError.details` com os detalhes não sensíveis do envelope de erro da API
+  (`oauthError`, `quota`, metadados de conflito).
+- Widget: aviso de conexão durante falhas transitórias de renovação, mensagem para jogo indisponível e
+  status da nuvem somente após `saves.save()`/`saves.delete()` explícitos.
+- Exemplo Vite com status da sessão, painel de Cloud Saves e modo `?headless`.
+
+### Changed
+
+- `auth.logout()` revoga o refresh token (`token_type_hint=refresh_token`, com `client_id`), encerrando
+  toda a autorização do jogo; sem refresh token, revoga o access token como antes.
+- `auth.getPlayer()` renova a sessão em vez de declará-la expirada quando o access token vence ou a API
+  responde `401`; quando a sessão realmente termina, o estado `anonymous/expired` agora traz
+  `PixelumeAuthError` explícito em `error` (antes `null`).
+- O parser do token aceita `scope` `profile saves` e os campos opcionais `refresh_token` e
+  `refresh_token_expires_in`.
+- Uniões públicas ampliadas (aditivo, mas afeta `switch` exaustivo): `PixelumeAuthErrorReason` ganhou
+  `not_authenticated`, `session_expired`, `game_unavailable` e `renewal_rejected`;
+  `PixelumeApiErrorCode` ganhou os códigos de Cloud Saves e `OAUTH_UNSUPPORTED_GRANT_TYPE`.
+- A interface `PixelumeAuthApi` ganhou `session`, `subscribeSession()` e `refresh()`; implementações
+  próprias dessa interface (mocks) precisam acrescentá-los.
+- O marcador não sensível em `sessionStorage` passou a guardar o escopo concedido (`profile` ou
+  `profile saves`); o valor antigo `1` continua aceito.
+
+## [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
@@ -47,7 +106,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.2.0...HEAD
+[Unreleased]: https://github.com/ericksonnascimento/pixelume-sdk/compare/v0.4.0...HEAD
+[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
 [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,8 +1,10 @@
 # @pixelume/sdk
 
-SDK TypeScript headless para jogos web da Pixelume. A versão 0.2 adiciona autenticação centralizada
-com OAuth 2.0 Authorization Code + PKCE S256, além do cliente HTTP e health check da Fase 1. Não há
-dependências de runtime, componentes visuais, senha no jogo nem `client_secret`.
+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`.
 
 ## Instalação
 
@@ -18,14 +20,16 @@ CommonJS, use `await import('@pixelume/sdk')`.
 Antes de integrar um jogo, registre na Pixelume API:
 
 - 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.
+- os escopos: `profile` (obrigatório) e `saves` (somente se o jogo usar Cloud Saves);
+- cada callback completo por igualdade exata de scheme, host, porta, path e query, e as origens do jogo.
 
 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.
+`http://127.0.0.1:4173/oauth/callback`, apenas com `profile`. Jogos são cadastrados pelo Game Registry
+da API (`npm run admin:games` no repositório `pixelume-api`; veja `docs/GAME_REGISTRY.md` de lá). Em
+14/10/2026 nenhum cliente público tinha `saves` habilitado em produção.
 
-## Uso
+## Uso headless
 
 ```ts
 import { Pixelume, isPixelumeError } from '@pixelume/sdk';
@@ -53,17 +57,89 @@ loginButton.addEventListener('click', () => {
 
 logoutButton.addEventListener('click', async () => {
   try {
-    await pixelume.auth.logout(); // revoga somente o token deste jogo
+    await pixelume.auth.logout(); // revoga somente a autorização deste jogo
   } catch (error) {
     if (!isPixelumeError(error)) throw error;
     showRecoverableError(error.kind);
   }
 });
 
-// Ao desmontar a tela:
+// Ao desmontar a tela/jogo:
 unsubscribe();
+pixelume.destroy(); // cancela timers de renovação e listeners (não revoga)
 ```
 
+### Sessões longas
+
+Nada a fazer: o SDK renova o access token (10 min) antes de expirar, ao retomar a aba e após um `401`,
+com uma única renovação por vez e um único retry da requisição. Falhas de rede mantêm o jogador
+conectado (`pixelume.auth.session.error`); sessão revogada/expirada vira `anonymous/expired` com erro
+explícito. Detalhes: [renovação de sessão](docs/SESSION_RENEWAL.md).
+
+```ts
+pixelume.auth.subscribeSession((session) => {
+  connectionBanner.hidden = session.error === null; // recuperável, sem logout
+});
+```
+
+## Cloud Saves
+
+```ts
+const pixelume = new Pixelume({ gameId: 'rail-puzzle', scope: 'profile saves' });
+await pixelume.initialize();
+
+const current = await pixelume.saves.load<{ level: number }>('main'); // ou null
+await pixelume.saves.save('main', {
+  schemaVersion: 1,
+  expectedRevision: current?.revision ?? 0, // 0 cria; n atualiza só a revisão n
+  data: { level: 12 },
+});
+const { saves, limits, usage } = await pixelume.saves.list();
+await pixelume.saves.delete('old-slot', { expectedRevision: 3 }); // 'deleted' | 'not_found'
+```
+
+Conflitos (`409`) rejeitam com `PixelumeSaveConflictError` (revisão remota em `error.current`); o SDK
+nunca sobrescreve, mescla ou reenvia sozinho, e não há fila offline. Saves são dados pessoais não
+verificados: não servem como prova de conquista, ranking ou prêmio. Guia completo:
+[Cloud Saves](docs/CLOUD_SAVES.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.
+
+## Widget opcional
+
+```ts
+import { Pixelume } from '@pixelume/sdk';
+import { mountPixelumeWidget } from '@pixelume/sdk/ui';
+
+const pixelume = new Pixelume({
+  gameId: 'rail-puzzle',
+  redirectUri: 'https://rail-puzzle.pixelume.com.br/oauth/callback',
+});
+
+await pixelume.initialize();
+
+const widget = mountPixelumeWidget(pixelume, {
+  position: 'bottom-right',
+  offset: 16,
+  theme: 'pixel',
+});
+
+// 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). O widget também mostra
+avisos de conexão durante a renovação e, apenas depois de `saves.save()`/`saves.delete()` explícitos, o
+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.
@@ -71,14 +147,17 @@ unsubscribe();
 ### 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**.
+- O access token opaco dura 10 minutos e é renovado automaticamente pelo refresh token rotativo; os dois
+  ficam **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.
+  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.
 - 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
+- `logout()` limpa o estado local imediatamente, cancela a renovação e revoga o refresh token em
+  `/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.
 
 ## Configuração
@@ -90,6 +169,7 @@ unsubscribe();
 | `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              |
@@ -114,16 +194,20 @@ 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`.
+- O fluxo não é OIDC: não há ID Token, discovery nem `client_secret`. O refresh token é rotativo, de uso
+  único, ligado ao jogo e à sessão central, e fica só em memória.
 - 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.
+- 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.
 - 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.
+- 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.
 
 ## Erros
 
@@ -132,8 +216,11 @@ Todo erro lançado diretamente pelo SDK é `PixelumeError`. Os `kind` estáveis
 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`.
+O único retry automático é o da renovação de sessão: após `401` em uma rota autenticada, o SDK renova uma
+vez e repete aquela requisição uma vez. Nada mais é repetido. Para 400/403/409/413/429/5xx, use
+`PixelumeHttpError.status`, `code`, `details` e `requestId`; conflitos de save são
+`PixelumeSaveConflictError`; sessões encerradas são `PixelumeAuthError` (`session_expired`,
+`game_unavailable`, `renewal_rejected`, `not_authenticated`). Para cancelamento, use `AbortSignal`.
 
 ## Health check
 
@@ -146,10 +233,12 @@ local, mas não diretamente de outro domínio no browser.
 
 ## Compatibilidade
 
-| SDK     | Pixelume API                                         | Pixelume Auth                  | Recursos                         |
-| ------- | ---------------------------------------------------- | ------------------------------ | -------------------------------- |
-| `0.2.x` | OpenAPI `0.4.0`, release SSO `3846479` ou compatível | Fase 2 `dd5a8e5` ou compatível | SSO PKCE, perfil, logout, health |
-| `0.1.x` | API anterior/atual para `/health`                    | não consumido                  | fundação e health apenas         |
+| SDK     | Pixelume API                                         | Pixelume Auth                  | Recursos                                        |
+| ------- | ---------------------------------------------------- | ------------------------------ | ----------------------------------------------- |
+| `0.4.x` | OpenAPI `0.6.0`, release `10752b8` ou compatível     | Fase 2 `3a1ded4` ou compatível | Renovação de sessão, Cloud Saves, widget, SSO   |
+| `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                        |
 
 Como o pacote ainda está em `0.x`, mudanças incompatíveis usam incremento _minor_ e são listadas no
 [CHANGELOG](CHANGELOG.md).
@@ -164,7 +253,9 @@ npm run verify
 npm run example:smoke # leitura opcional da API real
 ```
 
-Mais detalhes: [integração SSO](docs/SSO_INTEGRATION.md),
+Mais detalhes: [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
 [publicação](docs/publishing.md).
 

package/dist/contracts/index.d.ts

@@ -25,11 +25,17 @@ export interface PlayerEnvelopeWire {
     player: PlayerWire;
 }
 export declare const parsePlayerEnvelope: BodyParser<PlayerEnvelopeWire>;
+/** Scopes the API can grant. `profile` is always present; `saves` is opt-in per game. */
+export type OAuthScopeWire = 'profile' | 'saves';
 export interface OAuthTokenResponseWire {
     access_token: string;
     token_type: 'Bearer';
     expires_in: number;
-    scope: 'profile';
+    /** Granted scopes, parsed from the space-separated `scope` field. */
+    scopes: readonly OAuthScopeWire[];
+    /** Rotating refresh token; absent for legacy codes or when the central session already ended. */
+    refresh_token?: string;
+    refresh_token_expires_in?: number;
 }
 export declare const parseOAuthTokenResponse: BodyParser<OAuthTokenResponseWire>;
 export declare const parseEmptyResponse: BodyParser<void>;
@@ -40,13 +46,47 @@ export interface HealthResponseWire {
     release?: string;
 }
 export declare const parseHealthResponse: BodyParser<HealthResponseWire>;
-/** Error envelope returned by every API error: `{ error: { code, message, requestId } }`. */
+/** Error envelope returned by every API error: `{ error: { code, message, requestId, details? } }`. */
 export interface ErrorEnvelopeWire {
     error: {
         code: string;
         message: string;
         requestId: string;
+        details: Readonly<Record<string, unknown>> | null;
     };
 }
 /** Returns the envelope when `body` matches it, `null` otherwise (e.g. an HTML 502 from a proxy). */
 export declare function parseErrorEnvelope(body: unknown): ErrorEnvelopeWire | null;
+export interface SaveMetadataWire {
+    gameId: string;
+    slotId: string;
+    schemaVersion: number;
+    revision: number;
+    sizeBytes: number;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface CloudSaveWire extends SaveMetadataWire {
+    data: Record<string, unknown>;
+}
+export interface SaveListWire {
+    gameId: string;
+    saves: SaveMetadataWire[];
+    limits: {
+        maxSlotsPerGame: number;
+        maxDataBytes: number;
+        maxBytesPerPlayer: number;
+    };
+    usage: {
+        slots: number;
+        playerBytes: number;
+    };
+}
+/** Validates one `SaveMetadata` object; `null` when it does not match. */
+export declare function parseSaveMetadata(value: unknown): SaveMetadataWire | null;
+/** `PUT` → `{ save: SaveMetadata }`. */
+export declare const parseSaveMetadataEnvelope: BodyParser<SaveMetadataWire>;
+/** `GET /saves/:slotId` → `{ save: SaveMetadata & { data } }`. */
+export declare const parseCloudSaveEnvelope: BodyParser<CloudSaveWire>;
+/** `GET /saves` → `{ gameId, saves, limits, usage }`. */
+export declare const parseSaveList: BodyParser<SaveListWire>;

package/dist/contracts/index.js

@@ -27,11 +27,12 @@ export const parsePlayerEnvelope = (body) => {
     }
     return ok({ player: { id, displayName, avatarUrl } });
 };
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]{43,128}$/u;
+const KNOWN_SCOPES = ['profile', 'saves'];
 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)) {
+    if (typeof body.access_token !== 'string' || !TOKEN_PATTERN.test(body.access_token)) {
         return fail('expected "access_token" to be a base64url token');
     }
     if (body.token_type !== 'Bearer')
@@ -39,13 +40,34 @@ export const parseOAuthTokenResponse = (body) => {
     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({
+    const scopes = typeof body.scope === 'string' ? body.scope.split(' ') : [];
+    if (!scopes.includes('profile') ||
+        new Set(scopes).size !== scopes.length ||
+        !scopes.every((scope) => KNOWN_SCOPES.includes(scope))) {
+        return fail('expected "scope" to be "profile" or "profile saves"');
+    }
+    const result = {
         access_token: body.access_token,
         token_type: 'Bearer',
         expires_in: body.expires_in,
-        scope: 'profile',
+        scopes: scopes,
+    };
+    if (body.refresh_token === undefined)
+        return ok(result);
+    if (typeof body.refresh_token !== 'string' || !TOKEN_PATTERN.test(body.refresh_token)) {
+        return fail('expected "refresh_token" to be a base64url token when present');
+    }
+    const refreshExpiresIn = body.refresh_token_expires_in;
+    if (refreshExpiresIn !== undefined &&
+        (!Number.isInteger(refreshExpiresIn) || refreshExpiresIn < 0)) {
+        return fail('expected "refresh_token_expires_in" to be a non-negative integer when present');
+    }
+    return ok({
+        ...result,
+        refresh_token: body.refresh_token,
+        ...(refreshExpiresIn === undefined
+            ? {}
+            : { refresh_token_expires_in: refreshExpiresIn }),
     });
 };
 export const parseEmptyResponse = (body) => body === undefined ? ok(undefined) : fail('expected an empty response body');
@@ -69,10 +91,87 @@ export const parseHealthResponse = (body) => {
 export function parseErrorEnvelope(body) {
     if (!isRecord(body) || !isRecord(body.error))
         return null;
-    const { code, message, requestId } = body.error;
+    const { code, message, requestId, details } = body.error;
     if (typeof code !== 'string' || typeof message !== 'string' || typeof requestId !== 'string') {
         return null;
     }
-    return { error: { code, message, requestId } };
+    return { error: { code, message, requestId, details: isRecord(details) ? details : null } };
+}
+function isNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+}
+function isTimestamp(value) {
+    return typeof value === 'string' && !Number.isNaN(Date.parse(value));
+}
+/** Validates one `SaveMetadata` object; `null` when it does not match. */
+export function parseSaveMetadata(value) {
+    if (!isRecord(value))
+        return null;
+    const { gameId, slotId, schemaVersion, revision, sizeBytes, createdAt, updatedAt } = value;
+    if (typeof gameId !== 'string' ||
+        typeof slotId !== 'string' ||
+        !isNonNegativeInteger(schemaVersion) ||
+        schemaVersion < 1 ||
+        !isNonNegativeInteger(revision) ||
+        revision < 1 ||
+        !isNonNegativeInteger(sizeBytes) ||
+        !isTimestamp(createdAt) ||
+        !isTimestamp(updatedAt)) {
+        return null;
+    }
+    return { gameId, slotId, schemaVersion, revision, sizeBytes, createdAt, updatedAt };
 }
+/** `PUT` → `{ save: SaveMetadata }`. */
+export const parseSaveMetadataEnvelope = (body) => {
+    const save = isRecord(body) ? parseSaveMetadata(body.save) : null;
+    return save ? ok(save) : fail('expected a JSON object containing "save" metadata');
+};
+/** `GET /saves/:slotId` → `{ save: SaveMetadata & { data } }`. */
+export const parseCloudSaveEnvelope = (body) => {
+    if (!isRecord(body) || !isRecord(body.save)) {
+        return fail('expected a JSON object containing "save"');
+    }
+    const metadata = parseSaveMetadata(body.save);
+    if (!metadata)
+        return fail('expected "save" to contain valid save metadata');
+    const data = body.save.data;
+    if (!isRecord(data))
+        return fail('expected "save.data" to be a JSON object');
+    return ok({ ...metadata, data });
+};
+/** `GET /saves` → `{ gameId, saves, limits, usage }`. */
+export const parseSaveList = (body) => {
+    if (!isRecord(body) || typeof body.gameId !== 'string' || !Array.isArray(body.saves)) {
+        return fail('expected a JSON object containing "gameId" and "saves"');
+    }
+    const saves = [];
+    for (const entry of body.saves) {
+        const save = parseSaveMetadata(entry);
+        if (!save)
+            return fail('expected every entry of "saves" to be save metadata');
+        saves.push(save);
+    }
+    const { limits, usage } = body;
+    if (!isRecord(limits) ||
+        !isNonNegativeInteger(limits.maxSlotsPerGame) ||
+        !isNonNegativeInteger(limits.maxDataBytes) ||
+        !isNonNegativeInteger(limits.maxBytesPerPlayer)) {
+        return fail('expected "limits" to contain non-negative integers');
+    }
+    if (!isRecord(usage) ||
+        !isNonNegativeInteger(usage.slots) ||
+        !isNonNegativeInteger(usage.playerBytes)) {
+        return fail('expected "usage" to contain non-negative integers');
+    }
+    return ok({
+        gameId: body.gameId,
+        saves,
+        limits: {
+            maxSlotsPerGame: limits.maxSlotsPerGame,
+            maxDataBytes: limits.maxDataBytes,
+            maxBytesPerPlayer: limits.maxBytesPerPlayer,
+        },
+        usage: { slots: usage.slots, playerBytes: usage.playerBytes },
+    });
+};
 //# sourceMappingURL=index.js.map

package/dist/contracts/index.js.map

@@ -1 +1 @@
-{"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"]}
+{"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\n/** Scopes the API can grant. `profile` is always present; `saves` is opt-in per game. */\nexport type OAuthScopeWire = 'profile' | 'saves';\n\nexport interface OAuthTokenResponseWire {\n  access_token: string;\n  token_type: 'Bearer';\n  expires_in: number;\n  /** Granted scopes, parsed from the space-separated `scope` field. */\n  scopes: readonly OAuthScopeWire[];\n  /** Rotating refresh token; absent for legacy codes or when the central session already ended. */\n  refresh_token?: string;\n  refresh_token_expires_in?: number;\n}\n\nconst TOKEN_PATTERN = /^[A-Za-z0-9_-]{43,128}$/u;\nconst KNOWN_SCOPES: readonly string[] = ['profile', 'saves'];\n\nexport const parseOAuthTokenResponse: BodyParser<OAuthTokenResponseWire> = (body) => {\n  if (!isRecord(body)) return fail('expected a JSON object');\n  if (typeof body.access_token !== 'string' || !TOKEN_PATTERN.test(body.access_token)) {\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  const scopes = typeof body.scope === 'string' ? body.scope.split(' ') : [];\n  if (\n    !scopes.includes('profile') ||\n    new Set(scopes).size !== scopes.length ||\n    !scopes.every((scope) => KNOWN_SCOPES.includes(scope))\n  ) {\n    return fail('expected \"scope\" to be \"profile\" or \"profile saves\"');\n  }\n  const result: OAuthTokenResponseWire = {\n    access_token: body.access_token,\n    token_type: 'Bearer',\n    expires_in: body.expires_in as number,\n    scopes: scopes as OAuthScopeWire[],\n  };\n  if (body.refresh_token === undefined) return ok(result);\n  if (typeof body.refresh_token !== 'string' || !TOKEN_PATTERN.test(body.refresh_token)) {\n    return fail('expected \"refresh_token\" to be a base64url token when present');\n  }\n  const refreshExpiresIn = body.refresh_token_expires_in;\n  if (\n    refreshExpiresIn !== undefined &&\n    (!Number.isInteger(refreshExpiresIn) || (refreshExpiresIn as number) < 0)\n  ) {\n    return fail('expected \"refresh_token_expires_in\" to be a non-negative integer when present');\n  }\n  return ok({\n    ...result,\n    refresh_token: body.refresh_token,\n    ...(refreshExpiresIn === undefined\n      ? {}\n      : { refresh_token_expires_in: refreshExpiresIn as number }),\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, details? } }`. */\nexport interface ErrorEnvelopeWire {\n  error: {\n    code: string;\n    message: string;\n    requestId: string;\n    details: Readonly<Record<string, unknown>> | null;\n  };\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, details } = body.error;\n  if (typeof code !== 'string' || typeof message !== 'string' || typeof requestId !== 'string') {\n    return null;\n  }\n  return { error: { code, message, requestId, details: isRecord(details) ? details : null } };\n}\n\n// ---------------------------------------------------------------------------------------------\n// Cloud Saves (`/v1/games/:gameId/saves`). OpenAPI: SaveMetadata, CloudSave, SaveListResponse.\n// ---------------------------------------------------------------------------------------------\n\nexport interface SaveMetadataWire {\n  gameId: string;\n  slotId: string;\n  schemaVersion: number;\n  revision: number;\n  sizeBytes: number;\n  createdAt: string;\n  updatedAt: string;\n}\n\nexport interface CloudSaveWire extends SaveMetadataWire {\n  data: Record<string, unknown>;\n}\n\nexport interface SaveListWire {\n  gameId: string;\n  saves: SaveMetadataWire[];\n  limits: { maxSlotsPerGame: number; maxDataBytes: number; maxBytesPerPlayer: number };\n  usage: { slots: number; playerBytes: number };\n}\n\nfunction isNonNegativeInteger(value: unknown): value is number {\n  return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;\n}\n\nfunction isTimestamp(value: unknown): value is string {\n  return typeof value === 'string' && !Number.isNaN(Date.parse(value));\n}\n\n/** Validates one `SaveMetadata` object; `null` when it does not match. */\nexport function parseSaveMetadata(value: unknown): SaveMetadataWire | null {\n  if (!isRecord(value)) return null;\n  const { gameId, slotId, schemaVersion, revision, sizeBytes, createdAt, updatedAt } = value;\n  if (\n    typeof gameId !== 'string' ||\n    typeof slotId !== 'string' ||\n    !isNonNegativeInteger(schemaVersion) ||\n    schemaVersion < 1 ||\n    !isNonNegativeInteger(revision) ||\n    revision < 1 ||\n    !isNonNegativeInteger(sizeBytes) ||\n    !isTimestamp(createdAt) ||\n    !isTimestamp(updatedAt)\n  ) {\n    return null;\n  }\n  return { gameId, slotId, schemaVersion, revision, sizeBytes, createdAt, updatedAt };\n}\n\n/** `PUT` → `{ save: SaveMetadata }`. */\nexport const parseSaveMetadataEnvelope: BodyParser<SaveMetadataWire> = (body) => {\n  const save = isRecord(body) ? parseSaveMetadata(body.save) : null;\n  return save ? ok(save) : fail('expected a JSON object containing \"save\" metadata');\n};\n\n/** `GET /saves/:slotId` → `{ save: SaveMetadata & { data } }`. */\nexport const parseCloudSaveEnvelope: BodyParser<CloudSaveWire> = (body) => {\n  if (!isRecord(body) || !isRecord(body.save)) {\n    return fail('expected a JSON object containing \"save\"');\n  }\n  const metadata = parseSaveMetadata(body.save);\n  if (!metadata) return fail('expected \"save\" to contain valid save metadata');\n  const data = body.save.data;\n  if (!isRecord(data)) return fail('expected \"save.data\" to be a JSON object');\n  return ok({ ...metadata, data });\n};\n\n/** `GET /saves` → `{ gameId, saves, limits, usage }`. */\nexport const parseSaveList: BodyParser<SaveListWire> = (body) => {\n  if (!isRecord(body) || typeof body.gameId !== 'string' || !Array.isArray(body.saves)) {\n    return fail('expected a JSON object containing \"gameId\" and \"saves\"');\n  }\n  const saves: SaveMetadataWire[] = [];\n  for (const entry of body.saves) {\n    const save = parseSaveMetadata(entry);\n    if (!save) return fail('expected every entry of \"saves\" to be save metadata');\n    saves.push(save);\n  }\n  const { limits, usage } = body;\n  if (\n    !isRecord(limits) ||\n    !isNonNegativeInteger(limits.maxSlotsPerGame) ||\n    !isNonNegativeInteger(limits.maxDataBytes) ||\n    !isNonNegativeInteger(limits.maxBytesPerPlayer)\n  ) {\n    return fail('expected \"limits\" to contain non-negative integers');\n  }\n  if (\n    !isRecord(usage) ||\n    !isNonNegativeInteger(usage.slots) ||\n    !isNonNegativeInteger(usage.playerBytes)\n  ) {\n    return fail('expected \"usage\" to contain non-negative integers');\n  }\n  return ok({\n    gameId: body.gameId,\n    saves,\n    limits: {\n      maxSlotsPerGame: limits.maxSlotsPerGame,\n      maxDataBytes: limits.maxDataBytes,\n      maxBytesPerPlayer: limits.maxBytesPerPlayer,\n    },\n    usage: { slots: usage.slots, playerBytes: usage.playerBytes },\n  });\n};\n"]}

package/dist/core/PixelumeClient.d.ts

@@ -1,5 +1,6 @@
 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';
 import type { PixelumeClientConfig, PixelumeClientOptions } from './types.js';
 /**
  * Entry point of the SDK. Create one instance per API/game and share it.
@@ -9,8 +10,9 @@ import type { PixelumeClientConfig, PixelumeClientOptions } from './types.js';
  * const health = await pixelume.health.check();
  * ```
  *
- * Feature modules are exposed as read-only properties. Phase 1 ships only `health`; future modules
- * (authentication, saves…) will be added as new properties without changing existing ones.
+ * Feature modules are exposed as read-only properties: `health`, `auth` and `saves`. 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.
  *
  * @throws {PixelumeConfigError} when the options are invalid.
  */
@@ -19,12 +21,20 @@ export declare class PixelumeClient {
     readonly config: PixelumeClientConfig;
     readonly health: PixelumeHealthApi;
     readonly auth: PixelumeAuthApi;
+    /** Cloud Saves of the signed-in player for `gameId` (requires the `saves` scope). */
+    readonly saves: PixelumeSavesApi;
     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>;
+    /**
+     * 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.
+     */
+    destroy(): void;
 }
 /** Concise alias for new integrations; `PixelumeClient` remains supported. */
 export { PixelumeClient as Pixelume };