@pixelume/sdk 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+Todas as mudanças relevantes deste pacote são documentadas aqui.
+O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/) e o projeto usa
+[Semantic Versioning](https://semver.org/lang/pt-BR/). Antes da 1.0.0, versões _minor_ podem
+conter mudanças incompatíveis, sempre listadas em **Changed/Removed**.
+
+## [Unreleased]
+
+## [0.1.1] - 2026-10-13
+
+### Changed
+
+- README do pacote: instalação a partir do npm (a 0.1.0 trazia a instrução provisória de instalar
+  via `npm pack`). Sem mudanças de código ou de API pública.
+- Primeira versão publicada pelo workflow de release com npm Trusted Publishing (OIDC).
+
+## [0.1.0] - 2026-10-13
+
+### Added
+
+- `PixelumeClient` com configuração validada: `apiUrl` (HTTPS; HTTP apenas em loopback ou com
+  `allowInsecureHttp`), `gameId` opcional (slug público), `timeoutMs`, política de `credentials`
+  e `fetch` injetável.
+- `client.health.check()` para `GET /health` da Pixelume API, com validação do contrato.
+- Cliente HTTP interno com timeout, propagação de `AbortSignal`, tratamento de JSON/texto/corpo
+  vazio e sem retries automáticos.
+- Hierarquia de erros `PixelumeError` (`config`, `http`, `network`, `timeout`, `aborted`,
+  `invalid_response`) e `isPixelumeError()`.
+- Build ESM + `.d.ts`, CI e workflow de publicação via npm Trusted Publishing.
+
+[Unreleased]: https://github.com/ericksonnascimento/pixelume-sdk/compare/v0.1.1...HEAD
+[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/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2026 Erickson Nascimento / Pixelume. All rights reserved.
+
+PROPRIETARY AND CONFIDENTIAL — NOT OPEN SOURCE.
+
+This software package ("@pixelume/sdk"), including its source code, compiled
+code, type declarations and documentation, is the exclusive property of the
+copyright holder.
+
+Permission is granted only to games and applications developed or explicitly
+authorized by Pixelume to install this package and include its compiled code
+in their distributed builds, solely to integrate with Pixelume services.
+
+Except as stated above, no permission is granted to copy, modify, merge,
+publish, distribute, sublicense, sell, reverse engineer or create derivative
+works of this software, in whole or in part, without the prior written
+consent of the copyright holder. Availability of the package on a public
+registry does not grant any additional rights.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
+# @pixelume/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK TypeScript dos jogos web do estúdio **Pixelume**. Fornece um cliente tipado, seguro e sem
+dependências de runtime para a [Pixelume API](https://api.pixelume.com.br), independente de framework ou
+engine (funciona com Vite, Three.js, React, JavaScript puro, SSR e workers).
+
+> **Status: Fase 1 — fundação.** Esta versão oferece configuração, cliente HTTP, erros padronizados e a
+> checagem de disponibilidade da API. Login, sessão, cloud saves e analytics **ainda não existem** e
+> serão adicionados quando os contratos da API estiverem prontos (veja o [roadmap](docs/roadmap.md)).
+
+## Capacidades
+
+| Capacidade                                   | Fase 1 | Observação                                              |
+| -------------------------------------------- | :----: | ------------------------------------------------------- |
+| `PixelumeClient` com configuração validada   |   ✅   | `apiUrl`, `gameId`, `timeoutMs`, `credentials`, `fetch` |
+| `client.health.check()` (`GET /health`)      |   ✅   | sem CORS na API: servidor/mesma origem (ver abaixo)     |
+| Erros padronizados, timeout e cancelamento   |   ✅   | `PixelumeError` + `kind`                                |
+| Autenticação / Pixelume Auth                 |   —    | aguarda portal central e contratos de redirect          |
+| Cloud saves, analytics, rankings, conquistas |   —    | aguardam contratos na API                               |
+
+## Pré-requisitos
+
+- Navegadores modernos (Chrome/Edge 98+, Firefox 97+, Safari 15.4+) ou Node.js 22+, Deno, Bun, Workers.
+- Projeto ESM (o pacote é ESM-only, com tipos incluídos). Em CommonJS use `await import('@pixelume/sdk')`.
+
+## Instalação
+
+```bash
+npm install @pixelume/sdk
+```
+
+Publicado no npm: [`@pixelume/sdk`](https://www.npmjs.com/package/@pixelume/sdk) (versão atual `0.1.0`).
+
+## Uso
+
+```ts
+import { PixelumeClient } from '@pixelume/sdk';
+
+const pixelume = new PixelumeClient({
+  apiUrl: 'https://api.pixelume.com.br', // padrão
+  gameId: 'rail-puzzle', // opcional nesta fase
+});
+
+const health = await pixelume.health.check();
+// { status: 'ok', registration: 'email-verification', release: 'd99d195…' }
+```
+
+Saída real obtida pelo exemplo em 2026-10-13 (Node.js, pacote instalado via `npm pack`):
+
+```json
+{
+  "sdk": "0.1.0",
+  "apiUrl": "https://api.pixelume.com.br",
+  "health": {
+    "status": "ok",
+    "registration": "email-verification",
+    "release": "d99d19543620f09309268f67d959e874ddc78ecf"
+  }
+}
+```
+
+### `health.check()` no navegador
+
+A API ainda **não envia cabeçalhos CORS em `/health`** (só em `/v1/*`). Em uma página servida por outra
+origem, o navegador bloqueia a resposta e o SDK rejeita com `PixelumeNetworkError`. Use `health.check()`
+no servidor (Node/SSR/workers), em ferramentas, ou na mesma origem via proxy — o
+[exemplo Vite](examples/vite-basic) usa o proxy do `vite dev`. A correção depende da API
+([auditoria](docs/api-contract-audit.md)).
+
+### Configuração
+
+| Opção               | Padrão                        | Descrição                                                                                    |
+| ------------------- | ----------------------------- | -------------------------------------------------------------------------------------------- |
+| `apiUrl`            | `https://api.pixelume.com.br` | `https:` obrigatório; `http:` aceito só para `localhost`/`127.0.0.1`/`[::1]`/`*.localhost`.  |
+| `gameId`            | —                             | slug público (`a-z`, `0-9`, `-`, até 64). Identifica o jogo; **não** é credencial.           |
+| `timeoutMs`         | `10000`                       | tempo máximo de cada operação, incluindo leitura do corpo.                                   |
+| `credentials`       | `'omit'`                      | política de cookies do `fetch` para módulos futuros. O SDK não presume cookies cross-origin. |
+| `fetch`             | `globalThis.fetch`            | implementação injetável (testes, SSR, instrumentação).                                       |
+| `allowInsecureHttp` | `false`                       | permite `http:` em hosts não-loopback (ex.: IP da LAN). Nunca em produção.                   |
+
+Opções inválidas lançam `PixelumeConfigError` no construtor. Cada operação aceita
+`{ signal?: AbortSignal; timeoutMs?: number }`.
+
+### Erros
+
+Todas as falhas são `PixelumeError` com um `kind` estável:
+
+```ts
+import { isPixelumeError } from '@pixelume/sdk';
+
+const controller = new AbortController();
+try {
+  await pixelume.health.check({ signal: controller.signal, timeoutMs: 5_000 });
+} catch (error) {
+  if (!isPixelumeError(error)) throw error;
+  switch (error.kind) {
+    case 'http': // error.status, error.code ('RATE_LIMITED'…), error.requestId
+    case 'network': // offline, DNS/TLS ou bloqueio de CORS
+    case 'timeout': // error.timeoutMs
+    case 'aborted': // cancelado pelo AbortSignal
+    case 'invalid_response': // a API respondeu fora do contrato
+    case 'config': // configuração inválida
+  }
+}
+```
+
+Mensagens de erro não incluem corpo, cookies, cabeçalhos nem query string. O corpo bruto fica em
+`PixelumeHttpError.payload`, propriedade não enumerável (não aparece em `JSON.stringify`). O SDK nunca
+escreve no console.
+
+## Segurança
+
+- O SDK não contém nem aceita API keys, tokens administrativos ou senhas.
+- `gameId` é público; autorização sempre vem da API.
+- Não há fluxo de login com senha dentro do jogo — e não haverá: o login será feito pelo Pixelume Auth.
+- O SDK não define `Origin`/`Referer`/`Cookie` e não trata CORS como segurança.
+
+## Desenvolvimento
+
+Requer Node.js 24 (`.nvmrc`).
+
+```bash
+npm ci
+npm run lint         # ESLint + Prettier
+npm run typecheck
+npm test             # unitários + integração com servidor HTTP local (sem rede)
+npm run build        # dist/ (ESM + .d.ts + sourcemaps)
+npm run check:package  # dist browser-safe, conteúdo do tarball, publint, attw
+npm run example:prepare && npm run example:build   # instala o .tgz no exemplo e compila
+npm run example:smoke  # exemplo Node contra a API real (rede)
+npm run test:live      # teste opcional contra a API real (rede)
+npm run verify       # tudo o que a CI executa
+```
+
+## Documentação
+
+- [Arquitetura e decisões técnicas](docs/architecture.md)
+- [Auditoria de contratos da API](docs/api-contract-audit.md)
+- [Publicação, CI/CD e rollback](docs/publishing.md)
+- [Roadmap](docs/roadmap.md)
+- [Changelog](CHANGELOG.md)
+
+## Licença
+
+Proprietária — todos os direitos reservados. Veja [LICENSE](LICENSE). A disponibilidade pública no npm
+não concede direitos além dos descritos na licença.

package/dist/contracts/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Wire contracts of the Pixelume API used by the SDK, with hand-written runtime guards.
+ *
+ * Source of truth: `pixelume-api` (`docs/openapi.yaml` and `src/interfaces/http/app.ts`).
+ * See `docs/api-contract-audit.md`. These types describe JSON on the wire and are internal;
+ * public modules map them to SDK types so the API can evolve without breaking consumers.
+ *
+ * Validation is intentionally tolerant to *additive* changes (unknown fields are ignored,
+ * unknown enum values are accepted as strings) and strict about the fields the SDK relies on.
+ */
+export type ParseResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export type BodyParser<T> = (body: unknown) => ParseResult<T>;
+/** `GET /health` → 200. OpenAPI: `{ status: 'ok', registration: enum, release?: /^[a-f0-9]{7,40}$/ }`. */
+export interface HealthResponseWire {
+    status: 'ok';
+    registration: string;
+    release?: string;
+}
+export declare const parseHealthResponse: BodyParser<HealthResponseWire>;
+/** Error envelope returned by every API error: `{ error: { code, message, requestId } }`. */
+export interface ErrorEnvelopeWire {
+    error: {
+        code: string;
+        message: string;
+        requestId: string;
+    };
+}
+/** 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;

package/dist/contracts/index.js

@@ -0,0 +1,42 @@
+/**
+ * Wire contracts of the Pixelume API used by the SDK, with hand-written runtime guards.
+ *
+ * Source of truth: `pixelume-api` (`docs/openapi.yaml` and `src/interfaces/http/app.ts`).
+ * See `docs/api-contract-audit.md`. These types describe JSON on the wire and are internal;
+ * public modules map them to SDK types so the API can evolve without breaking consumers.
+ *
+ * Validation is intentionally tolerant to *additive* changes (unknown fields are ignored,
+ * unknown enum values are accepted as strings) and strict about the fields the SDK relies on.
+ */
+const ok = (value) => ({ ok: true, value });
+const fail = (reason) => ({ ok: false, reason });
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export const parseHealthResponse = (body) => {
+    if (!isRecord(body))
+        return fail('expected a JSON object');
+    if (body.status !== 'ok')
+        return fail('expected "status" to be "ok"');
+    if (typeof body.registration !== 'string')
+        return fail('expected "registration" to be a string');
+    if (body.release !== undefined && typeof body.release !== 'string') {
+        return fail('expected "release" to be a string when present');
+    }
+    return ok({
+        status: 'ok',
+        registration: body.registration,
+        ...(body.release === undefined ? {} : { release: body.release }),
+    });
+};
+/** Returns the envelope when `body` matches it, `null` otherwise (e.g. an HTML 502 from a proxy). */
+export function parseErrorEnvelope(body) {
+    if (!isRecord(body) || !isRecord(body.error))
+        return null;
+    const { code, message, requestId } = body.error;
+    if (typeof code !== 'string' || typeof message !== 'string' || typeof requestId !== 'string') {
+        return null;
+    }
+    return { error: { code, message, requestId } };
+}
+//# sourceMappingURL=index.js.map

package/dist/contracts/index.js.map

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

package/dist/core/PixelumeClient.d.ts

@@ -0,0 +1,20 @@
+import { type PixelumeHealthApi } from '../modules/health/HealthModule.js';
+import type { PixelumeClientConfig, PixelumeClientOptions } from './types.js';
+/**
+ * Entry point of the SDK. Create one instance per API/game and share it.
+ *
+ * ```ts
+ * const pixelume = new PixelumeClient({ gameId: 'rail-puzzle' });
+ * 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.
+ *
+ * @throws {PixelumeConfigError} when the options are invalid.
+ */
+export declare class PixelumeClient {
+    readonly config: PixelumeClientConfig;
+    readonly health: PixelumeHealthApi;
+    constructor(options?: PixelumeClientOptions);
+}

package/dist/core/PixelumeClient.js

@@ -0,0 +1,37 @@
+import { HttpClient } from '../http/HttpClient.js';
+import { HealthModule } from '../modules/health/HealthModule.js';
+import { resolveConfig } from './config.js';
+/**
+ * Entry point of the SDK. Create one instance per API/game and share it.
+ *
+ * ```ts
+ * const pixelume = new PixelumeClient({ gameId: 'rail-puzzle' });
+ * 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.
+ *
+ * @throws {PixelumeConfigError} when the options are invalid.
+ */
+export class PixelumeClient {
+    config;
+    health;
+    constructor(options = {}) {
+        const resolved = resolveConfig(options);
+        this.config = Object.freeze({
+            apiUrl: resolved.apiUrl,
+            gameId: resolved.gameId,
+            timeoutMs: resolved.timeoutMs,
+            credentials: resolved.credentials,
+        });
+        const http = new HttpClient({
+            baseUrl: resolved.apiUrl,
+            fetch: resolved.fetch,
+            timeoutMs: resolved.timeoutMs,
+            credentials: resolved.credentials,
+        });
+        this.health = new HealthModule(http);
+    }
+}
+//# sourceMappingURL=PixelumeClient.js.map

package/dist/core/PixelumeClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PixelumeClient.js","sourceRoot":"","sources":["../../src/core/PixelumeClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,YAAY,EAA0B,MAAM,mCAAmC,CAAC;AACzF,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,cAAc;IAChB,MAAM,CAAuB;IAC7B,MAAM,CAAoB;IAEnC,YAAY,UAAiC,EAAE;QAC7C,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;YAC1B,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,MAAM,EAAE,QAAQ,CAAC,MAAM;YACvB,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,WAAW,EAAE,QAAQ,CAAC,WAAW;SAClC,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC;YAC1B,OAAO,EAAE,QAAQ,CAAC,MAAM;YACxB,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,SAAS,EAAE,QAAQ,CAAC,SAAS;YAC7B,WAAW,EAAE,QAAQ,CAAC,WAAW;SAClC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;CACF","sourcesContent":["import { HttpClient } from '../http/HttpClient.js';\nimport { HealthModule, type PixelumeHealthApi } from '../modules/health/HealthModule.js';\nimport { resolveConfig } from './config.js';\nimport type { PixelumeClientConfig, PixelumeClientOptions } from './types.js';\n\n/**\n * Entry point of the SDK. Create one instance per API/game and share it.\n *\n * ```ts\n * const pixelume = new PixelumeClient({ gameId: 'rail-puzzle' });\n * const health = await pixelume.health.check();\n * ```\n *\n * Feature modules are exposed as read-only properties. Phase 1 ships only `health`; future modules\n * (authentication, saves…) will be added as new properties without changing existing ones.\n *\n * @throws {PixelumeConfigError} when the options are invalid.\n */\nexport class PixelumeClient {\n  readonly config: PixelumeClientConfig;\n  readonly health: PixelumeHealthApi;\n\n  constructor(options: PixelumeClientOptions = {}) {\n    const resolved = resolveConfig(options);\n    this.config = Object.freeze({\n      apiUrl: resolved.apiUrl,\n      gameId: resolved.gameId,\n      timeoutMs: resolved.timeoutMs,\n      credentials: resolved.credentials,\n    });\n    const http = new HttpClient({\n      baseUrl: resolved.apiUrl,\n      fetch: resolved.fetch,\n      timeoutMs: resolved.timeoutMs,\n      credentials: resolved.credentials,\n    });\n    this.health = new HealthModule(http);\n  }\n}\n"]}

package/dist/core/config.d.ts

@@ -0,0 +1,25 @@
+import type { CredentialsPolicy, FetchLike } from '../http/types.js';
+import type { PixelumeClientOptions } from './types.js';
+export declare const DEFAULT_API_URL = "https://api.pixelume.com.br";
+export declare const DEFAULT_TIMEOUT_MS = 10000;
+export interface ResolvedConfig {
+    apiUrl: string;
+    gameId: string | null;
+    timeoutMs: number;
+    credentials: CredentialsPolicy;
+    fetch: FetchLike;
+}
+export declare function resolveConfig(options: PixelumeClientOptions): ResolvedConfig;
+/**
+ * Accepts `https:` URLs, plus `http:` for loopback hosts (`localhost`, `*.localhost`, `127.0.0.0/8`,
+ * `[::1]`). Other `http:` hosts (e.g. a LAN IP while testing on a phone) need `allowInsecureHttp`.
+ */
+export declare function normalizeApiUrl(value: string, allowInsecureHttp: boolean): string;
+/**
+ * Game identifiers are public, non-secret slugs (e.g. `rail-puzzle`): lowercase letters, digits
+ * and inner hyphens, 1–64 characters. They identify a game, they never authorize anything.
+ */
+export declare function validateGameId(value: string): string;
+/** For feature modules that need a game context (future phases). */
+export declare function requireGameId(config: Pick<ResolvedConfig, 'gameId'>, feature: string): string;
+export declare function validateTimeout(value: number): number;

package/dist/core/config.js

@@ -0,0 +1,89 @@
+import { PixelumeConfigError } from './errors.js';
+export const DEFAULT_API_URL = 'https://api.pixelume.com.br';
+export const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_TIMEOUT_MS = 2_147_483_647; // setTimeout limit
+const GAME_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/u;
+const CREDENTIALS = ['omit', 'same-origin', 'include'];
+export function resolveConfig(options) {
+    return {
+        apiUrl: normalizeApiUrl(options.apiUrl ?? DEFAULT_API_URL, options.allowInsecureHttp === true),
+        gameId: options.gameId === undefined ? null : validateGameId(options.gameId),
+        timeoutMs: options.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : validateTimeout(options.timeoutMs),
+        credentials: validateCredentials(options.credentials ?? 'omit'),
+        fetch: resolveFetch(options.fetch),
+    };
+}
+/**
+ * Accepts `https:` URLs, plus `http:` for loopback hosts (`localhost`, `*.localhost`, `127.0.0.0/8`,
+ * `[::1]`). Other `http:` hosts (e.g. a LAN IP while testing on a phone) need `allowInsecureHttp`.
+ */
+export function normalizeApiUrl(value, allowInsecureHttp) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new PixelumeConfigError('apiUrl must be an absolute URL, e.g. https://api.pixelume.com.br');
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new PixelumeConfigError('apiUrl must use https: (or http: for local development)');
+    }
+    if (url.protocol === 'http:' && !allowInsecureHttp && !isLoopbackHost(url.hostname)) {
+        throw new PixelumeConfigError('apiUrl must use https:. Plain http: is only accepted for localhost unless allowInsecureHttp is set');
+    }
+    if (url.username || url.password) {
+        throw new PixelumeConfigError('apiUrl must not contain credentials');
+    }
+    if (url.search || url.hash) {
+        throw new PixelumeConfigError('apiUrl must not contain a query string or fragment');
+    }
+    return `${url.origin}${url.pathname.replace(/\/+$/u, '')}`;
+}
+function isLoopbackHost(hostname) {
+    return (hostname === 'localhost' ||
+        hostname.endsWith('.localhost') ||
+        hostname === '[::1]' ||
+        /^127(?:\.\d{1,3}){3}$/u.test(hostname));
+}
+/**
+ * Game identifiers are public, non-secret slugs (e.g. `rail-puzzle`): lowercase letters, digits
+ * and inner hyphens, 1–64 characters. They identify a game, they never authorize anything.
+ */
+export function validateGameId(value) {
+    if (typeof value !== 'string' || !GAME_ID_PATTERN.test(value)) {
+        throw new PixelumeConfigError('gameId must be a lowercase slug (a-z, 0-9 and inner hyphens, up to 64 characters)');
+    }
+    return value;
+}
+/** For feature modules that need a game context (future phases). */
+export function requireGameId(config, feature) {
+    if (config.gameId === null) {
+        throw new PixelumeConfigError(`${feature} requires the client to be created with a gameId`);
+    }
+    return config.gameId;
+}
+export function validateTimeout(value) {
+    if (!Number.isInteger(value) || value <= 0 || value > MAX_TIMEOUT_MS) {
+        throw new PixelumeConfigError('timeoutMs must be a positive integer number of milliseconds');
+    }
+    return value;
+}
+function validateCredentials(value) {
+    if (!CREDENTIALS.includes(value)) {
+        throw new PixelumeConfigError(`credentials must be one of: ${CREDENTIALS.join(', ')}`);
+    }
+    return value;
+}
+function resolveFetch(custom) {
+    if (custom !== undefined) {
+        if (typeof custom !== 'function')
+            throw new PixelumeConfigError('fetch must be a function');
+        return custom;
+    }
+    if (typeof globalThis.fetch !== 'function') {
+        throw new PixelumeConfigError('No global fetch available; pass the fetch option');
+    }
+    // Looked up on each call so polyfills or test doubles installed later are honoured.
+    return (input, init) => globalThis.fetch(input, init);
+}
+//# sourceMappingURL=config.js.map

package/dist/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"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","sourcesContent":["import type { CredentialsPolicy, FetchLike } from '../http/types.js';\nimport { PixelumeConfigError } from './errors.js';\nimport type { PixelumeClientOptions } from './types.js';\n\nexport const DEFAULT_API_URL = 'https://api.pixelume.com.br';\nexport const DEFAULT_TIMEOUT_MS = 10_000;\nconst MAX_TIMEOUT_MS = 2_147_483_647; // setTimeout limit\nconst GAME_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/u;\nconst CREDENTIALS: readonly CredentialsPolicy[] = ['omit', 'same-origin', 'include'];\n\nexport interface ResolvedConfig {\n  apiUrl: string;\n  gameId: string | null;\n  timeoutMs: number;\n  credentials: CredentialsPolicy;\n  fetch: FetchLike;\n}\n\nexport function resolveConfig(options: PixelumeClientOptions): ResolvedConfig {\n  return {\n    apiUrl: normalizeApiUrl(options.apiUrl ?? DEFAULT_API_URL, options.allowInsecureHttp === true),\n    gameId: options.gameId === undefined ? null : validateGameId(options.gameId),\n    timeoutMs:\n      options.timeoutMs === undefined ? DEFAULT_TIMEOUT_MS : validateTimeout(options.timeoutMs),\n    credentials: validateCredentials(options.credentials ?? 'omit'),\n    fetch: resolveFetch(options.fetch),\n  };\n}\n\n/**\n * Accepts `https:` URLs, plus `http:` for loopback hosts (`localhost`, `*.localhost`, `127.0.0.0/8`,\n * `[::1]`). Other `http:` hosts (e.g. a LAN IP while testing on a phone) need `allowInsecureHttp`.\n */\nexport function normalizeApiUrl(value: string, allowInsecureHttp: boolean): string {\n  let url: URL;\n  try {\n    url = new URL(value);\n  } catch {\n    throw new PixelumeConfigError(\n      'apiUrl must be an absolute URL, e.g. https://api.pixelume.com.br',\n    );\n  }\n  if (url.protocol !== 'https:' && url.protocol !== 'http:') {\n    throw new PixelumeConfigError('apiUrl must use https: (or http: for local development)');\n  }\n  if (url.protocol === 'http:' && !allowInsecureHttp && !isLoopbackHost(url.hostname)) {\n    throw new PixelumeConfigError(\n      'apiUrl must use https:. Plain http: is only accepted for localhost unless allowInsecureHttp is set',\n    );\n  }\n  if (url.username || url.password) {\n    throw new PixelumeConfigError('apiUrl must not contain credentials');\n  }\n  if (url.search || url.hash) {\n    throw new PixelumeConfigError('apiUrl must not contain a query string or fragment');\n  }\n  return `${url.origin}${url.pathname.replace(/\\/+$/u, '')}`;\n}\n\nfunction isLoopbackHost(hostname: string): boolean {\n  return (\n    hostname === 'localhost' ||\n    hostname.endsWith('.localhost') ||\n    hostname === '[::1]' ||\n    /^127(?:\\.\\d{1,3}){3}$/u.test(hostname)\n  );\n}\n\n/**\n * Game identifiers are public, non-secret slugs (e.g. `rail-puzzle`): lowercase letters, digits\n * and inner hyphens, 1–64 characters. They identify a game, they never authorize anything.\n */\nexport function validateGameId(value: string): string {\n  if (typeof value !== 'string' || !GAME_ID_PATTERN.test(value)) {\n    throw new PixelumeConfigError(\n      'gameId must be a lowercase slug (a-z, 0-9 and inner hyphens, up to 64 characters)',\n    );\n  }\n  return value;\n}\n\n/** For feature modules that need a game context (future phases). */\nexport function requireGameId(config: Pick<ResolvedConfig, 'gameId'>, feature: string): string {\n  if (config.gameId === null) {\n    throw new PixelumeConfigError(`${feature} requires the client to be created with a gameId`);\n  }\n  return config.gameId;\n}\n\nexport function validateTimeout(value: number): number {\n  if (!Number.isInteger(value) || value <= 0 || value > MAX_TIMEOUT_MS) {\n    throw new PixelumeConfigError('timeoutMs must be a positive integer number of milliseconds');\n  }\n  return value;\n}\n\nfunction validateCredentials(value: CredentialsPolicy): CredentialsPolicy {\n  if (!CREDENTIALS.includes(value)) {\n    throw new PixelumeConfigError(`credentials must be one of: ${CREDENTIALS.join(', ')}`);\n  }\n  return value;\n}\n\nfunction resolveFetch(custom: FetchLike | undefined): FetchLike {\n  if (custom !== undefined) {\n    if (typeof custom !== 'function') throw new PixelumeConfigError('fetch must be a function');\n    return custom;\n  }\n  if (typeof globalThis.fetch !== 'function') {\n    throw new PixelumeConfigError('No global fetch available; pass the fetch option');\n  }\n  // Looked up on each call so polyfills or test doubles installed later are honoured.\n  return (input, init) => globalThis.fetch(input, init);\n}\n"]}

package/dist/core/errors.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Error hierarchy of the SDK.
+ *
+ * Every error thrown by the SDK is a {@link PixelumeError} with a stable `kind` discriminator.
+ * Messages are deterministic and never include request/response bodies, headers, cookies or
+ * query strings, so they are safe to log. Raw response payloads are kept on
+ * {@link PixelumeHttpError.payload} as a non-enumerable property for programmatic inspection only.
+ */
+export type PixelumeErrorKind = 'config' | 'http' | 'network' | 'timeout' | 'aborted' | 'invalid_response';
+/**
+ * Error codes documented in the Pixelume API OpenAPI `ErrorEnvelope`.
+ * The API may introduce new codes, so any string is accepted at runtime.
+ */
+export type PixelumeApiErrorCode = 'INVALID_INPUT' | 'UNAUTHENTICATED' | 'FORBIDDEN_ORIGIN' | 'FORBIDDEN_HOST' | 'RATE_LIMITED' | 'REGISTRATION_DISABLED' | 'AUTH_TOKEN_INVALID' | 'INTERNAL_ERROR' | 'NOT_FOUND' | (string & {});
+/** Identifies the request that failed. `path` never contains the query string. */
+export interface PixelumeRequestInfo {
+    readonly method: string;
+    readonly path: string;
+}
+/** Base class of every error thrown by the SDK. */
+export declare abstract class PixelumeError extends Error {
+    abstract readonly kind: PixelumeErrorKind;
+    protected constructor(name: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Invalid SDK configuration or invalid use of the SDK. Never caused by the network. */
+export declare class PixelumeConfigError extends PixelumeError {
+    readonly kind: "config";
+    constructor(message: string);
+}
+/** Base class of errors tied to a specific HTTP request. */
+export declare abstract class PixelumeRequestError extends PixelumeError {
+    readonly method: string;
+    readonly path: string;
+    protected constructor(name: string, message: string, request: PixelumeRequestInfo, options?: {
+        cause?: unknown;
+    });
+}
+/** The API answered with a non-2xx status. */
+export declare class PixelumeHttpError extends PixelumeRequestError {
+    readonly kind: "http";
+    readonly status: number;
+    /** `error.code` from the API error envelope, or `null` when the body is not an envelope. */
+    readonly code: PixelumeApiErrorCode | null;
+    /** `error.message` from the API error envelope (already sanitized by the API). */
+    readonly apiMessage: string | null;
+    /** Request ID from the envelope or the `x-request-id` header, useful for support. */
+    readonly requestId: string | null;
+    /**
+     * Decoded response body (JSON value, text or `undefined`). Non-enumerable so that
+     * `JSON.stringify(error)` and structured loggers do not dump it by accident.
+     */
+    readonly payload: unknown;
+    constructor(details: {
+        request: PixelumeRequestInfo;
+        status: number;
+        code: string | null;
+        apiMessage: string | null;
+        requestId: string | null;
+        payload: unknown;
+    });
+}
+/**
+ * The request did not produce an HTTP response: offline, DNS/TLS failure, connection reset,
+ * or a browser CORS rejection (browsers do not distinguish these for security reasons).
+ */
+export declare class PixelumeNetworkError extends PixelumeRequestError {
+    readonly kind: "network";
+    constructor(request: PixelumeRequestInfo, options?: {
+        cause?: unknown;
+    });
+}
+/** The SDK timeout elapsed before the response (including its body) was received. */
+export declare class PixelumeTimeoutError extends PixelumeRequestError {
+    readonly kind: "timeout";
+    readonly timeoutMs: number;
+    constructor(request: PixelumeRequestInfo, timeoutMs: number, options?: {
+        cause?: unknown;
+    });
+}
+/** The caller aborted the request through its `AbortSignal`. `cause` holds the abort reason. */
+export declare class PixelumeAbortError extends PixelumeRequestError {
+    readonly kind: "aborted";
+    constructor(request: PixelumeRequestInfo, options?: {
+        cause?: unknown;
+    });
+}
+/** A 2xx response did not match the contract expected by the SDK. */
+export declare class PixelumeInvalidResponseError extends PixelumeRequestError {
+    readonly kind: "invalid_response";
+    readonly status: number;
+    /** Short, payload-free description of the contract violation. */
+    readonly reason: string;
+    constructor(request: PixelumeRequestInfo, status: number, reason: string);
+}
+/**
+ * Returns `true` for any error thrown by the SDK. Works across duplicated copies of the package
+ * (where `instanceof` would fail) because it checks a global symbol brand.
+ */
+export declare function isPixelumeError(value: unknown): value is PixelumeError;