@gamecore-api/sdk 0.12.0 → 0.14.0

package/README.md

@@ -1,17 +1,29 @@
-# @gamecore/sdk
+# @gamecore-api/sdk
 
 TypeScript SDK for GameCore API — zero external dependencies, browser-safe.
 
 ## Install
 
 ```bash
-npm install @gamecore/sdk
+npm install @gamecore-api/sdk
 ```
 
+## What's new in 0.14.0
+
+- **BREAKING** `giftCards.purchase()` signature changed: first arg is now `amountRub` (was `amountUsd`). GiftCard payload fields renamed — `amount_usd` → `amount_rub`, added `currency`, `remainingBalance`, `expiresAt`. `denomination` is now optional (legacy)
+- `cart.merge(items)` — guest → authed cart handoff; new response fields `quantity`, `addedAt`, `gameIcon`
+- `auth.linkEmail(email, password)` — add email identity to an existing Telegram/VK account
+- `profile.getConversations / getConversationMessages / submitCode / submitScreenshot` — in-profile support chat
+- `profile.getPushPublicKey / subscribePush / unsubscribePush` — web push subscriptions
+- `referrals.getPopularProducts(limit)` + `referrals.getPerformance({ from, to })` — affiliate analytics
+- `site.requestGame({ gameName, contact })` — public "request a game" lead capture
+- `site.getSitemapData()` — data source for `sitemap.xml`
+- `checkout.completeWithBalance` now returns `{ newBalance }`
+
 ## Quick Start
 
 ```typescript
-import { GameCoreClient } from "@gamecore/sdk";
+import { GameCoreClient } from "@gamecore-api/sdk";
 
 const gc = new GameCoreClient({
   apiKey: "gc_live_YOUR_KEY",
@@ -50,6 +62,23 @@ console.log("Logged in:", user.firstName);
 const { user } = await gc.auth.verifyVk(vkAccessToken);
 ```
 
+### Email + Password
+
+```typescript
+await gc.auth.register(email, password, firstName, ref);
+await gc.auth.login(email, password);
+await gc.auth.changePassword(currentPassword, newPassword);
+```
+
+### Link additional identity
+
+```typescript
+// Add email to an existing Telegram/VK account
+await gc.auth.linkEmail(email, password);
+// Or link a VK access token
+await gc.auth.linkVk(vkAccessToken);
+```
+
 ### Session
 
 ```typescript
@@ -88,10 +117,14 @@ const { suggestions } = await gc.catalog.searchSuggestions("rob");
 ```typescript
 // Cart
 const items = await gc.cart.get();
-await gc.cart.add({ productId: 10, gameId: "roblox", gameName: "Roblox", productName: "800 Robux", price: 799, deliveryData: { username: "player123" } });
+// items: [{ id, productId, quantity, addedAt, gameIcon, ... }]
+await gc.cart.add({ productId: 10, gameId: "roblox", gameName: "Roblox", productName: "800 Robux", price: 799, deliveryData: { username: "player123" }, quantity: 2 });
 await gc.cart.remove(itemId);
 await gc.cart.clear();
 
