@gamecore-api/sdk 0.26.2 → 0.27.0

package/AGENTS.md

@@ -61,6 +61,17 @@ import { verifyWebhookSignature } from "@gamecore-api/sdk/server";
 - 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`.
 
+## Display currency (since 0.27.0)
+
+- Pass `currency: "USD" | "EUR" | "KZT" | "UAH" | "TRY" | …` in constructor → SDK sends `X-Currency` automatically on every catalog request.
+- Override at runtime: `gc.setCurrency("EUR")` / `gc.getCurrency()`.
+- Per-call override: `gc.catalog.getProducts(slug, { currency: "USD" })`.
+- Every product response carries `product.currency` so the storefront can render the right symbol without tracking the requested code.
+- Server applies **live FX rates** (open.er-api.com, 30-min cache) and rounds per currency convention (whole KZT/UAH/TRY/RUB, 2-decimal USD/EUR/GBP).
+- Default is RUB — existing storefronts keep working unchanged.
+- **Checkout is unrelated**: payments still settle in RUB or USD via the chosen gateway. Display currency is purely catalog-side.
+- See `examples/05-currency-switching.ts`.
+
 ## Pitfalls
 
 - **Don't put `apiKey` in client-side JS bundles** — proxy through your own

package/README.md

@@ -20,6 +20,7 @@ for a short orientation, then look at runnable code in
 | `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 |
+| `examples/05-currency-switching.ts` | Display currency (RUB / USD / EUR / KZT / UAH / TRY …) |
 
 ## Locale switching (RU / EN)
 
@@ -49,6 +50,40 @@ const enGame = await gc.catalog.getGame("afk-journey", "en");
 
 Supported locales: `"ru"` (default when nothing is passed) and `"en"`.
 
+## Display currency (RUB / USD / EUR / KZT / UAH / TRY …)
+
+Since 0.27.0 the SDK can quote product prices in any of the supported
+ISO-4217 currencies. The server uses live FX rates (cached 30 minutes)
+and rounds per currency convention (whole KZT/UAH/TRY/RUB, 2-decimal
+USD/EUR/GBP).
+
+```ts
+import { GameCoreClient, type SdkCurrency } from "@gamecore-api/sdk";
+
+const gc = new GameCoreClient({
+  apiKey: "gc_live_...",
+  baseUrl: "https://api.gamecore-api.tech",
+  currency: "USD", // SDK adds X-Currency: USD on every catalog request
+});
+
+// Runtime switch — wire to a storefront currency picker:
+gc.setCurrency("KZT");
+const products = await gc.catalog.getProducts("free-fire");
+console.log(products[0].price, products[0].currency); // 480, "KZT"
+
+// Per-call override:
+const usdProducts = await gc.catalog.getProducts("free-fire", { currency: "USD" });
+```
+
+Supported currencies: `RUB` (default), `USD`, `EUR`, `GBP`, `KZT`,
+`UAH`, `TRY`, `BRL`, `ARS`, `INR`, `PLN`, `CZK`. Every product
+response carries the resolved `currency` field — read that instead of
+tracking the requested code separately.
+
+**Checkout is unrelated**: payment gateways still settle in RUB or USD
+depending on the chosen `paymentMethod`. The display currency is a
+catalog-side feature today.
+
 ## What's new in 0.25.0
 
 - **Locale switching (RU / EN).** New `locale` option on `GameCoreClient`

package/dist/client.d.ts

