@gamecore-api/sdk 0.25.0 → 0.26.1

package/AGENTS.md

@@ -0,0 +1,80 @@
+# @gamecore-api/sdk — Agent Brief
+
+> **For AI agents reading this:** this file is the short-path orientation. If
+> the user is asking you to build with this SDK, read this first, then the
+> [README](./README.md), then look at [`examples/`](./examples/) for working
+> code you can adapt.
+
+## What this is
+
+Browser- and Node-safe TypeScript client for the GameCore API — a multi-tenant
+BaaS for game-currency / digital-key storefronts. Zero runtime dependencies.
+
+```ts
+import { GameCoreClient } from "@gamecore-api/sdk";
+
+const gc = new GameCoreClient({
+  apiKey: "gc_live_…",
+  baseUrl: "https://api.gamecore-api.tech",
+  locale: "en", // ← drives Accept-Language; "ru" or "en"
+});
+```
+
+## Required setup (don't forget any of these)
+
+| Option | Where it comes from | What happens if omitted |
+|---|---|---|
+| `apiKey` | Server env (`GAMECORE_API_KEY`) — **never** ship to browser bundles | All calls 401 |
+| `baseUrl` | `https://api.gamecore-api.tech` (prod) or self-hosted | Constructor throws |
+| `locale` | Optional. `"ru"` default, `"en"` for English storefronts | Storefront stays Russian |
+| `onAuthError` | Optional callback to handle JWT expiry | Caller has to catch 401s manually |
+
+`apiKey` is a **site-level** key. Each tenant ("site") has its own key. Don't
+share keys across tenants.
+
+## Namespaces (what to reach for)
+
+| Namespace | Purpose | Read first |
+|---|---|---|
+| `gc.catalog` | Games, products, search, categories, recommendations | `examples/01-quickstart.ts` |
+| `gc.cart` | Server-synced cart for logged-in users | `examples/01-quickstart.ts` |
+| `gc.checkout` | Create payment, get gateway redirect URL | `examples/01-quickstart.ts` |
+| `gc.orders` | Order list, detail, status polling | `examples/03-error-handling.ts` |
+| `gc.profile` | User profile, balance, address book | — |
+| `gc.auth` | Telegram login, email/password, JWT refresh | — |
+| `gc.favorites`, `api.coupons`, `api.referrals`, `api.reviews`, `api.topup`, `api.giftCards`, `api.announcements`, `api.analytics`, `api.seo` | Domain-specific endpoints | — |
+| `gc.sse` | Server-Sent Events stream (order updates) | — |
+| `gc.site` | Site config — homepage layout, footer, theme, modules | — |
+
+Server-only helpers live under the `/server` entry point:
+
+```ts
+import { verifyWebhookSignature } from "@gamecore-api/sdk/server";
+```
+
+(See `examples/04-webhook-verify.ts`.)
+
+## Locale (since 0.25.0)
+
+- Pass `locale: "ru" | "en"` in constructor → SDK sends `Accept-Language` automatically on every request.
+- Override at runtime: `gc.setLocale("en")` / `gc.getLocale()`.
+- The backend overlays **game names**, short descriptions, and descriptions in the requested locale. Slugs / IDs never change.
+- Original-language responses: just don't set `locale`.
+
+## Pitfalls
+
+- **Don't put `apiKey` in client-side JS bundles** — proxy through your own
+  backend (Next.js API routes, ElysiaJS, etc.) so the key stays server-side.
+- **Catch `GameCoreError`** — every namespace throws this class on non-2xx.
+  See `examples/03-error-handling.ts` for the shape.
+- **Cart endpoints require an authenticated user**. Call `api.auth.*` first.
+- **`baseUrl` must NOT end in `/`** — the SDK strips trailing slashes but be
+  consistent (`https://api.gamecore-api.tech`, not `…/`).
+- **Webhook verification** is a constant-time HMAC compare — never roll your
+  own with `==`. Use `verifyWebhookSignature` from `/server`.
+
+## Where to look next
+
+- [README.md](./README.md) — full API surface, options, browser/Node notes
+- [examples/](./examples/) — runnable .ts files covering quickstart, locale, errors, webhooks
+- [CHANGELOG.md](./CHANGELOG.md) — what's new per version

