@gamecore-api/sdk 0.9.0 → 0.13.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { TelegramInitResponse, User, SiteConfig, ExchangeRates, LegalDocument, Game, GameDetail, Product, SearchResult, Category, CartItem, CheckoutRequest, CheckoutResponse, Order, UserBalance, LevelStatus, Transaction, Notification, Favorite, Review, ReviewStats, CouponResult, ReferralStats, ReferralLink, ReferralCommission, TopupMethod, TopupResponse, TopupStatus, GiftCard, Announcement, AnnouncementBar, SiteUIConfig, PaymentMethod, CatalogSection, SiteStats, ProductFilters, PaginatedResponse } from "./types";
+import type { TelegramInitResponse, TelegramWidgetUser, TelegramAuthResponse, User, SiteConfig, ExchangeRates, LegalDocument, Game, GameDetail, Product, SearchResult, Category, CartItem, CheckoutRequest, CheckoutResponse, Conversation, ConversationDetail, Order, PaymentInfo, CompleteWithBalanceResult, UserBalance, WebPushSubscriptionInput, LevelStatus, Transaction, Notification, Favorite, Review, ReviewCreateResult, ReviewStats, CouponResult, ReferralStats, ReferralLink, ReferralCommission, ReferralPerformance, TopupMethod, TopupResponse, TopupStatus, GiftCard, Announcement, AnnouncementBar, SiteUIConfig, PaymentMethod, CatalogSection, SiteStats, ProductFilters, PaginatedResponse, PagedGamesResponse } from "./types";
 export interface GameCoreOptions {
     /** Site API key (gc_live_xxx or gc_test_xxx) */
     apiKey: string;
@@ -47,33 +47,141 @@ export declare class GameCoreClient {
         }>;
         /** Get per-site catalog sections (category tabs config) */
         getCatalogSections: () => Promise<CatalogSection[]>;
-        /** Get active hero banners for carousel */
+        /**
+         * Get active hero banners for the storefront carousel.
+         * Each banner carries optional visual fields plus a `url`
+         * destination — `null` means the banner is display-only and
+         * should not be rendered as a link.
+         */
         getBanners: () => Promise<{
             id: number;
             title: string | null;
             description: string | null;
             imageUrl: string | null;
             color: string | null;
+            url: string | null;
             scope: string;
             priority: number;
         }[]>;
         /** Get announcement bar settings (text, link, enabled) */
         getAnnouncementBar: () => Promise<AnnouncementBar>;
+        /**
+         * Get sitemap data for self-generated storefront sitemaps.
+         * Returns `{ slug, updatedAt }` for every game visible on
+         * this site. Use `updatedAt` as `lastModified` in Next.js
+         * `sitemap.ts` so Google's crawler respects unchanged pages
+         * instead of stamping the whole catalog with `new Date()`.
+         */
+        getSitemapData: () => Promise<{
+            slug: string;
+            updatedAt: string;
+        }[]>;
+        /**
+         * Submit a "please add this game" request. Works for both
+         * authenticated users (the server attaches the user id so
+         * support can reach back) and anonymous visitors.
+         *
+         * Rate-limited server-side. The optional `website` field is
+         * a honeypot — leave it `undefined` in real code; the
+         * storefront can render an invisible input under that name
+         * so scrapers self-identify.
+         *
+         * @returns The new request id and a success flag. A filled
+         *   honeypot still returns `success: true` with
+         *   `requestId: -1` so bots cannot distinguish a real save
+         *   from a silent drop.
+         */
+        requestGame: (data: {
+            gameName: string;
+            comment?: string;
+            gameUrl?: string;
+            website?: string;
+        }) => Promise<{
+            success: boolean;
+            requestId: number;
+        }>;
     };
     auth: {
         /** Start Telegram auth flow → returns bot link for user to click */
         initTelegram: () => Promise<TelegramInitResponse>;
         /** Poll Telegram auth status until authenticated or expired */
         pollTelegramStatus: (token: string, intervalMs?: number) => Promise<User>;
-        /** Get VK OAuth redirect URL */
-        getVkAuthUrl: (redirectUri: string) => Promise<{
+        /**
+         * Verify Telegram Mini App initData and issue a session cookie.
+         * Call this when your storefront is opened inside Telegram via the
+         * bot's Mini App / Web App button — `window.Telegram.WebApp.initData`
+         * is the raw URL-encoded string you should pass in. The backend
+         * validates the HMAC signature against the bot token and mints a
+         * normal auth cookie, so the rest of the site stays logged in.
+         * Optional `ref` threads a referral code through user creation.
+         */
+        verifyMiniApp: (initData: string, ref?: string) => Promise<TelegramAuthResponse>;
+        /**
+         * Verify Telegram Login Widget payload (JSON POST variant) and
+         * issue a session cookie. Use this when you embed the Login Widget
+         * with `data-onauth` (JS callback) instead of `data-auth-url`
+         * (full-page redirect) — pass the object the widget handed you
+         * directly to this method.
+         */
+        verifyTelegramWidget: (data: TelegramWidgetUser, ref?: string) => Promise<TelegramAuthResponse>;
+        /**
+         * Get VK OAuth authorize URL (authorization code flow).
+         *
+         * Backend generates a single-use state nonce, stores it server-
+         * side, and returns a URL pointing at VK with response_type=code.
+         * The storefront redirects the user to this URL; VK redirects
+         * back to `redirectUri` with ?code=...&state=...; the storefront
+         * then calls {@link vkCallback} with those two values.
+         *
+         * `redirectUri` must exactly match one of the site's allowed
+         * origins configured in master-admin — the backend validates
+         * this before storing the state. `ref` is an optional referral
+         * code that gets threaded through to user registration.
+         */
+        getVkAuthUrl: (redirectUri: string, ref?: string) => Promise<{
             url: string;
+            state: string;
+        }>;
+        /**
+         * Exchange an authorization code for a session cookie (code flow).
+         * Call this after VK redirects back to your storefront with
+         * ?code=...&state=... in the query string. The backend validates
+         * state (single-use), exchanges the code with VK server-to-server
+         * using the site's client_secret, fetches the user profile, and
+         * mints a normal auth cookie. The VK access token never reaches
+         * the client.
+         */
+        vkCallback: (code: string, state: string) => Promise<{
+            status: string;
+            user: User;
         }>;
-        /** Verify VK access token and login/register */
+        /**
+         * Verify a VK access token from the deprecated implicit flow.
+         * @deprecated Use {@link getVkAuthUrl} + {@link vkCallback} instead.
+         * This endpoint is kept alive for backwards compatibility while
+         * storefronts migrate to the code flow. It will be removed in a
+         * future major release.
+         */
         verifyVk: (accessToken: string, ref?: string) => Promise<{
             status: string;
             user: User;
         }>;
+        /** Register with email + password. No auth required. */
+        register: (email: string, password: string, firstName?: string, ref?: string) => Promise<{
+            success: boolean;
+            token: string;
+            user: User;
+        }>;
+        /** Login with email + password. No auth required. */
+        login: (email: string, password: string) => Promise<{
+            success: boolean;
+            token: string;
+            user: User;
+        }>;
+        /** Change password (requires auth). Revokes all other sessions. */
+        changePassword: (currentPassword: string, newPassword: string) => Promise<{
+            success: boolean;
+        }>;
         /** Get current authenticated user */
         getMe: () => Promise<User>;
         /** Logout and clear session */
@@ -88,6 +196,22 @@ export declare class GameCoreClient {
         }>;
         /** Link VK account to current user */
         linkVk: (accessToken: string) => Promise<void>;
+        /**
+         * Attach an email + password identity to the currently
+         * authenticated user. Use this for Telegram-only / VK-only
+         * accounts that want a backup login method. The user must
+         * not already have an email set — update flows go through
+         * `changePassword()` or a future `changeEmail()` method.
+         *
+         * Rate-limited to the same bucket as `/auth/register`.
+         * Returns the normalised email on success; throws 409 if the
+         * user already has an email or if another account on this
+         * site owns the address.
+         */
+        linkEmail: (email: string, password: string) => Promise<{
+            success: boolean;
+            email: string;
+        }>;
         /** Unlink auth provider */
         unlinkProvider: (provider: string) => Promise<void>;
         /** Preview VK account merge (before confirming) */
@@ -102,20 +226,49 @@ export declare class GameCoreClient {
         }>;
     };
     catalog: {
-        /** Get all games. Use inStockOnly:true for only games with products. include:"meta" for categories/deliveryTypes. */
+        /**
+         * Get paginated games catalog.
+         *
+         * Returns `{ data: Game[], pagination: { page, limit, total, totalPages, hasMore } }`.
+         *
+         * @param params.page - Page number (1-based, default 1)
+         * @param params.limit - Items per page (1-200, default 50)
+         * @param params.inStockOnly - Only games that have products in stock
+         * @param params.include - "meta" to include categories/deliveryTypes
+         * @param params.sort - Sort order: "popular" | "name" | "new" | "soldCount"
+         * @param params.q - Search query (Meilisearch or fallback)
+         */
         getGames: (params?: {
+            page?: number;
+            limit?: number;
             locale?: string;
             type?: string;
             deliveryType?: string;
             include?: string;
             inStockOnly?: boolean;
             sort?: "popular" | "name" | "new" | "soldCount";
-        }) => Promise<Game[]>;
+            q?: string;
+        }) => Promise<PagedGamesResponse>;
         /** Get homepage ranked games */
         getHomepageGames: () => Promise<Game[]>;
         /** Get single game with categories */
         getGame: (slug: string, locale?: string) => Promise<GameDetail>;
