@gamecore-api/sdk 0.9.0 → 0.12.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, 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";
 export interface GameCoreOptions {
     /** Site API key (gc_live_xxx or gc_test_xxx) */
     apiKey: string;
@@ -65,15 +65,82 @@ export declare class GameCoreClient {
         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;
         }>;
-        /** Verify VK access token and login/register */
+        /**
+         * 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 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 */
@@ -102,15 +169,29 @@ 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 */
@@ -185,7 +266,14 @@ export declare class GameCoreClient {
         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<{
@@ -199,8 +287,17 @@ 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<{
+        /**
+         * 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: unknown;
             orders: Order[];
         }>;

package/dist/index.js

@@ -105,8 +105,20 @@ 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 }),
@@ -118,6 +130,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 +146,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}` : ""}`);
     },
@@ -189,7 +207,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`)
   };

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,9 +125,17 @@ 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[];
@@ -496,6 +545,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,6 +1,6 @@
 {
 	"name": "@gamecore-api/sdk",
-	"version": "0.9.0",
+	"version": "0.12.0",
 	"description": "TypeScript SDK for GameCore API — browser-safe, zero dependencies",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",