@volorio/games-node 0.2.0

package/README.md

@@ -0,0 +1,25 @@
+# @volorio/games-node
+
+Server-side Volorio Games SDK.
+
+Use this package only in your backend. It sends your Volorio server API key to `api.volor.io` and creates short-lived game sessions/tokens for browser and mobile clients.
+
+```ts
+import { VolorioGamesNodeClient } from "@volorio/games-node";
+
+const games = new VolorioGamesNodeClient({
+  apiBaseUrl: "https://api.volor.io",
+  apiKey: process.env.VOLORIO_API_KEY!,
+});
+
+const session = await games.createGameSession({
+  projectId: "proj_123",
+  roomId: "room_123",
+  gameId: "dice",
+  gameVersion: "1.0.0",
+  createdBy: "user_123",
+});
+```
+
+Never put the server API key in browser or mobile code.
+

package/dist/src/index.d.ts

@@ -0,0 +1,85 @@
+import type { VolorioGameManifest, VolorioGameRole, VolorioGameSessionStatus } from "@volorio/games-core";
+export interface VolorioGamesNodeClientOptions {
+    apiBaseUrl: string;
+    apiKey: string;
+    fetch?: typeof fetch;
+}
+export interface CreateGameSessionInput {
+    projectId: string;
+    roomId: string;
+    gameId: string;
+    gameVersion?: string;
+    createdBy: string;
+    maxPlayers?: number;
+    spectatorSupport?: boolean;
+    idempotencyKey?: string;
+}
+export interface JoinGameSessionInput {
+    gameInstanceId: string;
+    identity: string;
+    displayName?: string;
+    role?: VolorioGameRole;
+    lastKnownStateVersion?: number;
+}
+export interface StartGameSessionInput {
+    gameInstanceId: string;
+    startedBy: string;
+    idempotencyKey?: string;
+}
+export interface FinishGameSessionInput {
+    gameInstanceId: string;
+    finishedBy: string;
+    reason?: string;
+    idempotencyKey?: string;
+}
+export interface CreateGameTokenInput {
+    gameInstanceId: string;
+    identity: string;
+    role?: VolorioGameRole;
+    ttlSeconds?: number;
+    permissions?: string[];
+}
+export interface VolorioGameSessionDescriptor {
+    gameInstanceId: string;
+    projectId: string;
+    roomId: string;
+    gameId: string;
+    gameVersion: string;
+    status: VolorioGameSessionStatus;
+    gatewayUrl?: string;
+}
+export interface VolorioGameJoinResult {
+    gameInstanceId: string;
+    identity: string;
+    role: VolorioGameRole;
+    status: VolorioGameSessionStatus;
+    token?: string;
+    gatewayUrl?: string;
+    stateVersion?: number;
+}
+export interface VolorioGameTokenResult {
+    token: string;
+    expiresAt: string;
+    gatewayUrl: string;
+}
+export interface VolorioLeaderboardEntry {
+    rank: number;
+    identity: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+}
+export declare class VolorioGamesNodeClient {
+    private readonly options;
+    private readonly apiBaseUrl;
+    private readonly fetchImpl;
+    constructor(options: VolorioGamesNodeClientOptions);
+    listCatalog(projectId: string): Promise<VolorioGameManifest[]>;
+    createGameSession(input: CreateGameSessionInput): Promise<VolorioGameSessionDescriptor>;
+    getGameSession(gameInstanceId: string): Promise<VolorioGameSessionDescriptor>;
+    joinGameSession(input: JoinGameSessionInput): Promise<VolorioGameJoinResult>;
+    startGameSession(input: StartGameSessionInput): Promise<VolorioGameSessionDescriptor>;
+    finishGameSession(input: FinishGameSessionInput): Promise<VolorioGameSessionDescriptor>;
+    createGameToken(input: CreateGameTokenInput): Promise<VolorioGameTokenResult>;
+    getLeaderboard(projectId: string, gameId: string, limit?: number): Promise<VolorioLeaderboardEntry[]>;
+    private request;
+}

package/dist/src/index.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VolorioGamesNodeClient = void 0;
+class VolorioGamesNodeClient {
+    options;
+    apiBaseUrl;
+    fetchImpl;
+    constructor(options) {
+        this.options = options;
+        this.apiBaseUrl = options.apiBaseUrl.replace(/\/+$/, "");
+        this.fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+        if (options.apiKey.trim().length === 0) {
+            throw new Error("volorio_games_api_key_required");
+        }
+    }
+    listCatalog(projectId) {
+        return this.request(`/v1/games/catalog?projectId=${encodeURIComponent(projectId)}`, { method: "GET" });
+    }
+    createGameSession(input) {
+        return this.request("/v1/games/sessions", { method: "POST", body: input });
+    }
+    getGameSession(gameInstanceId) {
+        return this.request(`/v1/games/sessions/${encodeURIComponent(gameInstanceId)}`, { method: "GET" });
+    }
+    joinGameSession(input) {
+        return this.request(`/v1/games/sessions/${encodeURIComponent(input.gameInstanceId)}/join`, { method: "POST", body: input });
+    }
+    startGameSession(input) {
+        return this.request(`/v1/games/sessions/${encodeURIComponent(input.gameInstanceId)}/start`, { method: "POST", body: input });
+    }
+    finishGameSession(input) {
+        return this.request(`/v1/games/sessions/${encodeURIComponent(input.gameInstanceId)}/finish`, { method: "POST", body: input });
+    }
+    createGameToken(input) {
+        return this.request(`/v1/games/sessions/${encodeURIComponent(input.gameInstanceId)}/tokens`, { method: "POST", body: input });
+    }
+    getLeaderboard(projectId, gameId, limit = 100) {
+        const params = new URLSearchParams({ projectId, limit: String(limit) });
+        return this.request(`/v1/games/leaderboards/${encodeURIComponent(gameId)}?${params.toString()}`, { method: "GET" });
+    }
+    async request(path, init) {
+        const response = await this.fetchImpl(`${this.apiBaseUrl}${path}`, {
+            method: init.method,
+            headers: {
+                "authorization": `Bearer ${this.options.apiKey}`,
+                "content-type": "application/json",
+            },
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+        });
+        const body = await response.json().catch(() => undefined);
+        if (!response.ok) {
+            throw new Error(readErrorMessage(body, response.status));
+        }
+        return body;
+    }
+}
+exports.VolorioGamesNodeClient = VolorioGamesNodeClient;
+function readErrorMessage(body, status) {
+    if (typeof body === "object" && body !== null && "message" in body) {
+        return String(body.message);
+    }
+    return `volorio_games_request_failed_${status}`;
+}
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@volorio/games-node",
+  "version": "0.2.0",
+  "private": false,
+  "description": "Server-side Volorio Games client for game catalog, session, token, and leaderboard control-plane APIs.",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": [
+    "dist/src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "pnpm build && tsc -p tsconfig.json && node --test dist/test/*.js",
+    "pack:local": "pnpm build && npm pack --pack-destination dist"
+  },
+  "dependencies": {
+    "@volorio/games-core": "^0.2.0"
+  }
+}