@gamecore-api/sdk 0.15.0 → 0.17.0

package/README.md

@@ -42,20 +42,62 @@ const results = await gc.catalog.search("roblox");
 
 ## Authentication
 
-### Telegram Auth Flow
+### Telegram Auth — two paths, pick both
+
+Two flavours, designed to coexist as two buttons in the UI:
+
+**1. Official Login Widget** (fastest, needs official Telegram Web session)
 
 ```typescript
-// 1. Start auth → get bot link
-const { token, botLink } = await gc.auth.initTelegram();
+// Mount the blue "Log in with Telegram" button into your own <div>.
+// Bot username is pulled from /site/config; no hardcoding.
+// BotFather /setdomain must point at your storefront's origin, or
+// telegram.org refuses to render the widget.
+const cleanup = await gc.auth.renderTelegramWidget({
+  container: document.querySelector("#tg-login")!,
+  size: "large",
+  onAuth: (user) => {
+    console.log("Logged in:", user.firstName);
+    window.location.href = "/profile";
+  },
+  onError: (err) => console.error(err),
+});
 
-// 2. Open Telegram bot (user clicks "Start")
-window.open(botLink, "_blank");
+// Later (React unmount, SPA route change):
+cleanup();
+```
 
-// 3. Poll until user authenticates
-const user = await gc.auth.pollTelegramStatus(token);
+**2. Bot-link flow** (works in every Telegram client including 3rd-party)
+
+```typescript
+const user = await gc.auth.loginViaTelegramBot({
+  onBotLinkReady: (botLink) => {
+    // Open in new tab — every TG client handles tg:// deep links.
+    // For desktop-only users you could also render botLink as a QR.
+    window.open(botLink, "_blank");
+  },
+  pollMs: 2000,
+  timeoutMs: 120_000,
+});
 console.log("Logged in:", user.firstName);
 ```
 
+**Low-level pieces (for custom flows)**
+
+```typescript
+// Manual init+poll — equivalent to loginViaTelegramBot above
+const { token, botLink } = await gc.auth.initTelegram();
+window.open(botLink, "_blank");
+const user = await gc.auth.pollTelegramStatus(token);
+
+// Manual widget verification — when you render Telegram's <script> yourself
+// and wire data-onauth to your own JS callback
+const auth = await gc.auth.verifyTelegramWidget(telegramWidgetUser);
+
+// Mini App (inside the Telegram bot's built-in WebApp)
+const auth = await gc.auth.verifyMiniApp(window.Telegram.WebApp.initData);
+```
+
 ### VK Auth
 
 ```typescript

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, 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";
+import type { Announcement, AnnouncementBar, CartItem, CatalogSection, Category, CategoryInfo, CheckoutRequest, CheckoutResponse, CompleteWithBalanceResult, Conversation, ConversationDetail, CouponResult, ExchangeRates, Favorite, Game, GameDetail, GiftCard, LegalDocument, LevelStatus, Notification, Order, PagedGamesResponse, PlatformInfo, PaginatedResponse, PaymentInfo, PaymentMethod, Product, ProductFilters, ReferralCommission, ReferralLink, ReferralPerformance, ReferralStats, Review, ReviewCreateResult, ReviewStats, SearchResult, SiteConfig, SiteStats, SiteUIConfig, TelegramAuthResponse, TelegramBotLoginOptions, TelegramInitResponse, TelegramWidgetRenderOptions, TelegramWidgetUser, TopupMethod, TopupResponse, TopupStatus, Transaction, User, UserBalance, WebPushSubscriptionInput } from "./types";
 export interface GameCoreOptions {
     /** Site API key (gc_live_xxx or gc_test_xxx) */
     apiKey: string;
@@ -124,6 +124,43 @@ export declare class GameCoreClient {
          * directly to this method.
          */
         verifyTelegramWidget: (data: TelegramWidgetUser, ref?: string) => Promise<TelegramAuthResponse>;
+        /**
+         * High-level helper: mount the official Telegram Login Widget into
+         * your own DOM element and hand the resulting User to `onAuth`
+         * after server-side HMAC verification. Browser-only.
+         *
+         * Compared to dropping the raw `<script>` on the page:
+         *   - Bot username is pulled from `gc.site.getConfig().authConfig.
+         *     telegram.botUsername` (no hardcoding).
+         *   - The widget's `data-onauth` bridge is plumbed to
+         *     {@link verifyTelegramWidget} so the caller only sees a
+         *     verified User.
+         *   - Errors (hash mismatch, missing bot, expired payload) surface
+         *     through `onError` instead of becoming silent no-ops.
+         *
+         * BotFather prerequisite: `/setdomain` must be set for the bot to
+         * the storefront's origin; the widget refuses to render otherwise.
+         *
+         * Returns a cleanup function that removes the widget from the
+         * container.
+         */
+        renderTelegramWidget: (opts: TelegramWidgetRenderOptions) => Promise<() => void>;
+        /**
+         * High-level helper: run the bot-link auth flow (initTelegram →
+         * poll) and resolve with the authenticated User. Works in every
+         * Telegram client (including third-party like Nicegram, Plus
+         * Messenger) because it doesn't depend on the Login Widget — the
+         * user just opens the deep link and presses Start in the bot.
+         *
+         * The caller's `onBotLinkReady` callback receives the generated
+         * `https://t.me/<bot>?start=<token>` link exactly once; use it to
+         * `window.open(url, "_blank")`, render a QR, or redirect the
+         * user. Polling for the auth handshake starts immediately after.
+         *
+         * Rejects with `GameCoreError("Timeout")` if the user doesn't
+         * press Start within `timeoutMs`.
+         */
+        loginViaTelegramBot: (opts: TelegramBotLoginOptions) => Promise<User>;
         /**
          * Get VK OAuth authorize URL (authorization code flow).
          *
@@ -248,7 +285,31 @@ export declare class GameCoreClient {
             inStockOnly?: boolean;
             sort?: "popular" | "name" | "new" | "soldCount";
             q?: string;
+            /**
+             * Filter by canonical platform slug — "steam", "xbox", "psn",
+             * "mobile_game", etc. Use slugs from `getPlatforms()`.
+             */
+            platform?: string;
+            /**
+             * Filter by canonical category slug — "currency",
+             * "battle_pass", "bundle", etc. Use slugs from `getCategories()`.
+             */
+            category?: string;
         }) => Promise<PagedGamesResponse>;