package/README.md

@@ -8,6 +8,55 @@ TypeScript SDK for GameCore API — zero external dependencies, browser-safe.
 npm install @gamecore-api/sdk
 ```
 
+## For AI agents
+
+If an AI coding assistant is reading this, start with [**AGENTS.md**](./AGENTS.md)
+for a short orientation, then look at runnable code in
+[**examples/**](./examples/):
+
+| File | Covers |
+|---|---|
+| `examples/01-quickstart.ts` | catalog → checkout → status polling |
+| `examples/02-locale-switching.ts` | RU/EN switching: constructor, runtime, per-call |
+| `examples/03-error-handling.ts` | `GameCoreError`, status/code patterns, retries |
+| `examples/04-webhook-verify.ts` | HMAC verification with `/server` entry point |
+
+## Locale switching (RU / EN)
+
+The SDK ships with built-in multilingual support. Pass `locale: "ru" | "en"`
+to the constructor and every catalog / CMS response comes back in that
+language. The client sends an `Accept-Language` header on every request;
+the API resolves it against the unified `catalog_translations` store and
+falls back to the base copy when a translation is missing.
+
+```ts
+import { GameCoreClient, type SdkLocale } from "@gamecore-api/sdk";
+
+const gc = new GameCoreClient({
+  apiKey: "gc_live_...",
+  baseUrl: "https://api.gamecore-api.tech",
+  locale: "en", // default for this client instance
+});
+
+// Runtime switch — wire this to a storefront language toggle:
+gc.setLocale("ru");
+const game = await gc.catalog.getGame("afk-journey");
+// game.name / game.description / game.shortDescription are now in RU
+
+// Per-call override still wins over the client default:
+const enGame = await gc.catalog.getGame("afk-journey", "en");
+```
+
+Supported locales: `"ru"` (default when nothing is passed) and `"en"`.
+
+## What's new in 0.25.0
+
+- **Locale switching (RU / EN).** New `locale` option on `GameCoreClient`
+  plus `setLocale` / `getLocale` runtime helpers. See section above.
+- New exported type `SdkLocale = "ru" | "en"`.
+- Backwards-compatible: clients that don't pass `locale` keep the previous
+  "server falls back to RU" behaviour.
+
 ## What's new in 0.14.0
 
 - **BREAKING** `giftCards.purchase()` signature changed: first arg is now `amountRub` (was `amountUsd`). GiftCard payload fields renamed — `amount_usd` → `amount_rub`, added `currency`, `remainingBalance`, `expiresAt`. `denomination` is now optional (legacy)

package/examples/01-quickstart.ts

@@ -0,0 +1,80 @@
+/**
+ * 01 — Quickstart: catalog → checkout → status
+ *
+ * Minimum viable flow for a guest checkout. Run with:
+ *
+ *   GAMECORE_API_KEY=gc_live_... bun run examples/01-quickstart.ts
+ *
+ * Don't put `apiKey` in client-side bundles — proxy through your own
+ * backend (Next.js route, Express, ElysiaJS, etc.).
+ */
+
+import { GameCoreClient } from "@gamecore-api/sdk";
+
+const gc = new GameCoreClient({
+	apiKey: process.env.GAMECORE_API_KEY!,
+	baseUrl: "https://api.gamecore-api.tech",
+});
+
+// 1. Browse the catalog (first 12 in-stock games)
+const { data: games } = await gc.catalog.getGames({
+	limit: 12,
+	inStockOnly: true,
+});
+console.log(
+	"games:",
+	games.map((g) => g.slug),
+);
+
+// 2. Open a game detail page — pick the first in-stock game from the list
+const game = games[0];
+if (!game) {
+	console.log("No in-stock games for this site. Done.");
+	process.exit(0);
+}
+await gc.catalog.getGame(game.slug); // detail page lookup (returns GameDetail)
+
+// 3. Pull products for that game — getGame returns metadata, not products.
+const products = await gc.catalog.getProducts(game.slug);
+const product = products[0];
+if (!product) {
+	console.log(`Game ${game.slug} has no products. Done.`);
+	process.exit(0);
+}
+console.log("picked product:", product.id, product.name, "price:", product.price);
+
+// 4. Create checkout (guest — pass email; no Telegram/VK login required).
+//    For balance-based payment, the user must be authenticated first.
+//    `amount` in items is the qty for products that have a fixed price
+//    OR the topup amount for variable-amount products; pass 1 for
+//    single-unit purchases.
+const checkout = await gc.checkout.create({
+	email: "buyer@example.com",
+	items: [{ productId: product.id, amount: 1, deliveryData: {} }],
+	paymentMethod: "antilopay", // gateway slug from checkout.getPaymentMethods()
+});
+
+if (!checkout.payment) {
+	console.error("Checkout did not return a payment record:", checkout);
+	process.exit(1);
+}
+console.log("payment code:", checkout.payment.code);
+console.log("payment URL:", checkout.payment.paymentUrl);
+
+// 5. Poll status until the user pays (or 5 minutes pass)
+for (let i = 0; i < 30; i++) {
+	const status = await gc.checkout.getStatus(checkout.payment.code);
+	console.log(`[${i}] status=${status.payment.status}`);
+	if (
+		status.payment.status === "completed" ||
+		status.payment.status === "failed" ||
+		status.payment.status === "cancelled"
+	) {
+		console.log(
+			"orders:",
+			status.orders.map((o) => ({ code: o.code, status: o.status })),
+		);
+		break;
+	}
+	await new Promise((r) => setTimeout(r, 10_000));
+}

package/examples/02-locale-switching.ts

@@ -0,0 +1,56 @@
+/**
+ * 02 — Locale switching (RU / EN)
+ *
+ * Same site, different language. Backend overlays game names, short
+ * descriptions, and descriptions for the requested locale. Slugs and
+ * IDs never change — safe to share across languages.
+ *
+ * Three ways to pick a locale (highest priority first):
+ *   1. ?locale=en on a per-request basis
+ *   2. constructor option `locale: "en"` → adds Accept-Language header
+ *   3. nothing → API falls back to RU
+ *
+ * Run with:
+ *   GAMECORE_API_KEY=gc_live_... bun run examples/02-locale-switching.ts
+ */
+
+import { GameCoreClient } from "@gamecore-api/sdk";
+
+const apiKey = process.env.GAMECORE_API_KEY!;
+const baseUrl = "https://api.gamecore-api.tech";
+
+// Approach A — one client per locale (simplest)
+const ru = new GameCoreClient({ apiKey, baseUrl, locale: "ru" });
+const en = new GameCoreClient({ apiKey, baseUrl, locale: "en" });
+
+const slug = "shp"; // a game we know has both RU and EN
+const ruDetail = await ru.catalog.getGame(slug);
+const enDetail = await en.catalog.getGame(slug);
+console.log("RU name:", ruDetail.name);
+console.log("EN name:", enDetail.name);
+console.log("EN short:", enDetail.shortDescription);
+
+// Approach B — single client, switch at runtime (useful for SSR
+// where the locale comes from the request headers).
+const gc = new GameCoreClient({ apiKey, baseUrl });
+gc.setLocale("en");
+console.log("locale now:", gc.getLocale());
+const homepage = await gc.catalog.getHomepageGames();
+console.log("homepage first:", homepage[0]?.name);
+
+// Approach C — per-call override. Useful when most traffic is one
+// locale but a specific page needs the other (e.g. an admin tool
+// rendering an EN preview from an otherwise-RU client).
+const enGame = await gc.catalog.getGame(slug, "en");
+console.log("per-call EN:", enGame.name);
+
+// Approach D — locale on the paginated list endpoint. Same per-call
+// override pattern but via a typed option.
+const { data: enGames } = await gc.catalog.getGames({
+	limit: 5,
+	locale: "en",
+});
+console.log(
+	"per-call EN list:",
+	enGames.map((g) => g.name),
+);

package/examples/03-error-handling.ts

@@ -0,0 +1,83 @@
+/**
+ * 03 — Error handling
+ *
+ * Every namespace throws `GameCoreError` on non-2xx responses. Always
+ * branch on `.status` (numeric HTTP code) and optionally `.code`
+ * (machine-readable string set by the API for known cases).
+ *
+ *   try {
+ *     await gc.checkout.create(...);
+ *   } catch (e) {
+ *     if (e instanceof GameCoreError) {
+ *       if (e.status === 401) { /* re-auth *\/ }
+ *       if (e.status === 429) { /* backoff + retry *\/ }
+ *       if (e.code === "INSUFFICIENT_FUNDS") { /* show top-up CTA *\/ }
+ *     }
+ *   }
+ *
+ * Run with:
+ *   GAMECORE_API_KEY=gc_live_... bun run examples/03-error-handling.ts
+ */
+
+import { GameCoreClient, GameCoreError } from "@gamecore-api/sdk";
+
+const gc = new GameCoreClient({
+	apiKey: process.env.GAMECORE_API_KEY!,
+	baseUrl: "https://api.gamecore-api.tech",
+
+	// Optional: catch silent JWT expiry across all endpoints. Fires
+	// when a request returned 401 with code "TOKEN_EXPIRED" — useful
+	// for showing a "please log in again" toast without wrapping
+	// every call.
+	onAuthError: () => {
+		console.warn("auth expired — redirect to login");
+	},
+});
+
+// Force a 404 to demonstrate the error shape
+try {
+	await gc.catalog.getGame("definitely-not-a-real-game-slug-9999");
+} catch (e) {
+	if (e instanceof GameCoreError) {
+		console.log("caught:", {
+			name: e.name,
+			status: e.status,
+			code: e.code,
+			message: e.message,
+		});
+	} else {
+		throw e;
+	}
+}
+
+// Patterns worth knowing:
+//
+// • 401 + code "UNAUTHORIZED" → API key invalid or revoked. Stop
+//   the request, re-fetch a fresh key from your secret store.
+// • 410 + code "TOKEN_EXPIRED" → user JWT expired. Triggers
+//   `onAuthError` if you provided one.
+// • 429 + code "RATE_LIMITED" → token bucket. Read the `Retry-After`
+//   header if present, otherwise back off ~1s and retry.
+// • 400 with field-level details → check `message` for the offending
+//   field (server returns plain-English reason for predictable cases
+//   like "amount must be ≥ 1" or "delivery data missing for product X").
+
+// Retry helper with exponential backoff for transient errors
+async function withRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
+	let lastError: unknown;
+	for (let i = 0; i < attempts; i++) {
+		try {
+			return await fn();
+		} catch (e) {
+			lastError = e;
+			const transient =
+				e instanceof GameCoreError && (e.status === 429 || e.status >= 500);
+			if (!transient) throw e;
+			await new Promise((r) => setTimeout(r, 2 ** i * 500));
+		}
+	}
+	throw lastError;
+}
+
+const games = await withRetry(() => gc.catalog.getHomepageGames());
+console.log("got", games.length, "games");

package/examples/04-webhook-verify.ts

@@ -0,0 +1,105 @@
+/**
+ * 04 — Webhook verification (server-side only)
+ *
+ * GameCore sends webhooks (order.completed, payment.received, etc.) to
+ * a URL you register in the site-admin. Each request is signed with
+ * HMAC-SHA256 using your webhook secret. ALWAYS verify before
+ * trusting the body — without verification, an attacker who guesses
+ * your webhook URL can fake order events.
+ *
+ * Import from "@gamecore-api/sdk/server", NOT the root entry, since
+ * webhook verification uses `node:crypto` and won't bundle for
+ * browsers.
+ *
+ * Below: a minimal Express handler. Same shape works for Bun, Next.js
+ * API routes, Hono, ElysiaJS, etc. — what matters is reading the
+ * RAW body (don't let your framework parse it before you verify).
+ */
+
+import {
+	parseWebhookPayload,
+	verifyWebhookSignature,
+} from "@gamecore-api/sdk/server";
+
+// — Express example —
+//
+// Type imports are inlined as `unknown` here so the example type-checks
+// without `@types/express` in this package. In a real project, replace
+// with `import type { Request, Response } from "express"`.
+type Request = {
+	body: string | Buffer;
+	header(name: string): string | undefined;
+};
+type Response = {
+	status(code: number): Response;
+	send(body: string): Response;
+};
+
+const WEBHOOK_SECRET = process.env.GAMECORE_WEBHOOK_SECRET!; // from site-admin
+
+export async function handleWebhook(req: Request, res: Response) {
+	// Critical: raw body. In Express, add this middleware specifically
+	// for the webhook route:
+	//   app.post("/gamecore-webhook",
+	//     express.raw({ type: "application/json" }),
+	//     handleWebhook);
+	const rawBody =
+		typeof req.body === "string" ? req.body : (req.body as Buffer).toString("utf8");
+
+	const signature = req.header("X-Webhook-Signature") ?? "";
+
+	const ok = verifyWebhookSignature(
+		rawBody,
+		signature,
+		WEBHOOK_SECRET,
+		300, // freshness window in seconds (default). 0 to disable.
+	);
+	if (!ok) {
+		res.status(401).send("invalid signature");
+		return;
+	}
+
+	const payload = parseWebhookPayload(rawBody);
+	// payload.event is the WebhookEvent union; payload.data is
+	// `Record<string, unknown>` because the shape varies per event.
+	// Cast inside each branch when you've checked the discriminant.
+	switch (payload.event) {
+		case "order.completed": {
+			const data = payload.data as { orderCode?: string };
+			console.log("order delivered:", data.orderCode);
+			break;
+		}
+		case "payment.received": {
+			const data = payload.data as { paymentCode?: string; totalAmount?: number };
+			console.log("payment received:", data.paymentCode, data.totalAmount);
+			break;
+		}
+		case "order.failed":
+		case "order.cancelled":
+			console.log("order ended:", payload.event, payload.data);
+			break;
+		default:
+			console.log("unhandled event:", payload.event);
+	}
+
+	res.status(200).send("ok");
+}
+
+// — Bun.serve example (no Express) —
+//
+// Bun.serve({
+//   port: 3000,
+//   async fetch(req) {
+//     if (new URL(req.url).pathname === "/gamecore-webhook") {
+//       const raw = await req.text();
+//       const sig = req.headers.get("X-Webhook-Signature") ?? "";
+//       if (!verifyWebhookSignature(raw, sig, WEBHOOK_SECRET)) {
+//         return new Response("invalid", { status: 401 });
+//       }
+//       const payload = parseWebhookPayload(raw);
+//       // ... switch on payload.event
+//       return new Response("ok");
+//     }
+//     return new Response("not found", { status: 404 });
+//   },
+// });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gamecore-api/sdk",
-	"version": "0.25.0",
+	"version": "0.26.1",
 	"description": "TypeScript SDK for GameCore API — browser-safe, zero dependencies",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -16,10 +16,11 @@
 			"types": "./dist/server.d.ts"
 		}
 	},
-	"files": ["dist"],
+	"files": ["dist", "examples", "AGENTS.md"],
 	"scripts": {
 		"build": "bun build src/index.ts --outdir dist --target browser && bun build src/server.ts --outdir dist --target node && bun x tsc --emitDeclarationOnly",
-		"typecheck": "bun x tsc --noEmit"
+		"typecheck": "bun x tsc --noEmit",
+		"typecheck:examples": "bun x tsc --project tsconfig.examples.json"
 	},
 	"devDependencies": {
 		"@types/node": "^25.5.0",