@ngsk2784-lab/game-sdk

Framework-agnostic TypeScript client for the game-services hub — guest-first leaderboards and cloud saves for games.

Status: 0.1.0 (M4). Implemented + tested. Non-JS engines (Godot/Unity/curl) use ../../docs/http-contract.md; full schema in ../../docs/api-contract.md.

Install

npm install @ngsk2784-lab/game-sdk

Usage

import { createGameClient, createMemoryStorage } from "@ngsk2784-lab/game-sdk";

const games = createGameClient({
  baseUrl: "https://game-services.example.com",
  gameId: "my-game",
  storage: createMemoryStorage(),       // or a localStorage/AsyncStorage adapter
  getUserToken: () => currentUserJwt,    // optional: login-hub user JWT (takes priority)
  apiKey: "ak_...",                      // optional: server-side read fallback
  hmacSecret: "...",                     // optional: client-side score signing
});

await games.ensureGuest();                                  // auto-issued + persisted
await games.submitScore("high-scores", 4200, { metadata: { level: 7 } });
await games.getTop("high-scores", { period: "weekly", limit: 20 });
await games.getMe("high-scores", { around: 5 });
await games.save(0, { gold: 100 });                         // → { version, conflict }
await games.load(0);
await games.merge();                                        // guest → account on login

API

createGameClient(options) → GameClient: ensureGuest · getIdentity · submitScore · getTop · getMe / getAround · getRank · save · load · merge · clearGuest. Errors throw GameServicesError { status, code, message, detail? } (codes from api-contract §1).

Publishing

Published to npm as a public scoped package on sdk-v* git tags (see repo CI). Bump version here, tag sdk-vX.Y.Z, push.