@gamecore-api/sdk 0.26.0 → 0.26.2

package/AGENTS.md

@@ -11,9 +11,9 @@ 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 { GameCore } from "@gamecore-api/sdk";
+import { GameCoreClient } from "@gamecore-api/sdk";
 
-const api = new GameCore({
+const gc = new GameCoreClient({
   apiKey: "gc_live_…",
   baseUrl: "https://api.gamecore-api.tech",
   locale: "en", // ← drives Accept-Language; "ru" or "en"
@@ -36,15 +36,15 @@ share keys across tenants.
 
 | Namespace | Purpose | Read first |
 |---|---|---|
-| `api.catalog` | Games, products, search, categories, recommendations | `examples/01-quickstart.ts` |
-| `api.cart` | Server-synced cart for logged-in users | `examples/01-quickstart.ts` |
-| `api.checkout` | Create payment, get gateway redirect URL | `examples/01-quickstart.ts` |
-| `api.orders` | Order list, detail, status polling | `examples/03-error-handling.ts` |
-| `api.profile` | User profile, balance, address book | — |
-| `api.auth` | Telegram login, email/password, JWT refresh | — |
-| `api.favorites`, `api.coupons`, `api.referrals`, `api.reviews`, `api.topup`, `api.giftCards`, `api.announcements`, `api.analytics`, `api.seo` | Domain-specific endpoints | — |
-| `api.sse` | Server-Sent Events stream (order updates) | — |
-| `api.site` | Site config — homepage layout, footer, theme, modules | — |
+| `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:
 
@@ -57,7 +57,7 @@ import { verifyWebhookSignature } from "@gamecore-api/sdk/server";
 ## Locale (since 0.25.0)
 
 - Pass `locale: "ru" | "en"` in constructor → SDK sends `Accept-Language` automatically on every request.
-- Override at runtime: `api.setLocale("en")` / `api.getLocale()`.
+- 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`.
 

package/examples/01-quickstart.ts

@@ -9,15 +9,15 @@
  * backend (Next.js route, Express, ElysiaJS, etc.).
  */
 
-import { GameCore } from "@gamecore-api/sdk";
+import { GameCoreClient } from "@gamecore-api/sdk";
 
-const api = new GameCore({
+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 api.catalog.getGames({
+const { data: games } = await gc.catalog.getGames({
 	limit: 12,
 	inStockOnly: true,
 });
@@ -26,36 +26,72 @@ console.log(
 	games.map((g) => g.slug),
 );
 
-// 2. Open a game detail page — pick the first in-stock game from list
+// 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);
 }
-const detail = await api.catalog.getGame(game.slug);
-const product = detail.products?.[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);
+console.log("picked product:", product.id, product.name, "price:", product.price);
 
-// 3. Create checkout (guest — pass email; no Telegram/VK login required).
+// 4. Create checkout (guest — pass email; no Telegram/VK login required).
 //    For balance-based payment, the user must be authenticated first.
-const checkout = await api.checkout.create({
-	items: [{ productId: product.id, qty: 1, deliveryData: {} }],
-	paymentMethod: "antilopay", // any gateway slug from getPaymentMethods()
+//
+//    Item fields:
+//      • productId  — REQUIRED, the supplier product
+//      • gameId     — REQUIRED (despite being typed optional). It's
+//                     the game slug; the backend reads it directly to
+//                     route Steam top-ups, SuperPass bundles, and
+//                     Robux-via-pass through their special validation
+//                     paths. A missing `gameId` crashes the request.
+//      • amount     — quantity for fixed-price items (default 1) OR
+//                     the top-up amount in local currency for Steam /
+//                     variable-amount products.
+//      • deliveryData — product-specific fields (account name, server
+//                     id, etc.). For simple gift cards this can be
+//                     an empty object.
+const checkout = await gc.checkout.create({
 	email: "buyer@example.com",
+	items: [
+		{
+			productId: product.id,
+			gameId: game.slug,
+			amount: 1,
+			deliveryData: {},
+		},
+	],
+	paymentMethod: "antilopay", // gateway slug from checkout.getPaymentMethods()
 });
-console.log("payment URL:", checkout.gatewayPaymentUrl);
-console.log("payment code:", checkout.paymentCode);
 
-// 4. Poll status until the user pays (or 5 minutes pass)
+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 api.checkout.getStatus(checkout.paymentCode);
+	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") {
-		console.log("orders:", status.orders);
+	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

@@ -8,20 +8,20 @@
  * 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 → defaults to "ru"
+ *   3. nothing → API falls back to RU
  *
  * Run with:
  *   GAMECORE_API_KEY=gc_live_... bun run examples/02-locale-switching.ts
  */
 
-import { GameCore } from "@gamecore-api/sdk";
+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 GameCore({ apiKey, baseUrl, locale: "ru" });
-const en = new GameCore({ apiKey, baseUrl, locale: "en" });
+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);
@@ -32,20 +32,25 @@ 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 api = new GameCore({ apiKey, baseUrl });
-api.setLocale("en");
-console.log("locale now:", api.getLocale());
-const homepage = await api.catalog.getHomepageGames();
+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 { data: enGames } = await api.catalog.getGames({
+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:",
+	"per-call EN list:",
 	enGames.map((g) => g.name),
 );

package/examples/03-error-handling.ts

@@ -6,7 +6,7 @@
  * (machine-readable string set by the API for known cases).
  *
  *   try {
- *     await api.checkout.create(...);
+ *     await gc.checkout.create(...);
  *   } catch (e) {
  *     if (e instanceof GameCoreError) {
  *       if (e.status === 401) { /* re-auth *\/ }
@@ -19,9 +19,9 @@
  *   GAMECORE_API_KEY=gc_live_... bun run examples/03-error-handling.ts
  */
 
-import { GameCore, GameCoreError } from "@gamecore-api/sdk";
+import { GameCoreClient, GameCoreError } from "@gamecore-api/sdk";
 
-const api = new GameCore({
+const gc = new GameCoreClient({
 	apiKey: process.env.GAMECORE_API_KEY!,
 	baseUrl: "https://api.gamecore-api.tech",
 
@@ -36,7 +36,7 @@ const api = new GameCore({
 
 // Force a 404 to demonstrate the error shape
 try {
-	await api.catalog.getGame("definitely-not-a-real-game-slug-9999");
+	await gc.catalog.getGame("definitely-not-a-real-game-slug-9999");
 } catch (e) {
 	if (e instanceof GameCoreError) {
 		console.log("caught:", {
@@ -54,13 +54,13 @@ try {
 //
 // • 401 + code "UNAUTHORIZED" → API key invalid or revoked. Stop
 //   the request, re-fetch a fresh key from your secret store.
-// • 401 + code "TOKEN_EXPIRED" → user session expired. Triggers
+// • 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 "qty must be ≥ 1" or "delivery data missing for product X").
+//   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> {
@@ -79,5 +79,5 @@ async function withRetry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
 	throw lastError;
 }
 
-const games = await withRetry(() => api.catalog.getHomepageGames());
+const games = await withRetry(() => gc.catalog.getHomepageGames());
 console.log("got", games.length, "games");

package/examples/04-webhook-verify.ts

@@ -1,7 +1,7 @@
 /**
  * 04 — Webhook verification (server-side only)
  *
- * GameCore sends webhooks (order.completed, payment.failed, etc.) to
+ * 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
@@ -16,10 +16,24 @@
  * RAW body (don't let your framework parse it before you verify).
  */
 
-import { verifyWebhookSignature, parseWebhookPayload } from "@gamecore-api/sdk/server";
+import {
+	parseWebhookPayload,
+	verifyWebhookSignature,
+} from "@gamecore-api/sdk/server";
 
 // — Express example —
-import type { Request, Response } from "express";
+//
+// 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
 
@@ -45,17 +59,27 @@ export async function handleWebhook(req: Request, res: Response) {
 		return;
 	}
 
-	const event = parseWebhookPayload(rawBody);
-	switch (event.type) {
-		case "order.completed":
-			console.log("order delivered:", event.data.orderCode);
-			// e.g. flip your internal order state, send a fulfillment email, etc.
+	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 "payment.completed":
-			console.log("payment received:", event.data.paymentCode);
+		}
+		case "order.failed":
+		case "order.cancelled":
+			console.log("order ended:", payload.event, payload.data);
 			break;
 		default:
-			console.log("unhandled event:", event.type);
+			console.log("unhandled event:", payload.event);
 	}
 
 	res.status(200).send("ok");
@@ -72,8 +96,8 @@ export async function handleWebhook(req: Request, res: Response) {
 //       if (!verifyWebhookSignature(raw, sig, WEBHOOK_SECRET)) {
 //         return new Response("invalid", { status: 401 });
 //       }
-//       const event = parseWebhookPayload(raw);
-//       // ... handle event
+//       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.26.0",
+	"version": "0.26.2",
 	"description": "TypeScript SDK for GameCore API — browser-safe, zero dependencies",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
@@ -19,7 +19,8 @@
 	"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",