-        /** Get recommended games (same type, random) */
+        /**
+         * Get recommended games for a game detail page
+         * ("you might also like" / "related games").
+         *
+         * Returns games of the same `type` as the source game, randomly
+         * selected and filtered by per-site visibility overrides.
+         *
+         * @param gameSlug - Source game slug. Must be the **canonical**
+         *   slug — this endpoint does NOT resolve aliases and returns an
+         *   empty array for alias inputs. If you only have an alias,
+         *   call `getGame()` first and use
+         *   `result.canonicalSlug ?? result.slug`.
+         * @param limit - Max recommendations (default 8). The backend
+         *   caps the effective limit; very large values are trimmed
+         *   server-side.
+         */
         getRecommendations: (gameSlug: string, limit?: number) => Promise<Game[]>;
         /** Get categories for a game with product counts and delivery metadata */
         getCategories: (gameSlug: string) => Promise<Category[]>;
@@ -148,17 +301,22 @@ export declare class GameCoreClient {
             minItems: number;
             discountPercent: number;
         }[]>;
-        /** Get active promo campaigns */
+        /**
+         * Get active promo campaigns. `targetUrl` is the clickable
+         * destination for the banner artwork (nullable — null means
+         * display-only).
+         */
         getPromos: () => Promise<{
             id: number;
             name: string;
             type: string;
             value: number;
             scope: string;
-            bannerTitle?: string;
-            bannerDescription?: string;
-            bannerImageUrl?: string;
-            bannerColor?: string;
+            bannerTitle?: string | null;
+            bannerDescription?: string | null;
+            bannerImageUrl?: string | null;
+            bannerColor?: string | null;
+            targetUrl?: string | null;
             endsAt?: string;
         }[]>;
         /** Get all games with full metadata (categories, delivery types) */