@@ -1,6 +1,13 @@
 import type { Announcement, AnnouncementBar, CartItem, CashbackPreview, CatalogSection, Category, CategoryInfo, CheckoutRequest, CheckoutResponse, CheckoutStatus, CmsArticleListResponse, CmsArticleLocale, CmsArticleResponse, CmsArticleType, CompleteWithBalanceResult, Conversation, ConversationDetail, CouponResult, DailyBonusClaimResult, DailyBonusStatus, DeliveryHelpResponse, ExchangeRates, FaqListResponse, Favorite, Game, GameDetail, GameRequestList, GiftCard, LegalDocument, LevelStatus, Notification, Order, PagedGamesResponse, PlatformInfo, PaginatedResponse, PaymentInfo, PaymentMethod, Product, ProductFilters, ProfileSummary, PublicCoupon, Quest, QuestCompleteResult, ReferralCommission, ReferralLink, ReferralPerformance, ReferralStats, ReferralTransferResult, Review, ReviewCreateResult, ReviewPolicy, ReviewProof, ReviewStats, ScreenshotsResponse, SearchResult, SiteConfig, SiteStats, SiteUIConfig, SystemRequirementsResponse, TelegramAuthResponse, TelegramBotLoginOptions, TelegramInitResponse, TelegramWidgetRenderOptions, TelegramWidgetUser, TopupMethod, TopupResponse, TopupStatus, Transaction, User, UserBalance, WebPushSubscriptionInput } from "./types";
 /** Supported storefront locales — extend as new languages land. */
 export type SdkLocale = "ru" | "en";