+        /**
+         * List distribution platforms present in the site catalog with
+         * per-platform game counts (post site-overrides). Drives
+         * storefront filter chips. Introduced in task 118 Phase 3.
+         */
+        getPlatforms: () => Promise<PlatformInfo[]>;
+        /**
+         * List canonical category slugs present in the site catalog
+         * with per-slug game counts. Use the returned `slug` as the
+         * `category` argument to `getGames()`. Not to be confused with
+         * `getCategories(gameSlug)` which returns categories of a
+         * single game. Introduced in task 119 Phase 3.
+         */
+        getCatalogCategories: () => Promise<CategoryInfo[]>;
         /** Get homepage ranked games */
         getHomepageGames: () => Promise<Game[]>;
         /** Get single game with categories */

package/dist/index.js

@@ -109,6 +109,91 @@ class GameCoreClient {
     }),
     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 }),
+    renderTelegramWidget: async (opts) => {
+      if (typeof document === "undefined") {
+        throw new GameCoreError("renderTelegramWidget requires a browser environment", 0, "NO_DOM");
+      }
+      let botUsername = opts.botUsername;
+      if (!botUsername) {
+        const config = await this.request("GET", "/site/config");
+        botUsername = config.authConfig?.telegram?.botUsername ?? undefined;
+      }
+      if (!botUsername) {
+        throw new GameCoreError("Telegram bot is not configured for this site — contact the operator to set a bot in master-admin", 0, "TG_NOT_CONFIGURED");
+      }
+      const callbackName = `__gcTgWidget_${Math.random().toString(36).slice(2)}`;
+      const onAuth = opts.onAuth;
+      const onError = opts.onError;
+      const ref = opts.ref;
+      const verify = this.auth.verifyTelegramWidget.bind(this.auth);
+      window[callbackName] = async (user) => {
+        try {
+          const res = await verify(user, ref);
+          if (!res.user) {
+            throw new GameCoreError(res.error || "Telegram verification returned no user", 401, "VERIFY_FAILED");
+          }
+          await onAuth(res.user);
+        } catch (err) {
+          if (onError)
+            onError(err);
+          else
+            throw err;
+        }
+      };
+      const script = document.createElement("script");
+      script.async = true;
+      script.src = "https://telegram.org/js/telegram-widget.js?22";
+      script.setAttribute("data-telegram-login", botUsername);
+      script.setAttribute("data-size", opts.size ?? "large");
+      if (typeof opts.cornerRadius === "number") {
+        script.setAttribute("data-radius", String(opts.cornerRadius));
+      }
+      if (opts.showUserPic === false) {
+        script.setAttribute("data-userpic", "false");
+      }
+      if (opts.requestWriteAccess !== false) {
+        script.setAttribute("data-request-access", "write");
+      }
+      script.setAttribute("data-onauth", `${callbackName}(user)`);
+      opts.container.replaceChildren();
+      opts.container.appendChild(script);
+      return () => {
+        opts.container.replaceChildren();
+        delete window[callbackName];
+      };
+    },
+    loginViaTelegramBot: async (opts) => {
+      const init = await this.auth.initTelegram();
+      opts.onBotLinkReady(init.botLink, init.token);
+      const pollMs = opts.pollMs ?? 2000;
+      const timeoutMs = opts.timeoutMs ?? 120000;
+      const deadline = Date.now() + timeoutMs;
+      const refParam = opts.ref ? `?ref=${encodeURIComponent(opts.ref)}` : "";
+      return new Promise((resolve, reject) => {
+        const tick = async () => {
+          if (Date.now() > deadline) {
+            reject(new GameCoreError("Telegram login timed out", 408, "TIMEOUT"));
+            return;
+          }
+          try {
+            const res = await this.request("GET", `/auth/telegram/status/${init.token}${refParam}`, undefined, { rawResponse: true });
+            if (res.status === "authenticated" && res.user) {
+              resolve(res.user);
+              return;
+            }
+            if (res.status === "expired" || res.status === "used") {
+              reject(new GameCoreError("Telegram auth token expired", 410, "TOKEN_EXPIRED"));
+              return;
+            }
+          } catch (err) {
+            reject(err);
+            return;
+          }
+          setTimeout(tick, pollMs);
+        };
+        setTimeout(tick, pollMs);
+      });
+    },
     getVkAuthUrl: (redirectUri, ref) => {
       const params = new URLSearchParams;
       params.set("redirect", redirectUri);
@@ -120,7 +205,10 @@ class GameCoreClient {
     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 }),