@@ -173,24 +331,64 @@ export declare class GameCoreClient {
         }>;
     };
     cart: {
-        /** Get cart items for authenticated user */
+        /**
+         * Get cart items for the authenticated user. Each row comes
+         * back with `quantity`, `addedAt`, and `gameIcon` /
+         * `productIcon` populated by the server (2 extra lookups for
+         * the whole cart, not per row).
+         */
         get: () => Promise<CartItem[]>;
-        /** Add single item to cart */
+        /**
+         * Add a single item to the cart. `quantity` is optional and
+         * defaults to `1`. The server caps per-row quantity at 999.
+         */
         add: (item: Omit<CartItem, "id">) => Promise<CartItem>;
-        /** Sync localStorage cart to server (replaces server cart) */
+        /**
+         * Replace the server cart with the given list. Kept for
+         * backwards compatibility with SDK <= 0.12 and for the
+         * "clear everything and insert fresh" use case. Prefer
+         * `cart.merge()` when handling the guest → authed handoff so
+         * an existing server cart is not wiped.
+         */
         sync: (items: Omit<CartItem, "id">[]) => Promise<CartItem[]>;
+        /**
+         * Merge the given items into the server cart without wiping
+         * it. Items colliding on `(productId, deliveryData)` add
+         * their quantities (capped at 999 per row); new rows are
+         * inserted. Use this when a guest with a localStorage cart
+         * logs in and we want to keep both the old server rows and
+         * the newly collected ones.
+         */
+        merge: (items: Omit<CartItem, "id">[]) => Promise<CartItem[]>;
         /** Remove item from cart by ID */
         remove: (id: number) => Promise<void>;
         /** Clear all cart items */
         clear: () => Promise<void>;
     };
     checkout: {
-        /** Create checkout (payment + orders). Auto-generates idempotency key. */
+        /**
+         * Create checkout (payment + orders). Auto-generates idempotency key.
+         *
+         * **Guest checkout:** This method works WITHOUT authentication when
+         * `data.email` is provided and `data.paymentMethod` is a gateway
+         * (not "balance"). The API creates a guest order tied to the email.
+         * No Telegram/VK login required. Balance payments still require auth.
+         */
         create: (data: CheckoutRequest, idempotencyKey?: string) => Promise<CheckoutResponse>;
-        /** Complete payment with balance (no external gateway) */
-        completeWithBalance: (paymentCode: string) => Promise<{
-            success: boolean;
-        }>;
+        /**
+         * Complete a pending payment by deducting the amount from the
+         * user's balance (bonus first, then permanent). Returns the
+         * deduction breakdown and the post-deduction balance so the
+         * success page can render the receipt without a second
+         * `profile.getBalance()` fetch (which is race-prone right
+         * after a completion).
+         *
+         * Idempotent replay: a second call for an already-completed
+         * payment still succeeds and returns the current `newBalance`,
+         * but the deduction breakdown is absent because the original
+         * move is not re-derivable from persisted state.
+         */
+        completeWithBalance: (paymentCode: string) => Promise<CompleteWithBalanceResult>;
         /** Get available payment methods for checkout */
         getPaymentMethods: () => Promise<PaymentMethod[]>;
     };
