@gamecore-api/sdk 0.17.1 → 0.19.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-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";
+import type { Announcement, AnnouncementBar, CartItem, CashbackPreview, CatalogSection, Category, CategoryInfo, CheckoutRequest, CheckoutResponse, CompleteWithBalanceResult, Conversation, ConversationDetail, CouponResult, DailyBonusClaimResult, DailyBonusStatus, ExchangeRates, Favorite, Game, GameDetail, GiftCard, LegalDocument, LevelStatus, Notification, Order, PagedGamesResponse, PlatformInfo, PaginatedResponse, PaymentInfo, PaymentMethod, Product, ProductFilters, PublicCoupon, Quest, QuestCompleteResult, ReferralCommission, ReferralLink, ReferralPerformance, ReferralStats, Review, ReviewCreateResult, ReviewProof, ReviewStats, ScreenshotsResponse, SearchResult, SiteConfig, SiteStats, SiteUIConfig, SystemRequirementsResponse, 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;
@@ -39,6 +39,17 @@ export declare class GameCoreClient {
         getTranslations: (locale?: string) => Promise<Record<string, string>>;
         /** Get site UI config (header, footer, nav, trust pills) */
         getUIConfig: () => Promise<SiteUIConfig>;
+        /**
+         * Per-site allowlist of partner origins permitted to iframe the
+         * storefront's checkout/widget pages. Wave 5 #58, available
+         * since gamecore-api 2026-05-01.
+         *
+         * Storefronts feed this list into their own
+         * `Content-Security-Policy: frame-ancestors` directive — this
+         * SDK call only fetches the data, it does not set the header
+         * itself (the storefront's edge / Next.js middleware does).
+         */
+        getEmbedAllowlist: () => Promise<string[]>;
         /** Get cookie consent config */
         getCookieConsent: () => Promise<{
             enabled: boolean;
@@ -106,6 +117,25 @@ export declare class GameCoreClient {
         initTelegram: () => Promise<TelegramInitResponse>;
         /** Poll Telegram auth status until authenticated or expired */
         pollTelegramStatus: (token: string, intervalMs?: number) => Promise<User>;
+        /**
+         * Read the storefront's Telegram OpenID Connect config. Returns
+         * { enabled: false, clientId: null } when the tenant hasn't set
+         * up Web Login in BotFather (the SPA should fall back to the
+         * deep-link flow). When enabled, hand `clientId` to telegram-
+         * login.js to render the native consent card.
+         */
+        getTelegramOidcConfig: () => Promise<{
+            enabled: boolean;
+            clientId: string | null;
+        }>;
+        /**
+         * Submit the RS256 id_token returned by telegram-login.js for
+         * server-side JWKS verification. On success the backend sets an
+         * auth cookie and returns the authenticated user, exactly like
+         * the Mini App / Widget verifiers. Optional `ref` threads a
+         * referral code through user creation on first login.
+         */
+        telegramOidc: (idToken: string, ref?: string) => Promise<TelegramAuthResponse>;
         /**
          * Verify Telegram Mini App initData and issue a session cookie.
          * Call this when your storefront is opened inside Telegram via the
@@ -343,6 +373,26 @@ export declare class GameCoreClient {
          *   server-side.
          */
         getRecommendations: (gameSlug: string, limit?: number) => Promise<Game[]>;
+        /**
+         * Steam-sourced PC system requirements for a canonical game.
+         * Designed for `/games/<slug>/system-requirements` SEO landings.
+         * Returns `{ hasData: false }` for non-Steam games (and for
+         * Steam games Steam didn't return data for) so the frontend
+         * can branch without try/catch.
+         *
+         * Cached 7 days server-side; the very first request for a game
+         * fetches synchronously, subsequent stale reads serve cached
+         * data and refresh in the background. Available since
+         * gamecore-api 2026-05-01 (Wave 5 #50).
+         */
+        getGameSystemRequirements: (gameSlug: string) => Promise<SystemRequirementsResponse>;
+        /**
+         * Steam-sourced screenshot gallery + trailers for a canonical
+         * game. Same `hasData` semantics as
+         * `getGameSystemRequirements`. Available since gamecore-api
+         * 2026-05-01 (Wave 5 #50).
+         */
+        getGameScreenshots: (gameSlug: string) => Promise<ScreenshotsResponse>;
         /** Get categories for a game with product counts and delivery metadata */
         getCategories: (gameSlug: string) => Promise<Category[]>;
         /** Get products for a game with optional filters */
@@ -437,6 +487,29 @@ export declare class GameCoreClient {
         remove: (id: number) => Promise<void>;
         /** Clear all cart items */
         clear: () => Promise<void>;
+        /**
+         * Cashback preview for the current cart (Wave 5 #51, available
+         * since gamecore-api 2026-05-01). Returns the credit the
+         * authenticated user would receive after the cart is paid for,
+         * given the user's current loyalty level + per-site cashback
+         * rate.
+         *
+         * **Requires authentication** — the endpoint sits behind the
+         * same auth gate as the rest of `/cart/*`; calling it without
+         * a session throws `GameCoreError(401, 'UNAUTHORIZED')`. Show
+         * a "Войдите, чтобы получать кэшбэк" hint on the storefront
+         * and skip the request for anonymous users instead of
+         * catching the 401.
+         *
+         * For tenants that have not configured cashback rates the
+         * response is `totalAmount: 0` with a UX hint in
+         * `rateExplanation` rather than an error.
+         *
+         * Storefronts: call this near the checkout button to render a
+         * "+N бонусов" trigger. Cheap (1 SQL aggregate); call freely
+         * after add/remove without caching.
+         */
+        getCashbackPreview: () => Promise<CashbackPreview>;
     };
     checkout: {
         /**
@@ -519,6 +592,51 @@ export declare class GameCoreClient {
         markRead: (id: number) => Promise<void>;
         /** Mark all notifications as read */
         markAllRead: () => Promise<void>;
+        /**
+         * Submit a screenshot of a review the user posted on a third-
+         * party platform (T-Bank, Otzyvru, Google Play, …). Lands in
+         * the moderator queue; once approved, the user gets a fixed
+         * payout to their balance.
+         *
+         * Available since gamecore-api 2026-05-01 (Wave 5 #56).
+         */
+        submitReviewProof: (input: {
+            platform: string;
+            screenshotUrl: string;
+            reviewUrl?: string;
+            userNote?: string;
+        }) => Promise<ReviewProof>;
+        /** List the current user's review-proof submissions, newest first. */
+        getReviewProofs: () => Promise<ReviewProof[]>;
+        /**
+         * Daily-bonus status: whether the user can claim, current
+         * streak, projected reward, and `nextAvailableAt` cooldown
+         * timestamp. Available since gamecore-api 2026-05-01
+         * (Wave 5 #49).
+         */
+        getDailyBonus: () => Promise<DailyBonusStatus>;
+        /**
+         * Claim the daily bonus. Atomic — concurrent claims race on a
+         * CAS check and only one wins; the loser sees a
+         * `cooldown_active` error. Reward formula:
+         *   `base(10₽) * min(1 + streak*0.1, 3.0) * (0.5 + Math.random())`.
+         */
+        claimDailyBonus: () => Promise<DailyBonusClaimResult>;
+        /**
+         * Quest catalog with the caller's progress folded in. Pass
+         * filters to narrow by `type` (daily/weekly/one_time) or
+         * lifecycle `status`.
+         */
+        getQuests: (filter?: {
+            type?: "daily" | "weekly" | "one_time";
+            status?: "available" | "in_progress" | "completed" | "claimed";
+        }) => Promise<Quest[]>;
+        /**
+         * Claim a quest reward. Eligibility is rechecked server-side
+         * before crediting. Idempotent — a second claim returns
+         * `alreadyClaimed: true` with rewardAmount=0.
+         */
+        completeQuest: (questCode: string) => Promise<QuestCompleteResult>;
         /** Delete user account */
         deleteAccount: () => Promise<void>;
         /** Export user data (GDPR) */
@@ -614,6 +732,21 @@ export declare class GameCoreClient {
         validate: (code: string, gameId?: string) => Promise<CouponResult>;
         /** Get user's currently active coupon */
         getActive: () => Promise<CouponResult | null>;
+        /**
+         * Public listing of active coupons applicable to a specific
+         * game. Designed for programmatic-SEO landings such as
+         * `/promocode/<gameSlug>`. Works without authentication; the
+         * api-key still has to be present so the response is scoped to
+         * the calling site.
+         *
+         * Each row carries either a code (when `isPublic === true` and
+         * the operator chose to expose it) or a hidden offer
+         * (`code: null, isPublic: false`) for cases where the storefront
+         * wants to advertise the discount without leaking the code.
+         *
+         * Available since gamecore-api 2026-05-01 (Wave 5 #54).
+         */
+        getActiveForGame: (gameSlug: string) => Promise<PublicCoupon[]>;
     };
     referrals: {
         /** Get referral dashboard stats */

package/dist/index.js

@@ -81,6 +81,7 @@ class GameCoreClient {
     getThemeConfig: () => this.request("GET", "/site/theme"),
     getTranslations: (locale = "ru") => this.request("GET", `/site/translations?locale=${locale}`),
     getUIConfig: () => this.request("GET", "/site/ui-config"),
+    getEmbedAllowlist: () => this.request("GET", "/site/embed-allowlist"),
     getCookieConsent: () => this.request("GET", "/site/cookie-consent"),
     getCatalogSections: () => this.request("GET", "/site/catalog-sections"),
     getBanners: () => this.request("GET", "/site/banners"),
@@ -107,6 +108,8 @@ class GameCoreClient {
         }
       }, intervalMs);
     }),
+    getTelegramOidcConfig: () => this.request("GET", "/auth/telegram/oidc/config"),
+    telegramOidc: (idToken, ref) => this.request("POST", "/auth/telegram/oidc/callback", { idToken, ref }, { rawResponse: true }),
     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) => {
@@ -254,6 +257,8 @@ class GameCoreClient {
       return this.request("GET", `/catalog/games/${slug}${qs}`);
     },
     getRecommendations: (gameSlug, limit = 8) => this.request("GET", `/catalog/games/${gameSlug}/recommendations?limit=${limit}`),
+    getGameSystemRequirements: (gameSlug) => this.request("GET", `/catalog/games/${gameSlug}/system-requirements`),
+    getGameScreenshots: (gameSlug) => this.request("GET", `/catalog/games/${gameSlug}/screenshots`),
     getCategories: (gameSlug) => this.request("GET", `/catalog/games/${gameSlug}/categories`),
     getProducts: (gameSlug, filters) => {
       const qs = new URLSearchParams;
@@ -290,7 +295,8 @@ class GameCoreClient {
     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")
+    clear: () => this.request("DELETE", "/cart"),
+    getCashbackPreview: () => this.request("GET", "/cart/cashback-preview")
   };
   checkout = {
     create: (data, idempotencyKey) => this.request("POST", "/checkout", data, {
@@ -329,6 +335,20 @@ class GameCoreClient {
     getUnreadCount: () => this.request("GET", "/profile/notifications/unread-count"),
     markRead: (id) => this.request("POST", `/profile/notifications/${id}/read`),
     markAllRead: () => this.request("POST", "/profile/notifications/read-all"),
+    submitReviewProof: (input) => this.request("POST", "/profile/review-proofs", input),
+    getReviewProofs: () => this.request("GET", "/profile/review-proofs"),
+    getDailyBonus: () => this.request("GET", "/profile/daily-bonus"),
+    claimDailyBonus: () => this.request("POST", "/profile/daily-bonus/claim"),
+    getQuests: (filter) => {
+      const qs = new URLSearchParams;
+      if (filter?.type)
+        qs.set("type", filter.type);
+      if (filter?.status)
+        qs.set("status", filter.status);
+      const q = qs.toString();
+      return this.request("GET", `/profile/quests${q ? `?${q}` : ""}`);
+    },
+    completeQuest: (questCode) => this.request("POST", `/profile/quests/${encodeURIComponent(questCode)}/complete`),
     deleteAccount: () => this.request("POST", "/profile/delete-account"),
     exportData: () => this.request("GET", "/profile/export"),
     getSettings: () => this.request("GET", "/profile/settings"),
@@ -368,7 +388,8 @@ class GameCoreClient {
     apply: (code) => this.request("POST", "/coupons/apply", { code }),
     remove: () => this.request("DELETE", "/coupons/active"),
     validate: (code, gameId) => this.request("POST", "/coupons/validate", { code, gameId }),
-    getActive: () => this.request("GET", "/profile/active-coupon")
+    getActive: () => this.request("GET", "/profile/active-coupon"),
+    getActiveForGame: (gameSlug) => this.request("GET", `/coupons/active?game=${encodeURIComponent(gameSlug)}`)
   };
   referrals = {
     getStats: () => this.request("GET", "/referral/stats"),

package/dist/types.d.ts

@@ -377,6 +377,23 @@ export interface Product {
     deliveryDataSchema: unknown[];
     region?: string;
     platform?: string;
+    /**
+     * Per-SKU variant metadata for the multi-SKU product picker.
+     * Available since gamecore-api 2026-05-01 (Wave 5 #52). All four
+     * fields are nullable — products without an operator-configured
+     * variant grouping leave them at `null` and the storefront falls
+     * back to single-SKU rendering.
+     *
+     * `riskTier` drives the badge ("Безопасно" / "Нужен логин" /
+     * "Полный доступ"); `warningMessage` is short copy under the
+     * variant tabs; `variantGroup` is an opaque key shared by SKUs
+     * that should be folded into one radio-group; `variantLabel` is
+     * the short tab title within that group.
+     */
+    riskTier?: "safe" | "moderate" | "requires_credentials" | null;
+    warningMessage?: string | null;
+    variantGroup?: string | null;
+    variantLabel?: string | null;
 }
 export interface ProductFilters {
     deliveryType?: string;
@@ -422,6 +439,81 @@ export interface CartItem {
      */
     productIcon?: string | null;
 }
+/**
+ * Per-cart cashback preview surfaced by `gc.cart.getCashbackPreview()`.
+ * `totalAmount` is the credit (in site balance units) the
+ * authenticated user would receive after the cart is paid for at the
+ * current state.
+ *
+ * The endpoint requires authentication — `gc.cart.getCashbackPreview()`
+ * throws `GameCoreError(401)` for anonymous callers. Storefronts
+ * should skip the request when the user is not signed in instead of
+ * relying on a graceful empty response. For tenants whose cashback
+ * rates are not configured the API returns `totalAmount: 0` with a
+ * UX hint in `rateExplanation`.
+ *
+ * Available since gamecore-api 2026-05-01 (Wave 5 #51).
+ */
+export interface CashbackPreview {
+    totalAmount: number;
+    currency: "balance";
+    breakdown: Array<{
+        source: "level_base";
+        amount: number;
+        label: string;
+    }>;
+    rateExplanation: string;
+}
+/**
+ * One block of Steam-sourced PC requirements (minimum or recommended).
+ * Available since gamecore-api 2026-05-01 (Wave 5 #50).
+ */
+export interface SystemRequirementsBlock {
+    os?: string;
+    processor?: string;
+    memory?: string;
+    graphics?: string;
+    directX?: string;
+    storage?: string;
+    soundCard?: string;
+    additional?: string;
+}
+/**
+ * Response from `gc.catalog.getGameSystemRequirements()`. `hasData`
+ * is false for non-Steam games and Steam games where Steam couldn't
+ * supply requirements — frontends should branch on this rather than
+ * treating an empty `minimum`/`recommended` as an error.
+ */
+export interface SystemRequirementsResponse {
+    hasData: boolean;
+    minimum: SystemRequirementsBlock;
+    recommended: SystemRequirementsBlock;
+    source: "steam";
+    fetchedAt: string;
+}
+export interface SteamScreenshot {
+    thumbnailUrl: string;
+    fullUrl: string;
+    order: number;
+}
+export interface SteamMovie {
+    thumbnailUrl: string;
+    webmUrl?: string;
+    mp4Url?: string;
+    title: string;
+}
+/**
+ * Response from `gc.catalog.getGameScreenshots()`. `hasData` mirrors
+ * the system-requirements semantics: false when no screenshots OR
+ * movies are available.
+ */
+export interface ScreenshotsResponse {
+    hasData: boolean;
+    screenshots: SteamScreenshot[];
+    movies: SteamMovie[];
+    source: "steam";
+    fetchedAt: string;
+}
 export interface CheckoutRequest {
     email?: string;
     items: Array<{
@@ -831,6 +923,107 @@ export interface CouponResult {
     gameId?: number | null;
     bonusAmount?: number;
 }
+/**
+ * Public-facing coupon entry returned by `gc.coupons.getActiveForGame()`.
+ * Designed for SEO landings (`/promocode/<gameSlug>`). `code` is `null`
+ * when the operator chose to advertise the offer without exposing the
+ * code itself (`isPublic === false`); the storefront still renders the
+ * card with `description`, validity window, and discount details.
+ *
+ * Available since gamecore-api 2026-05-01 (Wave 5 #54).
+ */
+export interface PublicCoupon {
+    code: string | null;
+    isPublic: boolean;
+    type: "bonus_balance" | "markup_discount";
+    value: number;
+    gameId: string | null;
+    description: string | null;
+    validFrom: string | null;
+    validUntil: string | null;
+    usagesLeft: number | null;
+    oneTimePerUser: boolean;
+}
+/**
+ * Daily-bonus claim status returned by `gc.profile.getDailyBonus()`.
+ * `available` is true when the cooldown has elapsed; `nextRewardAmount`
+ * is a preview of what the user would get on the next claim using
+ * the current streak. Available since gamecore-api 2026-05-01
+ * (Wave 5 #49).
+ */
+export interface DailyBonusStatus {
+    available: boolean;
+    currentStreak: number;
+    longestStreak: number;
+    nextRewardAmount: number;
+    nextAvailableAt: string | null;
+    streakMultiplier: number;
+    lastClaimedAt: string | null;
+    totalClaimedAmount: number;
+}
+export interface DailyBonusClaimResult {
+    claimedAmount: number;
+    newStreak: number;
+    newBalance: number;
+    nextAvailableAt: string;
+}
+/**
+ * Quest catalog entry returned by `gc.profile.getQuests()`.
+ * Status lifecycle:
+ *   available → in_progress → completed → claimed
+ * `verificationMode` describes how the quest is checked:
+ *   * `auto`   — backend computes progress from order/event tables.
+ *   * `trust`  — storefront sends a click signal (TG/VK subscribe).
+ *   * `manual` — admin moderates (e.g. tied to review-proof #56).
+ *
+ * Available since gamecore-api 2026-05-01 (Wave 5 #49).
+ */
+export interface Quest {
+    id: number;
+    code: string;
+    type: "daily" | "weekly" | "one_time";
+    category: string | null;
+    titleRu: string;
+    titleEn: string | null;
+    descriptionRu: string | null;
+    descriptionEn: string | null;
+    rewardAmount: number;
+    rewardCurrency: string;
+    verificationMode: "auto" | "trust" | "manual";
+    iconUrl: string | null;
+    status: "available" | "in_progress" | "completed" | "claimed";
+    progressCurrent: number;
+    progressRequired: number;
+    expiresAt: string | null;
+}
+export interface QuestCompleteResult {
+    rewardAmount: number;
+    newBalance: number;
+    alreadyClaimed: boolean;
+}
+/**
+ * Review-proof submission row returned by `gc.profile.getReviewProofs()`
+ * and surfaced to admins via `gc.admin.reviewProofs.list()`. Available
+ * since gamecore-api 2026-05-01 (Wave 5 #56).
+ *
+ * Status flow: pending → approved (gets `payoutAmount`) or rejected
+ * (gets `moderatorNote`). Already-resolved rows cannot transition again.
+ */
+export interface ReviewProof {
+    id: number;
+    siteId: number;
+    userId: number;
+    platform: string;
+    screenshotUrl: string;
+    reviewUrl: string | null;
+    userNote: string | null;
+    status: "pending" | "approved" | "rejected";
+    payoutAmount: number | null;
+    moderatorNote: string | null;
+    reviewedByUserId: number | null;
+    reviewedAt: string | null;
+    createdAt: string;
+}
 export interface ReferralStats {
     totalReferrals: number;
     lifetimeEarnings: number;

package/package.json

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