+    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 }),
@@ -151,9 +239,15 @@ class GameCoreClient {
         qs.set("sort", params.sort);
       if (params?.q)
         qs.set("q", params.q);
+      if (params?.platform)
+        qs.set("platform", params.platform);
+      if (params?.category)
+        qs.set("category", params.category);
       const q = qs.toString();
       return this.request("GET", `/catalog/games${q ? `?${q}` : ""}`);
     },
+    getPlatforms: () => this.request("GET", "/catalog/platforms"),
+    getCatalogCategories: () => this.request("GET", "/catalog/categories"),
     getHomepageGames: () => this.request("GET", "/catalog/homepage-games"),
     getGame: (slug, locale) => {
       const qs = locale ? `?locale=${locale}` : "";
@@ -261,7 +355,9 @@ class GameCoreClient {
     },
     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 })
+    unsubscribePush: (endpoint) => this.request("POST", "/profile/push/unsubscribe", {
+      endpoint
+    })
   };
   favorites = {
     list: () => this.request("GET", "/favorites"),

package/dist/types.d.ts

@@ -69,6 +69,17 @@ export interface SiteConfig {
     };
     modules: Record<string, boolean>;
     auth: string[];
+    /**
+     * Structured per-method auth config. Companion to the flat `auth` array
+     * — `auth` tells you WHICH methods are available, `authConfig` gives
+     * the details you need to render each method on the client (bot
+     * username for the Telegram Login Widget, etc).
+     */
+    authConfig?: {
+        telegram: {
+            botUsername: string;
+        } | null;
+    };
     payments: string[];
     displayCurrency: string;
     rateMode: "auto" | "manual";
@@ -87,6 +98,76 @@ export interface SiteConfig {
         } | null;
     };
 }