+/**
+ * ISO-4217 codes the API can quote prices in. Matches the server-side
+ * `DisplayCurrency` union in `apps/api/src/utils/currency.ts`. RUB is
+ * the default when nothing is configured; USD is the canonical base
+ * price in the DB.
+ */
+export type SdkCurrency = "RUB" | "USD" | "EUR" | "GBP" | "KZT" | "UAH" | "TRY" | "BRL" | "ARS" | "INR" | "PLN" | "CZK";
 export interface GameCoreOptions {
     /** Site API key (gc_live_xxx or gc_test_xxx) */
     apiKey: string;
@@ -16,12 +23,25 @@ export interface GameCoreOptions {
      * Omit to keep the legacy behaviour (server falls back to "ru").
      */
     locale?: SdkLocale;
+    /**
+     * Default display currency for catalog product prices. When set,
+     * every request sends an `X-Currency` header so the API converts
+     * `price` / `priceWithoutDiscount` into that ISO-4217 code (using
+     * live FX rates) and stamps the resolved code on each product
+     * response under the `currency` field.
+     *
+     * Per-call `?currency=` overrides this default. Omit to keep RUB
+     * (the legacy default — every existing storefront keeps working
+     * without a code change).
+     */
+    currency?: SdkCurrency;
 }
 export declare class GameCoreClient {
     private apiKey;
     private baseUrl;
     private onAuthError?;
     private defaultLocale?;
+    private defaultCurrency?;
     constructor(options: GameCoreOptions);
     /**
      * Switch the client's default locale at runtime — useful for a
@@ -31,6 +51,14 @@ export declare class GameCoreClient {
     setLocale(locale: SdkLocale | undefined): void;
     /** Current default locale (undefined when none set). */
     getLocale(): SdkLocale | undefined;
+    /**
+     * Switch the client's default display currency at runtime — wire to
+     * a storefront currency picker so the next product fetch comes back
+     * already converted, without re-instantiating the client.
+     */
+    setCurrency(currency: SdkCurrency | undefined): void;
+    /** Current default currency (undefined when none set → API returns RUB). */
+    getCurrency(): SdkCurrency | undefined;
     private request;
     site: {
         /** Get site configuration (modules, auth methods, payments, currency) */
@@ -468,8 +496,17 @@ export declare class GameCoreClient {
         getDeliveryHelp: (gameSlug: string) => Promise<DeliveryHelpResponse>;
         /** Get categories for a game with product counts and delivery metadata */
         getCategories: (gameSlug: string) => Promise<Category[]>;
-        /** Get products for a game with optional filters */
-        getProducts: (gameSlug: string, filters?: ProductFilters) => Promise<Product[]>;
+        /**
+         * Get products for a game with optional filters.
+         *
+         * `filters.currency` overrides the client-level default for
+         * this call only — useful for an admin tool that has a
+         * Storefront in one currency but needs to preview USD pricing
+         * without flipping the whole client.
+         */
+        getProducts: (gameSlug: string, filters?: ProductFilters & {
+            currency?: SdkCurrency;
+        }) => Promise<Product[]>;
         /** Get products grouped by category */
         getProductsGrouped: (gameSlug: string) => Promise<{
             category: Category;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { GameCoreClient } from "./client";
-export type { GameCoreOptions } from "./client";
+export type { GameCoreOptions, SdkCurrency, SdkLocale } from "./client";
 export * from "./types";
 export { convertPrice, formatPrice, generateIdempotencyKey } from "./utils";

package/dist/index.js

@@ -37,11 +37,13 @@ class GameCoreClient {
   baseUrl;
   onAuthError;
   defaultLocale;
+  defaultCurrency;
   constructor(options) {
     this.apiKey = options.apiKey;
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
     this.onAuthError = options.onAuthError;
     this.defaultLocale = options.locale;
+    this.defaultCurrency = options.currency;
   }
   setLocale(locale) {
     this.defaultLocale = locale;
@@ -49,6 +51,12 @@ class GameCoreClient {
   getLocale() {
     return this.defaultLocale;
   }
+  setCurrency(currency) {
+    this.defaultCurrency = currency;
+  }
+  getCurrency() {
+    return this.defaultCurrency;
+  }
   async request(method, path, body, options) {
     const headers = {
       "X-Api-Key": this.apiKey,
@@ -57,6 +65,9 @@ class GameCoreClient {
     if (this.defaultLocale) {
       headers["Accept-Language"] = this.defaultLocale;
     }
+    if (this.defaultCurrency) {
+      headers["X-Currency"] = this.defaultCurrency;
+    }
     if (options?.idempotencyKey) {
       headers["X-Idempotency-Key"] = options.idempotencyKey;
     }
@@ -307,6 +318,8 @@ class GameCoreClient {
         qs.set("minPrice", String(filters.minPrice));
       if (filters?.maxPrice != null)
         qs.set("maxPrice", String(filters.maxPrice));
+      if (filters?.currency)
+        qs.set("currency", filters.currency);
       const q = qs.toString();
       return this.request("GET", `/catalog/games/${gameSlug}/products${q ? `?${q}` : ""}`);
     },

package/dist/types.d.ts

@@ -381,6 +381,14 @@ export interface Product {
     estimatedDelivery?: string;
     icon: string | null;
     price: number | null;
+    /**
+     * ISO-4217 code (`RUB`, `USD`, `EUR`, `KZT`, …) for `price` and
+     * `priceWithoutDiscount`. Set by the API on every product response
+     * since gamecore-api 2026-05-11 / SDK 0.27 — the storefront should
+     * use this directly rather than tracking the requested currency
+     * separately. Falls through as `undefined` from older API builds.
+     */
+    currency?: string;
     priceWithoutDiscount?: number;
     discountPercent?: number;
     gameId: string;

package/examples/01-quickstart.ts

@@ -46,25 +46,30 @@ 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.
 //
-//    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.
+//    The SDK's `CheckoutRequest.items` type currently marks several
+//    fields optional, but the API's body schema (TypeBox) rejects
+//    requests that omit them:
+//      • productId    — REQUIRED, the supplier product
+//      • gameId       — REQUIRED, the game slug. Drives routing for
+//                       Steam top-ups, SuperPass bundles, and
+//                       Robux-via-pass; the backend also reads it
+//                       directly outside those paths.
+//      • gameName     — REQUIRED by body validation (maxLength 500).
+//      • productName  — REQUIRED by body validation (maxLength 500).
+//      • deliveryData — REQUIRED object (can be `{}`). For Steam /
+//                       Roblox / login-required products it carries
+//                       account name, server id, top-up currency, etc.
+//      • amount       — optional. Quantity for fixed-price items
+//                       (default 1) OR the top-up amount in local
+//                       currency for Steam / variable-amount products.
 const checkout = await gc.checkout.create({
 	email: "buyer@example.com",
 	items: [
 		{
 			productId: product.id,
 			gameId: game.slug,
+			gameName: game.name,
+			productName: product.name,
 			amount: 1,
 			deliveryData: {},
 		},

package/examples/05-currency-switching.ts

@@ -0,0 +1,74 @@
+/**
+ * 05 — Display-currency switching (RUB / USD / EUR / KZT / UAH / TRY / …)
+ *
+ * Catalog endpoints quote product prices in any of the supported ISO-4217
+ * currencies. RUB is the legacy default — a client that doesn't ask for
+ * anything else keeps getting ruble prices, same as before SDK 0.27.
+ *
+ * Resolution order on the server (highest priority first):
+ *   1. `?currency=USD` query param (per-call override)
+ *   2. `X-Currency` request header (SDK injects when constructor has
+ *      `currency: "USD"` configured)
+ *   3. RUB default
+ *
+ * Run with:
+ *   GAMECORE_API_KEY=gc_live_... bun run examples/05-currency-switching.ts
+ */
+
+import { GameCoreClient, type SdkCurrency } from "@gamecore-api/sdk";
+
+const apiKey = process.env.GAMECORE_API_KEY!;
+const baseUrl = "https://api.gamecore-api.tech";
+
+// Approach A — one client per currency. Simplest for a single-currency
+// storefront (e.g. a US store that always shows USD).
+const ru = new GameCoreClient({ apiKey, baseUrl, currency: "RUB" });
+const usd = new GameCoreClient({ apiKey, baseUrl, currency: "USD" });
+
+const gameSlug = "free-fire";
+const ruProducts = await ru.catalog.getProducts(gameSlug);
+const usdProducts = await usd.catalog.getProducts(gameSlug);
+console.log("RUB first product:", {
+	name: ruProducts[0]?.name,
+	price: ruProducts[0]?.price,
+	currency: ruProducts[0]?.currency, // "RUB"
+});
+console.log("USD first product:", {
+	name: usdProducts[0]?.name,
+	price: usdProducts[0]?.price,
+	currency: usdProducts[0]?.currency, // "USD"
+});
+
+// Approach B — single client, switch at runtime. Wire this to a
+// storefront currency picker so the next product fetch comes back
+// already converted.
+const gc = new GameCoreClient({ apiKey, baseUrl });
+console.log("default currency:", gc.getCurrency()); // undefined → RUB
+gc.setCurrency("KZT");
+const kztProducts = await gc.catalog.getProducts(gameSlug);
+console.log(
+	"KZT first product:",
+	kztProducts[0]?.price,
+	kztProducts[0]?.currency,
+);
+
+// Approach C — per-call override. Admin tool example: a Russian
+// operator inspects an EN/EUR preview of a product without flipping
+// the rest of the session.
+const previewCurrencies: SdkCurrency[] = ["EUR", "TRY", "UAH"];
+for (const ccy of previewCurrencies) {
+	const products = await gc.catalog.getProducts(gameSlug, { currency: ccy });
+	console.log(`${ccy}:`, products[0]?.price, products[0]?.currency);
+}
+
+// Notes for AI agents copying this example:
+//   • Don't try to convert prices yourself — the server applies live FX
+//     rates from open.er-api.com and rounds per-currency (whole KZT,
+//     2-decimal EUR, etc.). Doing it client-side will drift.
+//   • Always use `product.currency` for the display string instead of
+//     hardcoding the requested code — the server is the source of
+//     truth when an FX rate is missing.
+//   • Checkout is unrelated: payment gateways still settle in RUB or
+//     USD depending on the chosen `paymentMethod`. The display
+//     currency is purely catalog-side until checkout currency support
+//     ships.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gamecore-api/sdk",
-	"version": "0.26.2",
+	"version": "0.27.0",
 	"description": "TypeScript SDK for GameCore API — browser-safe, zero dependencies",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",