@@ -199,9 +397,18 @@ export declare class GameCoreClient {
         list: () => Promise<Order[]>;
         /** Get single order by code (includes items + payment) */
         get: (code: string) => Promise<Order>;
-        /** Get orders by payment code (route is under /checkout prefix) */
-        getByPayment: (paymentCode: string) => Promise<{
-            payment: unknown;
+        /**
+         * Get orders by payment code (route is under /checkout prefix).
+         *
+         * Authenticated users are verified via the session cookie.
+         * Guest callers must pass the `guestEmail` used at checkout — the
+         * server enforces a case-insensitive match against the payment
+         * email before returning any order data. Without it, a guest
+         * request returns 404 (the same response as a missing code, so
+         * the endpoint does not leak existence of valid codes).
+         */
+        getByPayment: (paymentCode: string, guestEmail?: string) => Promise<{
+            payment: PaymentInfo;
             orders: Order[];
         }>;
         /** Preview cancel — check if cancellable and refund amount */
@@ -263,6 +470,57 @@ export declare class GameCoreClient {
         getBroadcastStatus: () => Promise<{
             subscribed: boolean;
         }>;
+        /** List the current user's conversations (most-recent first). */
+        getConversations: () => Promise<Conversation[]>;
+        /**
+         * Fetch a conversation header plus its messages. Marks any
+         * unread admin/system messages as read as a side effect.
+         */
+        getConversationMessages: (conversationId: number, params?: {
+            limit?: number;
+            offset?: number;
+        }) => Promise<ConversationDetail>;
+        /**
+         * Submit a code to fulfill an open "code requested" request.
+         * Rate-limited to 5 submissions/minute per IP.
+         */
+        submitCode: (conversationId: number, requestId: number, code: string) => Promise<{
+            success: boolean;
+            data?: {
+                requestId: number;
+            };
+        }>;
+        /**
+         * Submit a screenshot file to fulfill an open "screenshot
+         * requested" request. Accepts a browser `File` object and
+         * delivers it via multipart upload. Rate-limited to 3
+         * submissions/minute per IP.
+         */
+        submitScreenshot: (conversationId: number, requestId: number, file: File) => Promise<{
+            success: boolean;
+            data?: {
+                requestId: number;
+            };
+        }>;
+        /** Get the VAPID public key needed to create a PushSubscription. */
+        getPushPublicKey: () => Promise<{
+            publicKey: string;
+        }>;
+        /**
+         * Register a push subscription for the current user + site.
+         * Call `PushSubscription.toJSON()` in the browser and pass the
+         * result directly.
+         */
+        subscribePush: (subscription: WebPushSubscriptionInput) => Promise<{
+            success: boolean;
+        }>;
+        /**
+         * Remove a push subscription by its endpoint. Call this when
+         * the user opts out or changes devices.
+         */
+        unsubscribePush: (endpoint: string) => Promise<{
+            success: boolean;
+        }>;
     };
     favorites: {
         /** List user's favorite products */
@@ -311,6 +569,38 @@ export declare class GameCoreClient {
         }>;
         /** Get commission history */
         getCommissions: () => Promise<ReferralCommission[]>;
+        /**
+         * Get a small grid of popular products so referrers can
+         * create a one-click reflink without hunting through the
+         * catalog. Sorted primarily by referral transaction count on
+         * the current site — i.e. "games that other referrers are
+         * actually earning commission on". Falls back to the homepage
+         * ranking on brand-new sites that have no referral history
+         * yet, so the grid is never empty for a new referrer.
+         *
+         * @param limit - Max number of entries to return (default 10,
+         *   capped at 50 server-side).
+         */
+        getPopularProducts: (limit?: number) => Promise<{
+            slug: string;
+            name: string;
+            icon: string | null;
+        }[]>;
+        /**
+         * Get performance stats aggregated over an optional date range.
+         *
+         * Pass `from` / `to` as Date or ISO-8601 string to filter
+         * commissions, transactions, and new-member counts. Clicks
+         * remain lifetime — see `ReferralPerformance` docstring for
+         * the rationale. Omit both to get all-time totals.
+         *
+         * Typical usage: wire to 7d / 30d / 90d / all buttons on the
+         * profile referrals dashboard.
+         */
+        getPerformance: (params?: {
+            from?: Date | string;
+            to?: Date | string;
+        }) => Promise<ReferralPerformance>;
     };
     reviews: {
         /** Get public reviews (paginated) */
@@ -328,8 +618,14 @@ export declare class GameCoreClient {
         getMine: () => Promise<Review[]>;
         /** Get orders eligible for review */
         getPending: () => Promise<Order[]>;
-        /** Submit review for a completed order */
-        create: (orderId: number, rating: number, text?: string) => Promise<Review>;
+        /**
+         * Submit a review for a completed order. Returns a narrow
+         * {@link ReviewCreateResult} with the new id, rating, text echo,
+         * and optional bonus grant. To fetch the full review record
+         * (including `createdAt`, `authorName`, `adminReply`, etc.),
+         * call `reviews.getMine()` after the create completes.
+         */
+        create: (orderId: number, rating: number, text?: string) => Promise<ReviewCreateResult>;
     };
     topup: {
         /** Get available topup payment methods */
@@ -340,8 +636,19 @@ export declare class GameCoreClient {
         getStatus: (code: string) => Promise<TopupStatus>;
     };
     giftCards: {
-        /** Purchase a gift card (amount in USD) */
-        purchase: (amountUsd: number) => Promise<GiftCard>;
+        /**
+         * Purchase a gift card. The amount is in RUB (despite the
+         * legacy SDK parameter name — the column was misnamed and has
+         * always held RUB values, see Wave 3 audit tasks/112a). The
+         * method accepts either a plain number for backwards
+         * compatibility or an options object with an explicit message.
+         *
+         * @param amountRub - RUB amount to deduct from the user's
+         *   balance and encode into the gift card.
+         * @param message - Optional personal note shown to the
+         *   redeeming user.
+         */
+        purchase: (amountRub: number, message?: string) => Promise<GiftCard>;
         /** Redeem a gift card code */
         redeem: (code: string) => Promise<{
             amount: number;

package/dist/index.js

@@ -84,7 +84,9 @@ class GameCoreClient {
     getCookieConsent: () => this.request("GET", "/site/cookie-consent"),
     getCatalogSections: () => this.request("GET", "/site/catalog-sections"),
     getBanners: () => this.request("GET", "/site/banners"),
-    getAnnouncementBar: () => this.request("GET", "/site/announcement-bar")
+    getAnnouncementBar: () => this.request("GET", "/site/announcement-bar"),
+    getSitemapData: () => this.request("GET", "/seo/sitemap-data"),
+    requestGame: (data) => this.request("POST", "/site/request-game", data)
   };
   auth = {
     initTelegram: () => this.request("POST", "/auth/telegram/init"),
@@ -105,12 +107,25 @@ class GameCoreClient {
         }
       }, intervalMs);
     }),
-    getVkAuthUrl: (redirectUri) => this.request("GET", `/auth/vk/url?redirect=${encodeURIComponent(redirectUri)}`),
+    verifyMiniApp: (initData, ref) => this.request("POST", "/auth/telegram/miniapp", { initData, ref }, { rawResponse: true }),
+    verifyTelegramWidget: (data, ref) => this.request("POST", "/auth/telegram/widget", { ...data, ref }, { rawResponse: true }),
+    getVkAuthUrl: (redirectUri, ref) => {
+      const params = new URLSearchParams;
+      params.set("redirect", redirectUri);
+      if (ref)
+        params.set("ref", ref);
+      return this.request("GET", `/auth/vk/url?${params.toString()}`, undefined, { rawResponse: true });
+    },
+    vkCallback: (code, state) => this.request("POST", "/auth/vk/callback", { code, state }, { rawResponse: true }),
     verifyVk: (accessToken, ref) => this.request("POST", "/auth/vk/verify", { accessToken, ref }, { rawResponse: true }),
+    register: (email, password, firstName, ref) => this.request("POST", "/auth/register", { email, password, firstName, ref }, { rawResponse: true }),
+    login: (email, password) => this.request("POST", "/auth/login", { email, password }, { rawResponse: true }),
+    changePassword: (currentPassword, newPassword) => this.request("POST", "/auth/change-password", { currentPassword, newPassword }),
     getMe: () => this.request("GET", "/auth/me", undefined, { rawResponse: true }),
     logout: () => this.request("POST", "/auth/logout"),
     getIdentities: () => this.request("GET", "/auth/identities", undefined, { rawResponse: true }),
     linkVk: (accessToken) => this.request("POST", "/auth/link/vk", { accessToken }),
+    linkEmail: (email, password) => this.request("POST", "/auth/link-email", { email, password }),
     unlinkProvider: (provider) => this.request("POST", `/auth/unlink/${provider}`),
     mergePreview: (accessToken) => this.request("POST", "/auth/merge/preview", { accessToken }),
     mergeConfirm: (accessToken) => this.request("POST", "/auth/merge/confirm", { accessToken })
@@ -118,6 +133,10 @@ class GameCoreClient {
   catalog = {
     getGames: (params) => {
       const qs = new URLSearchParams;
+      if (params?.page)
+        qs.set("page", String(params.page));
+      if (params?.limit)
+        qs.set("limit", String(params.limit));
       if (params?.locale)
         qs.set("locale", params.locale);
       if (params?.type)
@@ -130,6 +149,8 @@ class GameCoreClient {
         qs.set("inStockOnly", "true");
       if (params?.sort)
         qs.set("sort", params.sort);
+      if (params?.q)
+        qs.set("q", params.q);
       const q = qs.toString();
       return this.request("GET", `/catalog/games${q ? `?${q}` : ""}`);
     },
@@ -173,6 +194,7 @@ class GameCoreClient {
     get: () => this.request("GET", "/cart"),
     add: (item) => this.request("POST", "/cart", item),
     sync: (items) => this.request("POST", "/cart/sync", { items }),
+    merge: (items) => this.request("POST", "/cart/merge", { items }),
     remove: (id) => this.request("DELETE", `/cart/${id}`),
     clear: () => this.request("DELETE", "/cart")
   };
@@ -189,7 +211,10 @@ class GameCoreClient {
   orders = {
     list: () => this.request("GET", "/orders"),
     get: (code) => this.request("GET", `/orders/${code}`),
-    getByPayment: (paymentCode) => this.request("GET", `/checkout/orders/payment/${paymentCode}`, undefined, { rawResponse: true }),
+    getByPayment: (paymentCode, guestEmail) => {
+      const qs = guestEmail ? `?email=${encodeURIComponent(guestEmail)}` : "";
+      return this.request("GET", `/checkout/orders/payment/${paymentCode}${qs}`, undefined, { rawResponse: true });
+    },
     cancelPreview: (code) => this.request("GET", `/orders/${code}/cancel-preview`),
     cancel: (code) => this.request("POST", `/orders/${code}/cancel`)
   };
@@ -216,7 +241,27 @@ class GameCoreClient {
     updateSettings: (data) => this.request("PUT", "/profile/settings", data),
     subscribeBroadcast: () => this.request("POST", "/profile/broadcast/subscribe"),
     unsubscribeBroadcast: () => this.request("POST", "/profile/broadcast/unsubscribe"),
-    getBroadcastStatus: () => this.request("GET", "/profile/broadcast/status")
+    getBroadcastStatus: () => this.request("GET", "/profile/broadcast/status"),
+    getConversations: () => this.request("GET", "/profile/conversations"),
+    getConversationMessages: (conversationId, params) => {
+      const qs = new URLSearchParams;
+      if (params?.limit)
+        qs.set("limit", String(params.limit));
+      if (params?.offset)
+        qs.set("offset", String(params.offset));
+      const q = qs.toString();
+      return this.request("GET", `/profile/conversations/${conversationId}/messages${q ? `?${q}` : ""}`);
+    },
+    submitCode: (conversationId, requestId, code) => this.request("POST", `/profile/conversations/${conversationId}/submit-code`, { requestId, code }),
+    submitScreenshot: (conversationId, requestId, file) => {
+      const form = new FormData;
+      form.append("requestId", String(requestId));
+      form.append("file", file);
+      return this.request("POST", `/profile/conversations/${conversationId}/submit-screenshot`, form);
+    },
+    getPushPublicKey: () => this.request("GET", "/profile/push/public-key"),
+    subscribePush: (subscription) => this.request("POST", "/profile/push/subscribe", subscription),
+    unsubscribePush: (endpoint) => this.request("POST", "/profile/push/unsubscribe", { endpoint })
   };
   favorites = {
     list: () => this.request("GET", "/favorites"),
@@ -236,7 +281,22 @@ class GameCoreClient {
     updateLink: (id, data) => this.request("PUT", `/referral/links/${id}`, data),
     deleteLink: (id) => this.request("DELETE", `/referral/links/${id}`),
     getLinkStats: (id) => this.request("GET", `/referral/links/${id}/stats`),
-    getCommissions: () => this.request("GET", "/referral/commissions")
+    getCommissions: () => this.request("GET", "/referral/commissions"),
+    getPopularProducts: (limit) => {
+      const qs = limit ? `?limit=${limit}` : "";
+      return this.request("GET", `/referral/popular-products${qs}`);
+    },
+    getPerformance: (params) => {
+      const qs = new URLSearchParams;
+      if (params?.from) {
+        qs.set("from", params.from instanceof Date ? params.from.toISOString() : params.from);
+      }
+      if (params?.to) {
+        qs.set("to", params.to instanceof Date ? params.to.toISOString() : params.to);
+      }
+      const q = qs.toString();
+      return this.request("GET", `/referral/performance${q ? `?${q}` : ""}`);
+    }
   };
   reviews = {
     listPublic: (params) => {
@@ -259,7 +319,11 @@ class GameCoreClient {
     getRandom: (limit = 5) => this.request("GET", `/reviews/public/random?limit=${limit}`),
     getMine: () => this.request("GET", "/reviews/mine"),
     getPending: () => this.request("GET", "/reviews/pending"),
-    create: (orderId, rating, text) => this.request("POST", "/reviews", { orderId, rating, text })
+    create: (orderId, rating, text) => this.request("POST", "/reviews", {
+      orderId,
+      rating,
+      text
+    })
   };
   topup = {
     getPaymentMethods: () => this.request("GET", "/topup/payment-methods"),
@@ -267,7 +331,10 @@ class GameCoreClient {
     getStatus: (code) => this.request("GET", `/topup/${code}`)
   };
   giftCards = {
-    purchase: (amountUsd) => this.request("POST", "/gift-cards/purchase", { amountUsd }),
+    purchase: (amountRub, message) => this.request("POST", "/gift-cards/purchase", {
+      amountRub,
+      message
+    }),
     redeem: (code) => this.request("POST", "/gift-cards/redeem", { code }),
     check: (code) => this.request("GET", `/gift-cards/check/${code}`),
     getMine: () => this.request("GET", "/profile/gift-cards")

package/dist/types.d.ts

@@ -8,6 +8,47 @@ export interface AuthStatusResponse {
     status: "pending" | "verified" | "authenticated" | "expired" | "used";
     user?: User;
 }
+/**
+ * Payload returned by Telegram Login Widget when the user completes
+ * authentication. Same shape as Telegram's official docs — you can hand
+ * this object directly to auth.verifyTelegramWidget().
+ * https://core.telegram.org/widgets/login
+ */
+export interface TelegramWidgetUser {
+    id: number;
+    first_name: string;
+    last_name?: string;
+    username?: string;
+    photo_url?: string;
+    auth_date: number;
+    hash: string;
+}
+/**
+ * Narrow user DTO returned by /auth/telegram/miniapp and /auth/telegram/widget.
+ * This is intentionally a subset of the full {@link User} type — the auth
+ * endpoints only echo identity + role, not balance/level/email fields, so
+ * typing it as `User` would lie to SDK consumers. Call auth.getMe() after
+ * login if the storefront needs the full profile.
+ */
+export interface TelegramAuthUser {
+    id: number;
+    telegramId: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    username: string | null;
+    photoUrl: string | null;
+    role: string;
+}
+/**
+ * Response from the Mini App / Widget POST verification endpoints.
+ * Body includes success, status and (on success) the authenticated user.
+ */
+export interface TelegramAuthResponse {
+    success: boolean;
+    status?: "authenticated";
+    user?: TelegramAuthUser;
+    error?: string;
+}
 export interface User {
     id: number;
     firstName: string;
@@ -84,13 +125,36 @@ export interface GameDetail {
     name: string;
     icon: string | null;
     localIcon?: string | null;
+    /** Landscape hero image (1200x630). Null if no gallery is available. */
     coverImage?: string | null;
+    /** Gallery of product screenshots (resized to 800x600). */
     images?: string[];
     description: string | null;
+    /** Editorial badges like "hit", "new", "popular", "sale". */
+    tags?: string[];
+    /** Availability lifecycle. Shares the union from {@link Game}. */
+    availabilityStatus?: "available" | "coming_soon" | "maintenance" | "discontinued";
+    /** Human-readable message for non-available games. */
+    availabilityMessage?: string | null;
     inStock?: boolean;
     productCount?: number;
     categories: Category[];
     seo?: SeoContent | null;
+    /**
+     * Present only when the request used an alias slug and the backend
+     * resolved it to a different canonical slug. When set, the storefront
+     * should issue a 301 redirect to `/games/${canonicalSlug}` instead
+     * of rendering the page. Absent when the requested slug is already
+     * canonical.
+     */
+    canonicalSlug?: string;
+    /**
+     * ISO-8601 timestamp of the last meaningful edit on this canonical
+     * game — bumped on catalog changes (products, pricing, metadata).
+     * Storefronts should use this as `lastModified` in sitemap entries
+     * so Google doesn't refetch pages that haven't changed.
+     */
+    updatedAt?: string;
 }
 /**
  * Per-site SEO content for a game page.
@@ -188,6 +252,29 @@ export interface CartItem {
     productName: string;
     price: number;
     deliveryData: Record<string, string>;
+    /**
+     * Quantity for multi-amount products (e.g. N × 500 Robux).
+     * Optional when writing (server defaults to `1`); always
+     * present on server responses.
+     */
+    quantity?: number;
+    /**
+     * ISO-8601 timestamp of when the row was inserted. Absent when
+     * the item was freshly constructed client-side and hasn't been
+     * sent to the server yet.
+     */
+    addedAt?: string;
+    /**
+     * Canonical game icon (localIcon → icon fallback). May be `null`
+     * if the underlying game has no artwork. Never present on
+     * client-authored items — only populated on server responses.
+     */
+    gameIcon?: string | null;
+    /**
+     * Supplier product icon (localIcon → icon fallback). Same
+     * semantics as `gameIcon`.
+     */
+    productIcon?: string | null;
 }
 export interface CheckoutRequest {
     email?: string;
@@ -215,6 +302,46 @@ export interface CheckoutResponse {
     }>;
 }
 export type OrderStatus = "pending" | "paid" | "processing" | "completed" | "cancelled" | "refunded" | "failed";
+/**
+ * Payment record returned by `checkout.getByPayment()`.
+ *
+ * A payment groups one or more orders created in the same checkout
+ * call. The `code` is the external identifier exposed to the
+ * payment gateway and returned via the success URL query string.
+ *
+ * `paymentMethod` and `gatewayType` are `null` when the payment is
+ * fully settled from the user's balance (no external gateway is
+ * involved). `completedAt` is set when the payment transitions to
+ * `completed` via webhook confirmation or balance settlement; it
+ * remains `null` for `pending`, `failed`, and `cancelled` payments
+ * (the failure/cancellation timestamp is tracked separately by
+ * the stale-payment scanner and not surfaced on this shape).
+ */
+export interface PaymentInfo {
+    code: string;
+    totalAmount: number;
+    status: "pending" | "completed" | "failed" | "cancelled";
+    paymentMethod: string | null;
+    gatewayType: string | null;
+    createdAt: string;
+    completedAt: string | null;
+}
+/**
+ * Normalised delivery hint attached to an order. Used by the
+ * storefront "My Orders" page to decide which CTA to show
+ * (robux-via-pass → "Check Roblox transactions"; gift card →
+ * "Copy code"; login delivery → "Waiting for credentials"; etc).
+ *
+ * `helpTextKey` is an i18n key — the storefront owns the
+ * translation layer, so copy changes do not require a backend
+ * deploy. Unknown `kind` values should render a generic
+ * "processing" message as a fallback.
+ */
+export interface OrderDeliveryMeta {
+    kind: "cdkey" | "login" | "pass_based" | "service" | "manual" | (string & {});
+    helpTextKey: string;
+    checkTransactionsUrl?: string;
+}
 export interface Order {
     id: number;
     code: string;
@@ -231,6 +358,13 @@ export interface Order {
     };
     createdAt: string;
     completedAt?: string;
+    /**
+     * Delivery hint for the storefront UI — present on responses
+     * from `/profile/orders` and `/orders/:code` starting with
+     * SDK 0.13. Absent on legacy responses and on endpoints that
+     * do not currently surface it.
+     */
+    deliveryMeta?: OrderDeliveryMeta;
 }
 export interface OrderItem {
     id: number;
@@ -257,6 +391,20 @@ export interface UserBalance {
         expiresAt: string;
     }>;
 }
+/**
+ * One rung of the loyalty level ladder — used by the "how levels
+ * work" explainer on the profile page. Shape matches what the
+ * server computes from `loyalty_levels` (per-site custom) or the
+ * hardcoded default ladder.
+ */
+export interface LevelSystemLevel {
+    level: number;
+    name: string;
+    discountPercent: number;
+    minSpendingUsd: number;
+    minReviews: number;
+    minReferrals: number;
+}
 export interface LevelStatus {
     currentLevel: number;
     currentDiscount: number;
@@ -280,6 +428,19 @@ export interface LevelStatus {
             met: boolean;
         };
     };
+    /**
+     * Highest level in the ladder. Storefronts should use this
+     * instead of hardcoding "15" so per-site custom ladders render
+     * correctly. Always present on responses from SDK 0.13+.
+     */
+    maxLevel?: number;
+    /** Highest discount percent in the ladder. */
+    maxDiscount?: number;
+    /**
+     * Full ordered ladder. Use this to render the explainer table
+     * or a progress timeline. Omitted on very old responses.
+     */
+    allLevels?: LevelSystemLevel[];
 }
 export interface Transaction {
     id: number;
@@ -311,27 +472,212 @@ export interface Favorite {
     categorySlug?: string;
     createdAt: string;
 }
+/**
+ * Review record. Fields are endpoint-specific — this interface is a
+ * union of everything any review endpoint may return, and real-world
+ * shape depends on which route you call:
+ *
+ *   - `reviews.listPublic()`      → `id`, `rating`, `text`, `authorName`,
+ *                                   `gameName`, `adminReply`, `adminReplyAt`,
+ *                                   `createdAt`
+ *   - `reviews.mine()`            → `id`, `rating`, `text`, `adminReply`,
+ *                                   `adminReplyAt`, `createdAt`, `order`
+ *   - `reviews.create()`          → the freshly-created review + `bonus`
+ *
+ * Fields that are not relevant to a given endpoint are `undefined`. Do
+ * not assume any single field is always present.
+ */
 export interface Review {
     id: number;
-    userId: number;
-    userName?: string;
-    orderId: number;
-    orderCode?: string;
     rating: number;
     text?: string;
+    createdAt: string;
+    /** Public display name (author). Returned by `listPublic()`. */
+    authorName?: string;
+    /** Legacy alias for `authorName`. Prefer `authorName` on new code. */
+    userName?: string;
+    /** Owner of the review. Returned only to authenticated admins. */
+    userId?: number;
+    /** Link back to the order the review was left for. */
+    orderId?: number;
+    orderCode?: string;
     gameName?: string;
+    /**
+     * Public reply from site support. Rendered under the review body
+     * as "Ответ поддержки". `null` if support has not replied or the
+     * reply was removed. Included in both the public listing and the
+     * authenticated profile reviews list.
+     */
+    adminReply?: string | null;
+    /**
+     * ISO-8601 timestamp of when the support reply was created or last
+     * updated. `null` when no reply is present.
+     */
+    adminReplyAt?: string | null;
+    /**
+     * Nested order summary, returned only by `reviews.mine()` so the
+     * profile "My reviews" page can show game + order code without a
+     * second fetch. `null` when the underlying order was deleted.
+     */
+    order?: {
+        code: string;
+        gameName: string;
+        createdAt: string;
+    } | null;
+    /** Bonus granted for leaving the review, if any. */
     bonus?: {
         amount: number;
         percent: number;
         expiresAt: string;
     };
-    createdAt: string;
 }
 export interface ReviewStats {
     averageRating: number;
     totalCount: number;
     distribution?: Record<string, number>;
 }
+/**
+ * Response shape returned by `checkout.completeWithBalance()`.
+ *
+ * The post-deduction balance (`newBalance`) is always present on a
+ * successful response — the storefront success page can render
+ * "new balance: X" without a second `profile.getBalance()` fetch
+ * (which is race-prone right after completion).
+ *
+ * The deduction breakdown (`balanceUsed`, `balanceDeduction`) is
+ * present **only on the first successful call** — it reflects what
+ * was actually moved by this request. If the client retries the
+ * endpoint for an already-completed payment (idempotent replay),
+ * those fields are `undefined` because the original breakdown is
+ * not re-derivable from persisted state. The `newBalance` is still
+ * included in that case so the receipt UI has something to render.
+ *
+ * When present, `balanceUsed` equals
+ * `balanceDeduction.fromBonus + balanceDeduction.fromPermanent`.
+ */
+export interface CompleteWithBalanceResult {
+    paymentCode: string;
+    status: "completed";
+    balanceUsed?: number;
+    balanceDeduction?: {
+        fromBonus: number;
+        fromPermanent: number;
+    };
+    newBalance: {
+        total: number;
+        permanent: number;
+        bonus: number;
+    };
+}
+/**
+ * Short summary of a conversation as returned by
+ * `profile.getConversations()` — one row per user-owned order
+ * thread. Use the `id` to fetch full messages via
+ * `profile.getConversationMessages(id)`.
+ */
+export interface Conversation {
+    id: number;
+    orderId: number;
+    orderCode: string | null;
+    gameName: string | null;
+    orderStatus: string | null;
+    /** Number of unread system / admin messages. User messages don't count. */
+    unreadCount: number;
+    /**
+     * Preview of the most recent message. `body` is truncated to ~100
+     * chars. `null` if the conversation has no messages yet.
+     */
+    lastMessage: {
+        body: string;
+        authorType: "user" | "admin" | "system";
+        messageType: "text" | "status_change" | "code_requested" | "screenshot_requested" | (string & {});
+        createdAt: string;
+    } | null;
+    /** Last time either party posted a message, ISO-8601. */
+    lastMessageAt: string;
+}
+/**
+ * Single message inside a conversation. `metadata` is parsed JSON —
+ * system messages may carry status-change payloads, request ids, etc.
+ * Free chat (user-authored `text` messages) is currently disabled —
+ * expect only `admin`, `system`, and request-response messages.
+ */
+export interface ConversationMessage {
+    id: number;
+    authorType: "user" | "admin" | "system";
+    authorId: number | null;
+    messageType: "text" | "status_change" | "code_requested" | "screenshot_requested" | (string & {});
+    body: string;
+    metadata: Record<string, unknown> | null;
+    /** Set when the current viewer marked the message as read. */
+    readAt: string | null;
+    createdAt: string;
+}
+/**
+ * Open supplier-initiated request inside a conversation. The UI
+ * decides which input to show the user based on `requestType`.
+ */
+export interface ConversationRequest {
+    id: number;
+    conversationId: number;
+    orderId: number;
+    orderItemId: number;
+    requestType: "code" | "screenshot";
+    status: "open" | "fulfilled" | "cancelled" | "expired";
+    requestedAt: string;
+    fulfilledAt: string | null;
+}
+/**
+ * Full detail returned by `profile.getConversationMessages(id)`.
+ * The conversation header is included so the UI does not need a
+ * separate fetch to render the page title / order summary.
+ */
+export interface ConversationDetail {
+    conversation: {
+        id: number;
+        orderId: number;
+        orderCode: string | null;
+        gameName: string | null;
+        orderStatus: string | null;
+    };
+    messages: ConversationMessage[];
+    /** Open supplier requests the user can respond to right now. */
+    openRequests: ConversationRequest[];
+}
+/**
+ * Web Push subscription payload returned by the browser's
+ * `PushSubscription.toJSON()`. Pass this to
+ * `profile.subscribePush()` to start receiving push notifications
+ * for order status updates and conversation replies.
+ */
+export interface WebPushSubscriptionInput {
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+}
+/**
+ * Narrow response returned by `reviews.create()`.
+ *
+ * The create endpoint deliberately returns less than a full `Review`
+ * — only the fields the storefront needs to acknowledge the
+ * submission: the new review id, the numeric rating, the text echo,
+ * and the optional bonus grant metadata.
+ *
+ * Callers who need the full review (with `createdAt`, `authorName`,
+ * etc.) should re-fetch via `reviews.getMine()` after the create.
+ */
+export interface ReviewCreateResult {
+    id: number;
+    rating: number;
+    text: string | null;
+    bonus: {
+        amount: number;
+        percent: number;
+        expiresAt: string;
+    } | null;
+}
 export interface CouponResult {
     type: string;
     value: number;
@@ -366,13 +712,50 @@ export interface ReferralCommission {
     commissionPercent: number;
     createdAt: string;
 }
+/**
+ * Date-range aggregated performance metrics for a referrer.
+ *
+ * Commission, transaction and member counts honour the `from` /
+ * `to` range passed to `referrals.getPerformance()`. `totalClicks`
+ * is **lifetime across all of the referrer's links** and is NOT
+ * date-filtered — click events are not individually timestamped in
+ * the current schema. Storefronts should label the clicks metric
+ * accordingly ("all-time clicks" vs. "period earnings").
+ */
+export interface ReferralPerformance {
+    totalCommission: number;
+    totalClicks: number;
+    totalTransactions: number;
+    newMembers: number;
+}
 export interface TopupMethod {
     type: string;
     label: string;
     description?: string;
     feePercent?: number;
     gatewayType?: string;
-    invoiceCurrency?: string;
+    invoiceCurrency?: string | null;
+    /**
+     * Minimum topup amount in RUB. `null` means the storefront
+     * should use its global minimum (typically 50 RUB). The topup
+     * route enforces this server-side too.
+     */
+    minAmount?: number | null;
+    /**
+     * Maximum topup amount in RUB. `null` means "use global cap".
+     */
+    maxAmount?: number | null;
+    /**
+     * Grouping bucket for collapsible UIs. Known values: `"direct"`,
+     * `"p2p"`, `"intl"`. Unknown values should render as a
+     * generic "Other" group.
+     */
+    group?: "direct" | "p2p" | "intl" | (string & {}) | null;
+    /**
+     * Optional warning text rendered underneath the method
+     * selector (e.g. "Временно нестабильно"). `null` means no note.
+     */
+    stabilityNote?: string | null;
 }
 export interface TopupResponse {
     code: string;
@@ -385,13 +768,48 @@ export interface TopupStatus {
     amount: number;
     createdAt?: string;
 }
+/**
+ * Gift card voucher. Stored in RUB; the field was historically
+ * called `denomination` in the SDK and `amount_usd` in the DB
+ * column, but both were misnomers — the value has always been RUB
+ * (see Wave 3 #34 audit `tasks/112a-giftcard-currency-audit.md`).
+ * Use `amountRub` on new code; `amountUsd` and `denomination` are
+ * deprecated aliases that echo the same value.
+ */
 export interface GiftCard {
     id: number;
     code: string;
-    denomination: number;
-    status: string;
+    /** Canonical RUB value. Use this on new code. */
+    amountRub: number;
+    /**
+     * @deprecated Legacy alias echoing `amountRub`. The name was
+     * wrong historically — the value was always RUB despite the
+     * `Usd` suffix. Remove once storefronts upgrade past SDK 0.13.x.
+     */
+    amountUsd?: number;
+    /**
+     * @deprecated Legacy alias echoing `amountRub`. Kept for
+     * storefronts that were reading this field from typed code; at
+     * runtime the backend never emitted `denomination`, so most
+     * consumers were already getting `undefined`.
+     */
+    denomination?: number;
+    /** Currency of `amountRub`. Always `"RUB"` for now. */
+    currency: "RUB";
+    /**
+     * Remaining balance if the card supports partial redemption.
+     * For active and expired cards this equals `amountRub`. For
+     * redeemed or cancelled cards it is `0`. Partial redemption is
+     * not implemented yet — the field is reserved so storefronts
+     * can start rendering it now without a future breaking change.
+     */
+    remainingBalance: number;
+    status: "active" | "redeemed" | "expired" | "cancelled" | (string & {});
+    message?: string | null;
+    /** ISO-8601 expiry timestamp; `null` if the card never expires. */
+    expiresAt?: string | null;
     createdAt: string;
-    redeemedAt?: string;
+    redeemedAt?: string | null;
 }
 export interface Announcement {
     id: number;
@@ -496,6 +914,17 @@ export interface PaginatedResponse<T> {
         hasMore: boolean;
     };
 }
+/** Catalog games use page-based pagination (page 1, 2, ...) */
+export interface PagedGamesResponse {
+    data: Game[];
+    pagination: {
+        page: number;
+        limit: number;
+        total: number;
+        totalPages: number;
+        hasMore: boolean;
+    };
+}
 export declare class GameCoreError extends Error {
     status: number;
     code?: string;

package/package.json

@@ -1,10 +1,9 @@
 {
 	"name": "@gamecore-api/sdk",
-	"version": "0.9.0",
+	"version": "0.13.0",
 	"description": "TypeScript SDK for GameCore API — browser-safe, zero dependencies",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
-	"module": "dist/index.mjs",
 	"exports": {
 		".": {
 			"import": "./dist/index.js",