+/**
+ * Options for the high-level {@link GameCoreClient.auth.renderTelegramWidget}
+ * helper. Values map 1:1 to Telegram Login Widget `data-*` attributes
+ * (see https://core.telegram.org/widgets/login).
+ */
+export interface TelegramWidgetRenderOptions {
+    /** DOM element the widget renders into. Previous children are cleared. */
+    container: HTMLElement;
+    /** Button size. Default: "large". */
+    size?: "small" | "medium" | "large";
+    /** Corner radius in pixels. Default: Telegram's own (20). */
+    cornerRadius?: number;
+    /**
+     * Show user photo next to the button. Default: true (matches Telegram's
+     * own default of `data-userpic="true"`).
+     */
+    showUserPic?: boolean;
+    /**
+     * Request permission to send messages to the user from the bot. Sets
+     * `data-request-access="write"`. Default: true.
+     */
+    requestWriteAccess?: boolean;
+    /**
+     * Called after the widget reports an authenticated user AND the
+     * payload has been verified by GameCore server-side (HMAC-SHA256).
+     * The `user` object is GameCore's {@link TelegramAuthUser} —
+     * the same shape the underlying `POST /auth/telegram/widget`
+     * endpoint returns.
+     */
+    onAuth: (user: TelegramAuthUser) => void | Promise<void>;
+    /**
+     * Called if verification fails (expired hash, wrong signature, or
+     * network error). When omitted the error is thrown to the browser's
+     * unhandled-promise handler.
+     */
+    onError?: (err: Error) => void;
+    /** Optional referral code to thread through to the signup flow. */
+    ref?: string;
+    /**
+     * Bot username override. Defaults to the value from `gc.site.getConfig()`
+     * — only pass this when you have not called getConfig() yet and want
+     * to skip that round trip.
+     */
+    botUsername?: string;
+}
+/**
+ * Options for the high-level {@link GameCoreClient.auth.loginViaTelegramBot}
+ * helper. Orchestrates the init → poll flow for users whose Telegram
+ * client can't render the Login Widget (third-party mobile clients with
+ * no active Telegram Web session, desktop browsers without TG Web
+ * logged in, etc).
+ */
+export interface TelegramBotLoginOptions {
+    /**
+     * Callback that receives the generated bot deep-link. Use it to open
+     * a popup, render a QR code, or redirect the user. This is called
+     * exactly once per login attempt, as soon as the server returns the
+     * link.
+     */
+    onBotLinkReady: (botLink: string, token: string) => void;
+    /** Poll interval in milliseconds. Default: 2000. */
+    pollMs?: number;
+    /**
+     * Give up after this many milliseconds. Default: 120000 (2 minutes,
+     * matches the server-side token TTL).
+     */
+    timeoutMs?: number;
+    /** Optional referral code to thread through to the signup flow. */
+    ref?: string;
+}
 export interface ExchangeRates {
     usdToRub: number;
     base: string;
@@ -216,6 +297,40 @@ export interface Category {
     productCount: number;
     deliveryTypes?: string[];
     platforms?: string[];
+    /**
+     * Canonical category slug (e.g. "currency", "battle_pass"). Present
+     * on responses from servers running task 119 Phase 2+. Stable across
+     * suppliers — Nexus "Алмазы" and Vendoria "Diamonds" both carry
+     * canonicalSlug="currency". Use this (not `name`) for storefront
+     * dedup and routing.
+     */
+    canonicalSlug?: string | null;
+}
+/**
+ * Distribution platform descriptor from GET /catalog/platforms.
+ * Use `slug` as the key for ?platform= filter and as a stable identifier
+ * across locales. `label` is storefront-ready display text.
+ * Introduced by task 118 Phase 3.
+ */
+export interface PlatformInfo {
+    slug: string;
+    label: string;
+    group: string;
+    gameCount: number;
+}
+/**
+ * Canonical category descriptor from GET /catalog/categories. Use
+ * `slug` as the key for ?category= filter. `labelRu`/`labelEn` are
+ * storefront-ready display text in each supported UI locale; pick
+ * whichever matches the current site locale. Introduced by task 119
+ * Phase 3.
+ */
+export interface CategoryInfo {
+    slug: string;
+    labelRu: string;
+    labelEn: string;
+    group: string;
+    gameCount: number;
 }
 export interface FulfillmentMeta {
     needsPlayerId: boolean;

package/package.json

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