@gamecore-api/sdk 0.20.0 → 0.25.0

package/dist/client.d.ts

@@ -1,4 +1,6 @@
-import type { Announcement, AnnouncementBar, CartItem, CashbackPreview, CatalogSection, Category, CategoryInfo, CheckoutRequest, CheckoutResponse, CompleteWithBalanceResult, Conversation, ConversationDetail, CouponResult, DailyBonusClaimResult, DailyBonusStatus, ExchangeRates, Favorite, Game, GameDetail, GiftCard, LegalDocument, LevelStatus, Notification, Order, PagedGamesResponse, PlatformInfo, PaginatedResponse, PaymentInfo, PaymentMethod, Product, ProductFilters, PublicCoupon, Quest, QuestCompleteResult, ReferralCommission, ReferralLink, ReferralPerformance, ReferralStats, Review, ReviewCreateResult, ReviewProof, ReviewStats, ScreenshotsResponse, SearchResult, SiteConfig, SiteStats, SiteUIConfig, SystemRequirementsResponse, TelegramAuthResponse, TelegramBotLoginOptions, TelegramInitResponse, TelegramWidgetRenderOptions, TelegramWidgetUser, TopupMethod, TopupResponse, TopupStatus, Transaction, User, UserBalance, WebPushSubscriptionInput } from "./types";
+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";
 export interface GameCoreOptions {
     /** Site API key (gc_live_xxx or gc_test_xxx) */
     apiKey: string;
@@ -6,12 +8,29 @@ export interface GameCoreOptions {
     baseUrl: string;
     /** Called on 401 — use to redirect to login */
     onAuthError?: () => void;
+    /**
+     * Default locale for catalog/CMS responses. When set, every request
+     * sends an `Accept-Language` header so the API returns localized
+     * name/description fields without each call passing `locale=` itself.
+     * Per-call `locale` arguments still take precedence over the default.
+     * Omit to keep the legacy behaviour (server falls back to "ru").
+     */
+    locale?: SdkLocale;
 }
 export declare class GameCoreClient {
     private apiKey;
     private baseUrl;
     private onAuthError?;
+    private defaultLocale?;
     constructor(options: GameCoreOptions);
+    /**
+     * Switch the client's default locale at runtime — useful for a
+     * storefront language switcher that should not have to re-instantiate
+     * the client.
+     */
+    setLocale(locale: SdkLocale | undefined): void;
+    /** Current default locale (undefined when none set). */
+    getLocale(): SdkLocale | undefined;
     private request;
     site: {
         /** Get site configuration (modules, auth methods, payments, currency) */
@@ -111,6 +130,51 @@ export declare class GameCoreClient {
             success: boolean;
             requestId: number;
         }>;
+        /**
+         * Get the per-site review-payout policy. Storefronts use this on
+         * the order success page to decide whether to advertise a
+         * cashback bonus for posting a review, and to enforce the
+         * minimum text length client-side before submission.
+         */
+        getReviewPolicy: () => Promise<ReviewPolicy>;
+        /**
+         * Get FAQ entries for this site. Without `gameId`, returns all
+         * active site-wide FAQ entries (rows with `gameId: null`). When
+         * `gameId` is provided, returns ONLY entries scoped to that
+         * game — site-wide entries are NOT included in the response.
+         * Storefronts that want both site-wide and game-specific FAQ
+         * on the same page must call this method twice and merge the
+         * results client-side. `position` is the display order (lower
+         * first); `gameId: null` marks site-wide entries.
+         */
+        getFaq: (gameId?: number) => Promise<FaqListResponse>;
+        /**
+         * List published CMS articles of a given type for the current
+         * site. Returns a summary projection (no body) — call
+         * `getArticle()` to fetch a single article's full content.
+         *
+         * `locale` defaults to the site's default locale on the
+         * server (currently "ru") when omitted. `limit` is capped
+         * server-side at 100; `offset` enables pagination.
+         */
+        getArticles: (type: CmsArticleType, options?: {
+            locale?: CmsArticleLocale;
+            limit?: number;
+            offset?: number;
+        }) => Promise<CmsArticleListResponse>;
+        /**
+         * Fetch a single published CMS article by slug. The server
+         * falls back to the RU article when the requested locale is
+         * missing — inspect `article.locale` on the response to
+         * detect fallback.
+         *
+         * Throws `GameCoreError(404)` when no published article matches
+         * the requested type/slug pair under either the requested or
+         * fallback locale.
+         */
+        getArticle: (type: CmsArticleType, slug: string, options?: {
+            locale?: CmsArticleLocale;
+        }) => Promise<CmsArticleResponse>;
     };
     auth: {
         /** Start Telegram auth flow → returns bot link for user to click */
@@ -393,6 +457,15 @@ export declare class GameCoreClient {
          * 2026-05-01 (Wave 5 #50).
          */
         getGameScreenshots: (gameSlug: string) => Promise<ScreenshotsResponse>;
+        /**
+         * Pre-checkout delivery help (instructions, screenshots,
+         * warnings) configured by the operator for a game page. The
+         * endpoint returns `{ deliveryHelp: DeliveryHelp | null }` flat
+         * — without the `success`/`data` envelope — so the SDK does not
+         * auto-unwrap and the response shape mirrors the wire payload
+         * directly. `null` means no help content is configured.
+         */
+        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 */
@@ -537,6 +610,14 @@ export declare class GameCoreClient {
         completeWithBalance: (paymentCode: string) => Promise<CompleteWithBalanceResult>;
         /** Get available payment methods for checkout */
         getPaymentMethods: () => Promise<PaymentMethod[]>;
+        /**
+         * Get the current status of a payment plus its child orders by
+         * payment code. Public endpoint — no auth required, so it can
+         * power a "track your order" lookup page from a guest's email
+         * receipt link. `gatewayPaymentUrl` is `null` once the payment
+         * has been completed or expired.
+         */
+        getStatus: (code: string) => Promise<CheckoutStatus>;
     };
     orders: {
         /** List all orders for authenticated user */
@@ -712,6 +793,21 @@ export declare class GameCoreClient {
         unsubscribePush: (endpoint: string) => Promise<{
             success: boolean;
         }>;
+        /**
+         * List the current user's "please add this game" requests,
+         * newest first. Status is one of `pending` / `reviewed` /
+         * `completed` / `rejected` (string-typed because the server
+         * may add new states without an SDK bump).
+         */
+        getGameRequests: () => Promise<GameRequestList>;
+        /**
+         * Aggregated counters for the header / sidebar — cart size,
+         * unread notifications, pending review prompts, balances, and
+         * whether the user has an open support thread. One round-trip
+         * replaces several smaller calls; useful as a SWR pre-fetch on
+         * authenticated route shells.
+         */
+        getSummary: () => Promise<ProfileSummary>;
     };
     favorites: {
         /** List user's favorite products */
@@ -807,6 +903,13 @@ export declare class GameCoreClient {
             from?: Date | string;
             to?: Date | string;
         }) => Promise<ReferralPerformance>;
+        /**
+         * Transfer all eligible pending referral commissions to the
+         * user's permanent balance. Returns the total transferred amount,
+         * how many commissions were moved, and the user's new permanent
+         * balance.
+         */
+        transferToBalance: () => Promise<ReferralTransferResult>;
     };
     reviews: {
         /** Get public reviews (paginated) */

package/dist/index.js

@@ -36,16 +36,27 @@ class GameCoreClient {
   apiKey;
   baseUrl;
   onAuthError;
+  defaultLocale;
   constructor(options) {
     this.apiKey = options.apiKey;
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
     this.onAuthError = options.onAuthError;
+    this.defaultLocale = options.locale;
+  }
+  setLocale(locale) {
+    this.defaultLocale = locale;
+  }
+  getLocale() {
+    return this.defaultLocale;
   }
   async request(method, path, body, options) {
     const headers = {
       "X-Api-Key": this.apiKey,
       "Content-Type": "application/json"
     };
+    if (this.defaultLocale) {
+      headers["Accept-Language"] = this.defaultLocale;
+    }
     if (options?.idempotencyKey) {
       headers["X-Idempotency-Key"] = options.idempotencyKey;
     }
@@ -87,7 +98,28 @@ class GameCoreClient {
     getBanners: () => this.request("GET", "/site/banners"),
     getAnnouncementBar: () => this.request("GET", "/site/announcement-bar"),
     getSitemapData: () => this.request("GET", "/seo/sitemap-data"),
-    requestGame: (data) => this.request("POST", "/site/request-game", data)
+    requestGame: (data) => this.request("POST", "/site/request-game", data),
+    getReviewPolicy: () => this.request("GET", "/site/review-policy"),
+    getFaq: (gameId) => {
+      const qs = gameId !== undefined ? `?gameId=${encodeURIComponent(gameId)}` : "";
+      return this.request("GET", `/site/faq${qs}`);
+    },
+    getArticles: (type, options) => {
+      const params = new URLSearchParams;
+      if (options?.locale)
+        params.set("locale", options.locale);
+      if (options?.limit !== undefined)
+        params.set("limit", String(options.limit));
+      if (options?.offset !== undefined)
+        params.set("offset", String(options.offset));
+      const qs = params.toString();
+      const path = qs.length > 0 ? `/site/cms/${encodeURIComponent(type)}?${qs}` : `/site/cms/${encodeURIComponent(type)}`;
+      return this.request("GET", path);
+    },
+    getArticle: (type, slug, options) => {
+      const qs = options?.locale ? `?locale=${options.locale}` : "";
+      return this.request("GET", `/site/cms/${encodeURIComponent(type)}/${encodeURIComponent(slug)}${qs}`);
+    }
   };
   auth = {
     initTelegram: () => this.request("POST", "/auth/telegram/init"),
@@ -259,6 +291,7 @@ class GameCoreClient {
     getRecommendations: (gameSlug, limit = 8) => this.request("GET", `/catalog/games/${gameSlug}/recommendations?limit=${limit}`),
     getGameSystemRequirements: (gameSlug) => this.request("GET", `/catalog/games/${gameSlug}/system-requirements`),
     getGameScreenshots: (gameSlug) => this.request("GET", `/catalog/games/${gameSlug}/screenshots`),
+    getDeliveryHelp: (gameSlug) => this.request("GET", `/catalog/games/${encodeURIComponent(gameSlug)}/delivery-help`),
     getCategories: (gameSlug) => this.request("GET", `/catalog/games/${gameSlug}/categories`),
     getProducts: (gameSlug, filters) => {
       const qs = new URLSearchParams;
@@ -306,7 +339,8 @@ class GameCoreClient {
     getPaymentMethods: async () => {
       const res = await this.request("GET", "/checkout/payment-methods", undefined, { rawResponse: true });
       return res.methods || [];
-    }
+    },
+    getStatus: (code) => this.request("GET", `/checkout/${encodeURIComponent(code)}/status`)
   };
   orders = {
     list: () => this.request("GET", "/orders"),
@@ -377,7 +411,9 @@ class GameCoreClient {
     subscribePush: (subscription) => this.request("POST", "/profile/push/subscribe", subscription),
     unsubscribePush: (endpoint) => this.request("POST", "/profile/push/unsubscribe", {
       endpoint
-    })
+    }),
+    getGameRequests: () => this.request("GET", "/profile/game-requests"),
+    getSummary: () => this.request("GET", "/profile/summary")
   };
   favorites = {
     list: () => this.request("GET", "/favorites"),
@@ -413,7 +449,8 @@ class GameCoreClient {
       }
       const q = qs.toString();
       return this.request("GET", `/referral/performance${q ? `?${q}` : ""}`);
-    }
+    },
+    transferToBalance: async () => this.request("POST", "/referral/transfer")
   };
   reviews = {
     listPublic: (params) => {

package/dist/types.d.ts

@@ -532,6 +532,30 @@ export interface ScreenshotsResponse {
     source: "steam";
     fetchedAt: string;
 }
+/**
+ * Pre-checkout delivery help block for a game page. Operators
+ * configure copy/screenshots so the storefront can show "how to find
+ * your player ID" / "where to look up your login" instructions
+ * before the user fills the checkout form. All fields except `label`
+ * are optional — the storefront should render whatever combination
+ * the operator provided.
+ */
+export interface DeliveryHelp {
+    label: string;
+    helpText?: string;
+    screenshots?: string[];
+    warnings?: string[];
+    externalUrl?: string;
+}
+/**
+ * Response from `gc.catalog.getDeliveryHelp()`. `deliveryHelp` is
+ * `null` when the game has no help content configured — the
+ * storefront should hide the help panel in that case. The endpoint
+ * returns the field flat (no `success`/`data` envelope).
+ */
+export interface DeliveryHelpResponse {
+    deliveryHelp: DeliveryHelp | null;
+}
 export interface CheckoutRequest {
     email?: string;
     items: Array<{
@@ -1085,6 +1109,17 @@ export interface ReferralPerformance {
     totalTransactions: number;
     newMembers: number;
 }
+/**
+ * Result of `gc.referrals.transferToBalance()` — the SDK auto-unwraps
+ * the `{success, data}` envelope so callers receive this inner object
+ * directly. `transferredAmount` is the total moved from pending
+ * commissions to permanent balance.
+ */
+export interface ReferralTransferResult {
+    transferredAmount: number;
+    transferredCount: number;
+    newPermanentBalance: number;
+}
 export interface TopupMethod {
     type: string;
     label: string;
@@ -1256,6 +1291,125 @@ export interface WebhookPayload {
     sandbox: boolean;
     data: Record<string, unknown>;
 }
+/**
+ * Per-site review-payout policy. Storefronts use this to render the
+ * "leave a review and get +N% cashback" banner on the order success
+ * page. `enabled: false` means reviews are accepted but no payout is
+ * promised — render the form without the bonus copy.
+ */
+export interface ReviewPolicy {
+    enabled: boolean;
+    percent: number;
+    expiresInDays: number;
+    requiresText: boolean;
+    minTextLength: number;
+}
+/** Single FAQ entry. `gameId: null` means a global (site-wide) entry. */
+export interface FaqItem {
+    id: number;
+    question: string;
+    answer: string;
+    gameId: number | null;
+    position: number;
+}
+/** Response from `GET /site/faq`. */
+export interface FaqListResponse {
+    items: FaqItem[];
+}
+/** A single "please add this game" request submitted by the current user. */
+export interface GameRequestItem {
+    id: number;
+    gameName: string;
+    comment: string | null;
+    gameUrl: string | null;
+    status: string;
+    createdAt: string;
+}
+/** Inner payload of `GET /profile/game-requests` (envelope auto-unwrapped). */
+export interface GameRequestList {
+    items: GameRequestItem[];
+}
+/** Aggregated profile counters for header / sidebar widgets. */
+export interface ProfileSummary {
+    cartCount: number;
+    unreadNotifications: number;
+    pendingReviews: number;
+    hasOpenSupportThread: boolean;
+    permanentBalance: number;
+    bonusBalance: number;
+}
+/** Status of a checkout payment plus its child orders. Public endpoint. */
+export interface CheckoutStatus {
+    payment: {
+        code: string;
+        status: string;
+        totalAmount: number;
+        gatewayPaymentUrl: string | null;
+        createdAt: string;
+        completedAt: string | null;
+    };
+    orders: Array<{
+        code: string;
+        status: string;
+        gameName: string;
+        totalAmount: number;
+    }>;
+}
+export type CmsArticleType = "news" | "promo" | "footer_block";
+export type CmsArticleLocale = "ru" | "en";
+export type CmsArticleStatus = "draft" | "published" | "archived";
+/**
+ * Summary projection returned by `gc.site.getArticles()` — list pages
+ * stay cheap by omitting the article body. Storefronts call
+ * `gc.site.getArticle(type, slug)` to fetch the full body when the
+ * user opens the article.
+ *
+ * Date fields (`publishedAt`) are ISO-8601 strings on the wire.
+ */
+export interface CmsArticleSummary {
+    id: number;
+    type: CmsArticleType;
+    locale: CmsArticleLocale;
+    slug: string;
+    title: string;
+    summary: string | null;
+    coverImage: string | null;
+    publishedAt: string | null;
+    sortOrder: number;
+}
+/**
+ * Full CMS article shape returned by `gc.site.getArticle()`. The
+ * `locale` field reflects the article's actual language — when the
+ * storefront requests `en` and the article only exists in `ru`, the
+ * server falls back and the response carries `locale: "ru"`.
+ *
+ * Date fields are ISO-8601 strings.
+ */
+export interface CmsArticle {
+    id: number;
+    siteId: number;
+    type: CmsArticleType;
+    locale: CmsArticleLocale;
+    slug: string;
+    title: string;
+    summary: string | null;
+    body: string;
+    coverImage: string | null;
+    status: CmsArticleStatus;
+    publishedAt: string | null;
+    sortOrder: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Response from `GET /site/cms/:type`. */
+export interface CmsArticleListResponse {
+    items: CmsArticleSummary[];
+    total: number;
+}
+/** Response from `GET /site/cms/:type/:slug`. */
+export interface CmsArticleResponse {
+    article: CmsArticle;
+}
 /** Standard API response wrapper. Most endpoints return { success, data } or { success, error }. */
 export interface ApiResponse<T = unknown> {
     success: boolean;

package/package.json

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