+// Merge guest cart into authed session (on login)
+await gc.cart.merge(guestItems);
+
 // Checkout (auto-generates idempotency key)
 const checkout = await gc.checkout.create({
   items: [{ productId: 10, deliveryData: { username: "player123" } }],
@@ -144,6 +177,17 @@ const notifications = await gc.profile.getNotifications();
 const { count } = await gc.profile.getUnreadCount();
 await gc.profile.markRead(notificationId);
 await gc.profile.markAllRead();
+
+// Support conversations (in-profile chat)
+const conversations = await gc.profile.getConversations();
+const messages = await gc.profile.getConversationMessages(conversationId);
+await gc.profile.submitCode(conversationId, requestId, "ABC-123");
+await gc.profile.submitScreenshot(conversationId, requestId, file);
+
+// Web push subscriptions
+const { publicKey } = await gc.profile.getPushPublicKey();
+await gc.profile.subscribePush({ endpoint, keys: { p256dh, auth } });
+await gc.profile.unsubscribePush(endpoint);
 ```
 
 ## Favorites
@@ -185,8 +229,10 @@ await gc.coupons.remove();
 const active = await gc.coupons.getActive();
 
 // Gift cards
-const card = await gc.giftCards.purchase(5); // amountUsd
+const card = await gc.giftCards.purchase(500, "Happy birthday!"); // amountRub + optional message
 await gc.giftCards.redeem("GC-XXXX-XXXX-XXXX");
+const mine = await gc.giftCards.getMine();
+// { code, amount_rub, currency, remainingBalance, expiresAt, ... }
 ```
 
 ## Referrals
@@ -198,6 +244,15 @@ const link = await gc.referrals.createLink({ label: "YouTube", slug: "my-channel
 await gc.referrals.updateLink(link.id, { label: "Updated" });
 const linkStats = await gc.referrals.getLinkStats(link.id);
 const commissions = await gc.referrals.getCommissions();
+
+// Popular products referred by this user
+const popular = await gc.referrals.getPopularProducts(10);
+
+// Performance over a date range
+const perf = await gc.referrals.getPerformance({
+  from: "2026-04-01",
+  to: "2026-04-30",
+});
 ```
 
 ## Balance Top-up
@@ -236,7 +291,7 @@ const schema = await gc.seo.getSchema("product", 42);
 
 ```typescript
 // Import from server entrypoint (uses node:crypto)
-import { verifyWebhookSignature, parseWebhookPayload } from "@gamecore/sdk/server";
+import { verifyWebhookSignature, parseWebhookPayload } from "@gamecore-api/sdk/server";
 
 const isValid = verifyWebhookSignature(
   requestBody,
@@ -253,7 +308,7 @@ if (isValid) {
 ## Utilities
 
 ```typescript
-import { convertPrice, formatPrice, generateIdempotencyKey } from "@gamecore/sdk";
+import { convertPrice, formatPrice, generateIdempotencyKey } from "@gamecore-api/sdk";
 
 const rub = convertPrice(1.99, 92.5);       // 184.08
 const formatted = formatPrice(rub, "RUB");   // "184 ₽"
@@ -266,7 +321,7 @@ const key = generateIdempotencyKey();         // UUID v4
 
 ```typescript
 // app/catalog/page.tsx
-import { GameCoreClient } from "@gamecore/sdk";
+import { GameCoreClient } from "@gamecore-api/sdk";
 
 const gc = new GameCoreClient({
   apiKey: process.env.GAMECORE_API_KEY!,
@@ -297,7 +352,7 @@ export function CartWidget() {
 
 ```typescript
 // app/api/webhooks/gamecore/route.ts
-import { verifyWebhookSignature, parseWebhookPayload } from "@gamecore/sdk/server";
+import { verifyWebhookSignature, parseWebhookPayload } from "@gamecore-api/sdk/server";
 
 export async function POST(req: Request) {
   const body = await req.text();
@@ -317,16 +372,16 @@ export async function POST(req: Request) {
 
 | Namespace | Methods |
 |-----------|---------|
-| `gc.site` | getConfig, getRates, getLegal |
-| `gc.auth` | initTelegram, pollTelegramStatus, verifyVk, getMe, logout, getIdentities, linkVk, unlinkProvider |
-| `gc.catalog` | getGames, getHomepageGames, getGame, getProducts, getProductsGrouped, search, searchSuggestions, getProduct |
-| `gc.cart` | get, add, sync, remove, clear |
+| `gc.site` | getConfig, getRates, getLegal, getStats, getSocialProof, getThemeConfig, getTranslations, getUIConfig, getCookieConsent, getCatalogSections, getBanners, getAnnouncementBar, getSitemapData, requestGame |
+| `gc.auth` | initTelegram, pollTelegramStatus, verifyMiniApp, verifyTelegramWidget, getVkAuthUrl, vkCallback, verifyVk, register, login, changePassword, getMe, logout, getIdentities, linkVk, linkEmail, unlinkProvider, mergePreview, mergeConfirm |
+| `gc.catalog` | getGames, getHomepageGames, getGame, getRecommendations, getCategories, getProducts, getProductsGrouped, search, searchSuggestions, getProduct |
+| `gc.cart` | get, add, merge, sync, remove, clear |
 | `gc.checkout` | create, completeWithBalance, getPaymentMethods |
 | `gc.orders` | list, get, getByPayment, cancel |
-| `gc.profile` | getBalance, getLevelStatus, getTransactions, getOrders, getNotifications, getUnreadCount, markRead, markAllRead |
+| `gc.profile` | getBalance, getLevelStatus, getTransactions, getOrders, getNotifications, getUnreadCount, markRead, markAllRead, getConversations, getConversationMessages, submitCode, submitScreenshot, getPushPublicKey, subscribePush, unsubscribePush |
 | `gc.favorites` | list, add, remove |
 | `gc.coupons` | apply, remove, validate, getActive |
-| `gc.referrals` | getStats, getLinks, createLink, updateLink, deleteLink, getLinkStats, getCommissions |
+| `gc.referrals` | getStats, getLinks, createLink, updateLink, deleteLink, getLinkStats, getCommissions, getPopularProducts, getPerformance |
 | `gc.reviews` | listPublic, getStats, getRandom, getMine, getPending, create |
 | `gc.topup` | getPaymentMethods, create, getStatus |
 | `gc.giftCards` | purchase, redeem, check, getMine |
@@ -339,5 +394,5 @@ export async function POST(req: Request) {
 
 | Import | Environment | Includes |
 |--------|-------------|----------|
-| `@gamecore/sdk` | Browser + Node | Client, types, utilities |
-| `@gamecore/sdk/server` | Node only | Webhook verification (uses node:crypto) |
+| `@gamecore-api/sdk` | Browser + Node | Client, types, utilities |
+| `@gamecore-api/sdk/server` | Node only | Webhook verification (uses node:crypto) |

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { TelegramInitResponse, TelegramWidgetUser, TelegramAuthResponse, 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, PagedGamesResponse } 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,18 +47,59 @@ 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 */
@@ -155,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) */
@@ -196,7 +253,22 @@ export declare class GameCoreClient {
         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[]>;
@@ -229,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) */
@@ -254,12 +331,35 @@ 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 */
@@ -275,10 +375,20 @@ export declare class GameCoreClient {
          * 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[]>;
     };
@@ -298,7 +408,7 @@ export declare class GameCoreClient {
          * the endpoint does not leak existence of valid codes).
          */
         getByPayment: (paymentCode: string, guestEmail?: string) => Promise<{
-            payment: unknown;
+            payment: PaymentInfo;
             orders: Order[];
         }>;
         /** Preview cancel — check if cancellable and refund amount */
@@ -360,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 */
@@ -408,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) */
@@ -425,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 */
@@ -437,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"),
@@ -123,6 +125,7 @@ class GameCoreClient {
     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 })
@@ -191,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")
   };
@@ -237,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"),
@@ -257,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) => {
@@ -280,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"),
@@ -288,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

@@ -140,6 +140,21 @@ export interface GameDetail {
     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.
@@ -237,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;
@@ -264,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;
@@ -280,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;
@@ -306,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;
@@ -329,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;
@@ -360,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;
@@ -415,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;
@@ -434,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;

package/package.json

@@ -1,10 +1,9 @@
 {
 	"name": "@gamecore-api/sdk",
-	"version": "0.12.0",
+	"version": "0.14.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",