@gamecore-api/sdk 0.14.0 → 0.16.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, CheckoutRequest, CheckoutResponse, CompleteWithBalanceResult, Conversation, ConversationDetail, CouponResult, ExchangeRates, Favorite, Game, GameDetail, GiftCard, LegalDocument, LevelStatus, Notification, Order, PagedGamesResponse, 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).
          *

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 }),
@@ -261,7 +349,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;
@@ -130,8 +211,28 @@ export interface GameDetail {
     /** Gallery of product screenshots (resized to 800x600). */
     images?: string[];
     description: string | null;
+    /**
+     * Short teaser (<= 200 chars) suitable for list cards and meta
+     * descriptions. Distinct from `description` which may be multi-paragraph.
+     */
+    shortDescription?: string | null;
     /** Editorial badges like "hit", "new", "popular", "sale". */
     tags?: string[];
+    /** Game developers (studio names). Empty when supplier doesn't send it. */
+    developers?: string[];
+    /** Game publishers. Empty when supplier doesn't send it. */
+    publishers?: string[];
+    /** Genre labels ("Strategy", "RPG", ...). Empty for mobile-donation games. */
+    genres?: string[];
+    /**
+     * Upstream release date as the supplier sends it — may be an ISO date
+     * "YYYY-MM-DD", a localized natural-language string ("6 июн. 2016 г."),
+     * or null when unknown. Storefronts should render verbatim; do not
+     * parse as a reliable Date.
+     */
+    releaseDate?: string | null;
+    /** Steam app id — null for non-Steam titles and mobile games. */
+    steamAppid?: number | null;
     /** Availability lifecycle. Shares the union from {@link Game}. */
     availabilityStatus?: "available" | "coming_soon" | "maintenance" | "discontinued";
     /** Human-readable message for non-available games. */

package/package.json

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