@pixelume/sdk 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,78 @@ conter mudanças incompatíveis, sempre listadas em **Changed/Removed**.
 
 ## [Unreleased]
 
+## [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
+
+- 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
@@ -65,7 +137,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.3.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

package/README.md

@@ -1,9 +1,10 @@
 # @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`.
+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
 
@@ -19,12 +20,14 @@ 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 headless
 
@@ -54,17 +57,52 @@ 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.
 
@@ -98,39 +136,87 @@ 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).
+`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.
+`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
 
 - 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.
+- 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.
-- `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.
 
+### 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 |
-| `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                                                                         |
 
 `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
@@ -150,16 +236,21 @@ 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. 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.
+- 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
 
@@ -168,8 +259,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
 
@@ -184,6 +278,7 @@ local, mas não diretamente de outro domínio no browser.
 
 | 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                        |
@@ -201,7 +296,9 @@ npm run verify
 npm run example:smoke # leitura opcional da API real
 ```
 
-Mais detalhes: [widget oficial](docs/phase-03-widget.md), [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"]}