import type { Announcement, AnnouncementBar, CartItem, CashbackPreview, CatalogFacets, CatalogLetterCounts, CatalogSection, CatalogSitemapRoutesResponse, Category, CategoryInfo, CheckoutCreateOptions, CheckoutItemInput, CheckoutPreview, CheckoutPreviewOptions, CheckoutRequest, CheckoutResponse, CheckoutStatus, CmsArticleListResponse, CmsArticleLocale, CmsArticleResponse, CmsArticleType, CodeReadinessResult, CoinPurchaseResult, CoinPurchaseStatus, CoinRedeemResult, CoinRedemption, CoinReward, CoinTransaction, CoinWallet, CoinWinner, CompleteWithBalanceResult, Conversation, ConversationDetail, CouponResult, CustomerCancelResult, DailyBonusClaimResult, DailyBonusStatus, DeliveryHelpResponse, DeliveryImageUpload, ExchangeRates, FaqListResponse, Favorite, Game, GameDetail, GameRequestList, GiftCard, GuestCheckoutSessionRequest, GuestCheckoutSessionResponse, LegalDocument, LevelStatus, MarketingTrackVisitRequest, MarketingTrackVisitResult, MarketingVisitRefs, Notification, Order, OrderKeyState, OrderKeyStateResult, PackRequest, PackRequestGame, PackRequestPayResponse, PagedGamesResponse, PaginatedResponse, PaymentInfo, PaymentMethod, PlatformInfo, Product, ProductFilters, ProfileSummary, PublicCoupon, PublicSupportRequest, PublicSupportResponse, Quest, QuestCompleteResult, RecentPurchase, ReferralCommission, ReferralLink, ReferralPerformance, ReferralStats, ReferralTransferResult, ReorderItemResult, Review, ReviewCreateOptions, ReviewCreateResult, ReviewGuestCreateOptions, ReviewGuestCreateResult, ReviewPolicy, ReviewProof, ReviewStats, ScreenshotsResponse, SearchResult, SeoSitemapEntry, SiteConfig, SiteStats, SiteUIConfig, SuperpassGameResponse, SuperpassGameSummary, SuperpassUserVerification, SupportCallAdminResult, SupportMessage, SupportThread, SystemRequirementsResponse, TelegramAuthResponse, TelegramBotLoginOptions, TelegramInitResponse, TelegramWidgetRenderOptions, TelegramWidgetUser, TopupCreateOptions, TopupMethod, TopupResponse, TopupStatus, Transaction, User, UserBalance, WebPushSubscriptionInput } from "./types";
/**
 * Supported storefront locales — extend as new languages land.
 * "es" (Spanish) and "pt-br" (Brazilian Portuguese) are LATAM: the API maps
 * them to the `latam` payment region, so a client created with one of these
 * is not offered Russia-only payment rails. Extend as new languages land.
 *
 * "fa" (Persian) is recognised by every API resolver as of the fa layer-0
 * change. It is RTL, and no tenant lists it in `sites.additional_locales`
 * yet — so setting it today yields the API's untranslated fallbacks rather
 * than Persian content.
 *
 * ⚠ KNOWN GAP, pre-existing and NOT introduced by the fa work: "uk" is
 * missing from this union even though the API treats it as first-class and
 * the kazakevich tenant's default_locale IS uk. A uk storefront currently
 * needs a cast to set it. Widening is type-only (the runtime already accepts
 * any string) but is left out of the fa change on purpose — it is a separate
 * decision about a live tenant.
 */
export type SdkLocale = "ru" | "en" | "es" | "pt-br" | "fa";
/**
 * ISO-4217 codes the API can quote prices in. Matches the server-side
 * `DisplayCurrency` union in `apps/api/src/utils/currency.ts`. RUB is
 * the default when nothing is configured; USD is the canonical base
 * price in the DB.
 */
export type SdkCurrency = "RUB" | "USD" | "EUR" | "GBP" | "KZT" | "UAH" | "TRY" | "BRL" | "ARS" | "INR" | "PLN" | "CZK";
export interface GameCoreOptions {
    /** Site API key (gc_live_xxx or gc_test_xxx) */
    apiKey: string;
    /** Base URL of GameCore API (e.g. https://api.gamecore-api.tech) */
    baseUrl: string;
    /** Called on 401 — use to redirect to login */
    onAuthError?: () => void;
    /**
     * Default locale for catalog/CMS responses. When set, every request
     * sends an `Accept-Language` header so the API returns localized
     * name/description fields without each call passing `locale=` itself.
     * Per-call `locale` arguments still take precedence over the default.
     * Omit to keep the legacy behaviour (server falls back to "ru").
     */
    locale?: SdkLocale;
    /**
     * Default display currency for catalog product prices. When set,
     * every request sends an `X-Currency` header so the API converts
     * `price` / `priceWithoutDiscount` into that ISO-4217 code (using
     * live FX rates) and stamps the resolved code on each product
     * response under the `currency` field.
     *
     * Per-call `?currency=` overrides this default. Omit to keep RUB
     * (the legacy default — every existing storefront keeps working
     * without a code change).
     */
    currency?: SdkCurrency;
}
export declare class GameCoreClient {
    private apiKey;
    private baseUrl;
    private onAuthError?;
    private defaultLocale?;
    private defaultCurrency?;
    constructor(options: GameCoreOptions);
    /**
     * Switch the client's default locale at runtime — useful for a
     * storefront language switcher that should not have to re-instantiate
     * the client.
     */
    setLocale(locale: SdkLocale | undefined): void;
    /** Current default locale (undefined when none set). */
    getLocale(): SdkLocale | undefined;
    /**
     * Switch the client's default display currency at runtime — wire to
     * a storefront currency picker so the next product fetch comes back
     * already converted, without re-instantiating the client.
     */
    setCurrency(currency: SdkCurrency | undefined): void;
    /** Current default currency (undefined when none set → API returns RUB). */
    getCurrency(): SdkCurrency | undefined;
    private request;
    site: {
        /** Get site configuration (modules, auth methods, payments, currency) */
        getConfig: () => Promise<SiteConfig>;
        /** Get current exchange rates (USD→RUB and others) */
        getRates: () => Promise<ExchangeRates>;
        /** Get legal document by type (privacy, terms, etc.) */
        getLegal: (type: string, locale?: string) => Promise<LegalDocument>;
        /** Get site statistics for trust signals (cached 5 min on server) */
        getStats: () => Promise<SiteStats>;
        /** Get social proof — recent purchases for trust display */
        getSocialProof: () => Promise<{
            recentPurchases: Array<{
                gameName: string;
                timeAgo: string;
            }>;
        }>;
        /**
         * Public "recent purchases" feed for the homepage social-proof
         * ticker. Returns the last week of completed orders, deduped to
         * one row per order, privacy-masked (first name, masked
         * username, or "Покупатель"). Distinct from `getSocialProof()`
         * — that one is a thinner `{gameName,timeAgo}[]` projection
         * powered by the same data but shaped for a different widget.
         *
         * `limit` is clamped server-side to [1, 30]; default 15.
         */
        getRecentPurchases: (params?: {
            limit?: number;
        }) => Promise<RecentPurchase[]>;
        /** Get theme config (white-label colors, fonts, borderRadius) */
        getThemeConfig: () => Promise<{
            colors: Record<string, string>;
            borderRadius: string;
            font: string;
        }>;
        /** Get site translations for a locale (Record<key, value>) */
        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;
            text: string;
            policyUrl: string;
        }>;
        /** Get per-site catalog sections (category tabs config) */
        getCatalogSections: () => Promise<CatalogSection[]>;
        /**
         * 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()`.
         *
         * 🔴 Since 0.71.0 `slug` is the tenant's OWN url on a site with
         * per-site catalog pages — an ADDRESS, not the platform identity. Emit
         * it as-is; see {@link SeoSitemapEntry.slug}.
         */
        getSitemapData: () => Promise<SeoSitemapEntry[]>;
        /**
         * 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;
        }>;
        /**
         * Get the per-site review-payout policy. Storefronts use this on
         * the order success page to decide whether to advertise a
         * cashback bonus for posting a review, and to enforce the
         * minimum text length client-side before submission.
         */
        getReviewPolicy: () => Promise<ReviewPolicy>;
        /**
         * Get FAQ entries for this site. Without `gameId`, returns all
         * active site-wide FAQ entries (rows with `gameId: null`). When
         * `gameId` is provided, returns ONLY entries scoped to that
         * game — site-wide entries are NOT included in the response.
         * Storefronts that want both site-wide and game-specific FAQ
         * on the same page must call this method twice and merge the
         * results client-side. `position` is the display order (lower
         * first); `gameId: null` marks site-wide entries.
         */
        getFaq: (gameId?: number) => Promise<FaqListResponse>;
        /**
         * List published CMS articles of a given type for the current
         * site. Returns a summary projection (no body) — call
         * `getArticle()` to fetch a single article's full content.
         *
         * `locale` defaults to the site's default locale on the
         * server (currently "ru") when omitted. `limit` is capped
         * server-side at 100; `offset` enables pagination.
         *
         * `type: "guide"` (SDK 0.48.0+) returns AI-generated game
         * guides — each summary carries `entityKind`/`entityId`/
         * `entitySlug` linking it back to the SuperPass or canonical
         * game it's about. Other article types always return those
         * three fields as `null`.
         */
        getArticles: (type: CmsArticleType, options?: {
            locale?: CmsArticleLocale;
            limit?: number;
            offset?: number;
        }) => Promise<CmsArticleListResponse>;
        /**
         * Fetch a single published CMS article by slug, in the requested
         * locale EXACTLY.
         *
         * 🔴 Behaviour change (SDK 0.69.0): the server used to fall back
         * to the RU article when the requested locale was missing. It no
         * longer does — a slug that exists only in RU now throws 404 for
         * `{ locale: "en" }` instead of returning the Russian body. This
         * is intentional: the old fallback served one body under two
         * locale URLs (duplicate content) and made hreflang advertise
         * translations that didn't exist. A storefront that relied on the
         * fallback to always render something must now either request
         * "ru" explicitly or treat 404 as "no translation yet" and skip
         * the URL in its hreflang/sitemap output.
         *
         * `article.locale` is therefore always the locale you asked for;
         * there is no fallback left to detect.
         *
         * Throws `GameCoreError(404)` when no published article matches
         * the requested type/slug/locale triple.
         */
        getArticle: (type: CmsArticleType, slug: string, options?: {
            locale?: CmsArticleLocale;
        }) => Promise<CmsArticleResponse>;
    };
    auth: {
        /** Start Telegram auth flow → returns bot link for user to click */
        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; optional
         * `mv` threads marketing visit refs the same way.
         */
        telegramOidc: (idToken: string, ref?: string, mv?: MarketingVisitRefs) => Promise<TelegramAuthResponse>;
        /**
         * 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;
         * optional `mv` threads marketing visit refs the same way.
         */
        verifyMiniApp: (initData: string, ref?: string, mv?: MarketingVisitRefs) => 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, mv?: MarketingVisitRefs) => 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).
         *
         * 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, mv?: MarketingVisitRefs) => Promise<{
            url: string;
            state: string;
        }>;
        /**
         * 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, mv?: MarketingVisitRefs) => Promise<{
            status: string;
            user: User;
        }>;
        /** Register with email + password. No auth required. */
        register: (email: string, password: string, firstName?: string, ref?: string, mv?: MarketingVisitRefs) => 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;
        }>;
        /**
         * Request a passwordless magic-link + 6-digit code by email. No auth
         * required. Always resolves `{ success: true }` (anti-enumeration —
         * never reveals whether the email already has an account).
         */
        requestEmailLink: (email: string, opts?: {
            ref?: string;
            firstName?: string;
        } & MarketingVisitRefs) => Promise<{
            success: boolean;
        }>;
        /**
         * Verify a magic-link token (from the email button) OR an (email, code)
         * pair. Registers a new user or logs in an existing one, returning a
         * session token + user (same shape as register/login).
         */
        verifyEmail: (params: {
            token: string;
        } | {
            email: string;
            code: 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 */
        logout: () => Promise<void>;
        /**
         * List identities linked to the current account.
         *
         * Returns BOTH a typed `identities` object (preferred for new
         * code — `identities.email.linked`, `identities.telegram.linked`,
         * etc.) AND a legacy `providers` array (kept for storefronts
         * that already read it). When you are wiring a fresh "Settings
         * → Connected accounts" screen, use `identities`; the legacy
         * shape will stay forever but won't grow new providers.
         */
        getIdentities: () => Promise<{
            identities: {
                email: {
                    linked: boolean;
                    address: string | null;
                    hasPassword: boolean;
                };
                telegram: {
                    linked: boolean;
                    username: string | null;
                };
                vk: {
                    linked: boolean;
                };
            };
            providers: Array<{
                provider: string;
                linked: boolean;
                displayName: string | null;
            }>;
        }>;
        /** Link VK account to current user */
        linkVk: (accessToken: string) => Promise<void>;
        /**
         * Link a Telegram account to the currently authenticated user
         * using the same id_token the storefront receives from the
         * Telegram OIDC login widget. The user must already be logged
         * in (e.g. via email/password) and must not already have a
         * Telegram bound. The backend verifies the token, checks for
         * collisions on this site, and writes an audit-log entry.
         *
         * Typical flow for the storefront:
         *   1. user is authenticated via email/password;
         *   2. user clicks "Connect Telegram" → telegram-login.js
         *      mounts and returns an `id_token`;
         *   3. storefront calls `auth.linkTelegramOidc({ idToken })`;
         *   4. on success, call `auth.getIdentities()` to refresh the
         *      "Connected accounts" panel.
         */
        linkTelegramOidc: (input: {
            idToken: string;
        }) => Promise<{
            success: boolean;
            provider: "telegram";
            telegramId: string;
            username: string | null;
        }>;
        /**
         * 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;
        }>;
        /**
         * STEP 1 of confirming a mailbox you already use (API 0275,
         * `EMAIL_VISIBILITY`). Mails a 6-digit code to `email`. Requires a
         * session; the code goes to the MAILBOX, never to the response.
         *
         * Use this when `linkEmail()` refuses with
         * `code: "email_belongs_to_other_account"` — the classic case being a
         * buyer who checked out as a guest under this address and later signed in
         * with Telegram, so their orders live on a different row.
         *
         * ANTI-ENUMERATION: the response is identical for every address —
         * registered, free, or throttled. Never present it as "we found your
         * account"; say only "if that address exists, a code is on its way".
         * 404 means the tenant does not have the feature enabled.
         */
        requestEmailConfirm: (email: string) => Promise<{
            success: boolean;
        }>;
        /**
         * STEP 2: submit the emailed code. On success the orders of the account
         * behind that address appear in `profile.getOrders()`, each tagged with
         * {@link Order.linkedAccountEmail}.
         *
         * READ-ONLY: no merge, no balance transfer, no ownership change — the
         * other account keeps its own login, wallet and orders. Every failure
         * (wrong, expired, already used, too many attempts) answers the same
         * generic `invalid`; codes expire in 10 minutes and lock after 5 wrong
         * tries.
         */
        confirmEmail: (email: string, code: string) => Promise<{
            success: boolean;
            email: string;
            ordersVisible: boolean;
        }>;
        /**
         * The mailboxes this account has confirmed, for a "connected addresses"
         * panel.
         *
         * Deliberately says NOTHING about whether an account exists behind an
         * address: anyone can request a confirmation for any address, so a
         * "this one grants access" flag here would be an account-enumeration
         * oracle that needs no mailbox access at all. Render the claim, not a
         * verdict about the other side.
         */
        listEmailClaims: () => Promise<{
            success: boolean;
            data: Array<{
                email: string;
                verifiedAt: string;
                active: boolean;
            }>;
        }>;
        /**
         * TARGET SIDE — which accounts can currently see THIS user's order
         * history, for a "who has access" panel. `requester` is masked (e.g.
         * `b***@mail.ru`, `@handle`): enough to recognise an account you
         * authorised, not a directory of other people's addresses.
         */
        listEmailAccess: () => Promise<{
            success: boolean;
            data: Array<{
                requester: string;
                verifiedAt: string;
            }>;
        }>;
        /**
         * TARGET SIDE — "someone can see my order history; stop it." Drops every
         * claim pointing at the caller's own account and returns how many went.
         *
         * This is the button the post-confirmation warning mail refers to. It
         * takes no parameters at all: the scope comes from the session, so there
         * is nothing to tamper with, and it can never touch anyone else's data.
         */
        revokeEmailAccess: () => Promise<{
            success: boolean;
            revoked: number;
        }>;
        /**
         * Give the access back. Idempotent (`revoked: false` simply means there
         * was nothing to drop) and scoped to the caller's own claims — you can
         * never revoke someone else's. The linked order group disappears from
         * `profile.getOrders()` immediately.
         */
        revokeEmailConfirm: (email: string) => Promise<{
            success: boolean;
            revoked: boolean;
        }>;
        /** Unlink auth provider */
        unlinkProvider: (provider: string) => Promise<void>;
        /** Preview VK account merge (before confirming) */
        mergePreview: (accessToken: string) => Promise<{
            preview: Record<string, unknown>;
        }>;
        /** Confirm VK account merge */
        mergeConfirm: (accessToken: string) => Promise<{
            success: boolean;
            provider: string;
            vkId: string;
        }>;
    };
    catalog: {
        /**
         * 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. **Default: true** (changed 2026-05-20). Pass `false`
         *   to include canonicals with zero products — typically only
         *   admin tooling or sitemap generation wants that.
         * @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;
            /**
             * Legacy coarse-grained filter: `"topup"` → mobile donate
             * (keyhub + vendoria), `"cdkey"` → Steam keys (keyhub).
             * Still accepted for backward-compat with early storefront
             * builds.
             *
             * @deprecated Prefer `platform: "mobile_game"` instead of
             *   `type: "topup"` and `platform: "steam"` instead of
             *   `type: "cdkey"`. Canonical platforms give you facet
             *   counts via `getPlatforms()` and survive supplier
             *   reshuffles.
             */
            type?: string;
            deliveryType?: string;
            include?: string;
            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;
            /**
             * Filter by genre slug — "rpg", "action", "strategy", etc. Use
             * slugs from `getCatalogFacets().genres`. Distinct from the
             * deprecated `type` param and from `category`; only meaningful
             * when the GENRE_AXIS feature is enabled server-side.
             */
            genre?: string;
            /**
             * Display currency for the returned prices (ISO-4217). Overrides
             * the client-level default per call; the API converts `price` /
             * `priceWithoutDiscount` using live FX and stamps the resolved
             * code on each item. Omit to keep the client default (X-Currency).
             */
            currency?: SdkCurrency;
        }) => 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[]>;
        /**
         * Fetch all catalog navigation axes from GET /catalog/categories
         * in one call: the canonical category slugs (`categories`, mapped
         * from the response `data` envelope), the product-type shelves
         * (`productTypes`), and the genre chips (`genres`, empty unless
         * GENRE_AXIS is enabled server-side or the backend predates the
         * two-axis work).
         *
         * Additive companion to `getCatalogCategories()`, which still
         * returns only the `categories` array for backward-compat. Uses
         * `rawResponse` so the extra top-level keys survive the usual
         * `{ success, data }` auto-unwrap. Each axis defaults to `[]` when
         * the backend omits it, so this is safe against older APIs.
         */
        getCatalogFacets: () => Promise<CatalogFacets>;
        /**
         * Get homepage ranked games. `currency` sets the display currency of
         * each game's `minPrice` (server defaults to RUB when omitted). Pass the
         * storefront's display currency so homepage cards match the rest of the
         * catalog — otherwise a non-RUB storefront shows RUB numbers with the
         * wrong symbol.
         */
        getHomepageGames: (locale?: string, currency?: SdkCurrency) => Promise<Game[]>;
        /**
         * Get single game with categories.
         *
         * `currency` overrides the client-level default per call (sends
         * `?currency=`), so a server singleton configured for RUB can still
         * fetch a pt-br page's prices in BRL without a per-request client.
         * Mirrors how `locale` is threaded from the route segment.
         */
        getGame: (slug: string, locale?: string, currency?: SdkCurrency) => Promise<GameDetail>;
        /**
         * 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 pass `result.slug`.
         *
         *   🔴 Changed advice in 0.71.0: this used to say
         *   `result.canonicalSlug ?? result.slug`. `canonicalSlug` is now an
         *   ADDRESS — it may be absent where 0.70 sent a value, and on a tenant
         *   with per-site catalog pages it may be that tenant's own slug rather
         *   than the platform one. `slug` is the identity and is what this
         *   parameter wants. (A per-site slug still WORKS here — the endpoint
         *   resolves per-site pages — but "route on canonicalSlug, identify on
         *   slug" is the rule that keeps every call site honest.)
         * @param limit - Max recommendations (default 8). The backend
         *   caps the effective limit; very large values are trimmed
         *   server-side.
         */
        getRecommendations: (gameSlug: string, limit?: number, locale?: string) => 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>;
        /**
         * Pre-checkout delivery help (instructions, screenshots,
         * warnings) configured by the operator for a game page. The
         * endpoint returns `{ deliveryHelp: DeliveryHelp | null }` flat
         * — without the `success`/`data` envelope — so the SDK does not
         * auto-unwrap and the response shape mirrors the wire payload
         * directly. `null` means no help content is configured.
         */
        getDeliveryHelp: (gameSlug: string) => Promise<DeliveryHelpResponse>;
        /** Get categories for a game with product counts and delivery metadata */
        getCategories: (gameSlug: string, locale?: string) => Promise<Category[]>;
        /**
         * Get products for a game with optional filters.
         *
         * `filters.currency` overrides the client-level default for
         * this call only — useful for an admin tool that has a
         * Storefront in one currency but needs to preview USD pricing
         * without flipping the whole client.
         */
        getProducts: (gameSlug: string, filters?: ProductFilters & {
            currency?: SdkCurrency;
        }) => Promise<Product[]>;
        /** Get products grouped by category */
        getProductsGrouped: (gameSlug: string, locale?: string) => Promise<{
            category: Category;
            products: Product[];
        }[]>;
        /**
         * Search catalog (returns games and products, plus `superpasses`
         * hits for sites that have SuperPass search enabled — see
         * `SearchResult.superpasses`).
         */
        search: (query: string, limit?: number, locale?: string) => Promise<SearchResult>;
        /** Get search suggestions */
        searchSuggestions: (query: string, limit?: number, locale?: string) => Promise<{
            suggestions: string[];
        }>;
        /**
         * Get single product by ID.
         *
         * `locale` sends `?locale=` so the product NAME comes back localized
         * (es/pt-br/en) instead of base RU; `currency` sends `?currency=` so
         * the price is in the page's display currency. Both override the
         * client-level defaults per call — mirrors `getGame()`.
         */
        getProduct: (productId: number, locale?: string, currency?: SdkCurrency) => Promise<Product>;
        /** Get user's recently viewed games (auth required) */
        getRecentGames: (locale?: string) => Promise<Game[]>;
        /** Get user's search history — returns list of recent query strings (auth required) */
        getSearchHistory: () => Promise<string[]>;
        /** Save search query to history (auth required) */
        saveSearchHistory: (query: string) => Promise<void>;
        /** Get bundle discount rules */
        getBundleRules: () => Promise<{
            id: number;
            name: string;
            scope: string;
            minItems: number;
            discountPercent: number;
        }[]>;
        /**
         * Get active promo campaigns for the banner/news block.
         *
         * The banner's link is described by `targetType`:
         *   - `"game"` — links to a catalog game. `targetGameSlug` is the
         *     game's slug and `targetUrl` is the ready-to-use
         *     `/catalog/<slug>` path, re-derived server-side each request so
         *     it survives slug renames. Build your own locale-prefixed link
         *     from `targetGameSlug`, or use `targetUrl` directly.
         *
         *     Since 0.71.0, on a tenant with per-site catalog pages `targetUrl`
         *     already points at the tenant's OWN url, and `targetGameSiteSlug`
         *     carries that slug next to the platform `targetGameSlug`. The twin
         *     is ABSENT (not `null`) when the tenant renames nothing and when it
         *     would equal `targetGameSlug`; 🔴 never use it as an IDENTITY or a
         *     write value — link with `targetGameSiteSlug ?? targetGameSlug`,
         *     identify with `targetGameSlug`. (Unrelated to `sites.slug`.)
         *   - `"url"` — `targetUrl` is the operator-supplied destination
         *     (relative like `/referrals` or absolute `https://…`).
         *   - `"none"` — display-only banner, `targetUrl` is null.
         *
         * Note: a `"game"` target whose game was archived/deleted degrades
         * gracefully to `targetUrl: null` + `targetGameSlug: null` (still
         * `targetType: "game"`) — treat it as a non-clickable banner.
         * `targetType` is omitted only by API versions predating this field.
         */
        getPromos: () => Promise<{
            id: number;
            name: string;
            type: string;
            value: number;
            scope: string;
            bannerTitle?: string | null;
            bannerDescription?: string | null;
            bannerImageUrl?: string | null;
            bannerColor?: string | null;
            targetType?: "game" | "url" | "none";
            targetUrl?: string | null;
            targetGameSlug?: string | null;
            targetGameSiteSlug?: string;
            endsAt?: string;
        }[]>;
        /** Get all games with full metadata (categories, delivery types) */
        getGamesFull: (locale?: string) => Promise<Game[]>;
        /** Validate delivery data before checkout */
        validateDelivery: (productId: number, deliveryData: Record<string, string>) => Promise<{
            valid: boolean;
            errors?: Array<{
                field: string;
                message: string;
            }>;
        }>;
        /**
         * First-letter histogram of the visible catalog. Drives the
         * alphabetical sidebar on `/catalog` — letters that resolve to
         * zero games can be dimmed. Honours the same filters as
         * `getGames()` so the histogram matches the listing about to
         * render. Special key `"0-9"` collects names starting with a
         * digit.
         */
        getLetterCounts: (params?: {
            type?: string;
            q?: string;
            inStockOnly?: boolean;
            platform?: string;
            category?: string;
            /**
             * Filter by genre slug — mirrors `getGames({ genre })` so the
             * histogram matches the listing about to render. Distinct from
             * the deprecated `type` param and from `category`.
             */
            genre?: string;
        }) => Promise<CatalogLetterCounts>;
        /**
         * Bulk sitemap feed — one paginated response bundles each
         * game's categories + products. Replaces the N+1 loop that
         * Next.js `app/sitemap.ts` used to do; default 200 games per
         * page, hard cap 500.
         *
         * `locale` — OPT-IN ONLY, and deliberately NOT defaulted to the
         * client's `defaultLocale`.
         *
         * This endpoint is a machine feed (build-time sitemaps + YML product
         * feeds) sitting behind a proxy cache whose key does NOT include
         * Accept-Language, so the server ignores that header here and reads
         * only `?locale=`. With no param the server pins "ru" — which is the
         * LEGACY-EFFECTIVE locale of every tenant's feed today, including the
         * tenants whose default_locale is not ru (ashop-games=en,
         * giftcardi=en, kazakevich=uk). Wiring `defaultLocale` in here would
         * therefore silently flip those tenants' entire sitemap to a new
         * language on the next SDK bump. Multi-locale tenants must opt in per
         * call instead. See the LOCALE note on the handler in
         * apps/api/src/routes/catalog.ts.
         *
         * For tenants with per-site catalog pages, one game may contribute
         * several entries (main + intent pages), so a page of the feed can
         * exceed `limit` entries; `total` counts games.
         */
        getSitemapRoutes: (params?: {
            page?: number;
            limit?: number;
            locale?: SdkLocale;
        }) => Promise<CatalogSitemapRoutesResponse>;
    };
    cart: {
        /**
         * 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 a single item to the cart. `quantity` is optional and
         * defaults to `1`. The server caps per-row quantity at 100 000
         * (products may declare a tighter limit of their own).
         */
        add: (item: Omit<CartItem, "id">) => Promise<CartItem>;
        /**
         * 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 100 000 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 */
        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: {
        /**
         * Quote THIS cart against the buyer's wallet BEFORE the pay button: what
         * the BALANCE rail would charge, and how much of the wallet may actually
         * cover it once the per-order bonus cap is applied.
         *
         * **Authenticated buyers only.** It describes a wallet, so a guest gets
         * 401 and this method THROWS `GameCoreError` (status 401, code
         * `"UNAUTHORIZED"` — the SDK's 401 short-circuit never reads the body, so
         * the server's `auth_required` string does not reach you) and fires
         * `onAuthError`. Don't call it on a guest checkout page.
         *
         * **Display-only, and fail-open is the CALLER's job.** On any error,
         * render today's UI (the raw wallet), leave Pay enabled and let the 402
         * refuse — a missing preview must never disable a working checkout.
         *
         * 401 is not the only refusal: an empty cart answers 400, and a line the
         * route cannot sell or that fails body validation answers 422. Every
         * non-2xx THROWS `GameCoreError` here (this call passes no `okStatuses`),
         * so the caller contract is one `catch` covering ALL of them — render
         * without the preview rather than branching per status.
         *
         * Safe to re-run on every cart / checkbox change: the endpoint writes
         * nothing (no idempotency row, no coupon claim, no player-existence
         * check) and draws on its OWN rate-limit buckets, so it can never spend a
         * token the Pay button needs. Debounce it anyway — the budget that
         * actually refuses is ~30/min per (site, buyer) with NO cart in the key,
         * so re-asking the SAME cart costs a token exactly like a new one.
         *
         * Balance rail only: there is deliberately no `paymentMethod` argument.
         * The numbers always describe what the balance rail would charge and draw.
         *
         * ```ts
         * const q = await gc.checkout.preview(cartItems, { useBonus });
         * // «Заказ 289.59 ₽ · бонусами 27.69 ₽ · с баланса 8.89 ₽»
         * if (q.shortfall > 0) showTopupButton(q.shortfallAmount); // 0 = nothing to top up
         * ```
         */
        preview: (items: CheckoutItemInput[], opts?: CheckoutPreviewOptions) => Promise<CheckoutPreview>;
        /**
         * Create checkout (payment + orders).
         *
         * Second argument, two live forms:
         * `create(data, "key")` ≡ `create(data, { idempotencyKey: "key" })`.
         * The options form additionally carries `useBonus` — the buyer's
         * «Использовать бонусы» checkbox, which the server persists ON the
         * payment (so `completeWithBalance` deducts under the same flag; do not
         * send it there). Pass the `useBonus` a {@link CheckoutPreview} ECHOED,
         * not the checkbox state you last rendered.
         *
         * With neither form the SDK mints a RANDOM `X-Idempotency-Key` per call.
         * That is right for a human pressing Pay and WRONG for an automated
         * re-submit: the server gives a client-sent key the full 24h replay
         * window, so a repeated chain with two random keys is two payments for
         * one cart. Automation passes a key derived from the thing that must
         * happen once — see {@link CheckoutCreateOptions.idempotencyKey}.
         *
         * ⚠ A client-sent key FREEZES `useBonus` with the first payment it
         * mints: the replay is matched on (key, site) and never re-reads the
         * body, so resubmitting the same key after the buyer unticks the box
         * replays payment #1 and `completeWithBalance` spends the bonuses he
         * just withheld. A CHANGED flag requires a NEW key, never a reused one.
         *
         * **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.
         *
         * `data.ref` (referral attribution) is clamped client-side to the
         * server's accepted shape — a malformed/tampered ref cookie must
         * never be able to fail a sale, so invalid refs are silently dropped
         * rather than sent (the sale then simply proceeds unattributed).
         *
         * **Coins rail** (`paymentMethod: "coins"`, requires auth): the buyer
         * pays from the coin wallet and the response carries
         * `payment.coinAmount`/`coinCurrency` alongside the RUB `total`. Send
         * `expectedCoinAmount` (the coin price you displayed) so a re-price is
         * refused instead of silently charged. Typed failures on that rail:
         * 409 `insufficient_coins` (`details.required` / optional
         * `details.available` / `details.coinCurrency`) and 409
         * `coin_price_changed` (`details.coinAmount` / `details.coinCurrency`
         * = the current price — re-render, then retry).
         */
        create: (data: CheckoutRequest, optionsOrKey?: string | CheckoutCreateOptions) => Promise<CheckoutResponse>;
        /**
         * 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.
         *
         * Forwards the client locale as `?locale=` so the API can region-gate
         * the list (e.g. a LATAM locale is not offered Russia-only rails). When
         * no locale is set the param is omitted and the API returns the full
         * set — backward compatible.
         */
        getPaymentMethods: () => Promise<PaymentMethod[]>;
        /**
         * Get the current status of a payment plus its child orders by
         * payment code. Public endpoint — no auth required, so it can
         * power a "track your order" lookup page from a guest's email
         * receipt link. `gatewayPaymentUrl` is `null` once the payment
         * has been completed or expired.
         */
        getStatus: (code: string) => Promise<CheckoutStatus>;
        /**
         * Persist contact channel + cart snapshot BEFORE the user
         * pays. Task #24 (54-ФЗ ст.1.2) — once persisted, fiscal
         * receipts and post-payment notifications survive the user
         * closing the tab. 7-day TTL on the server-side row;
         * `expiresAt` lets the storefront drop the local copy when
         * the row is gone.
         *
         * Discriminated by `preferredChannel`: when "email" the API
         * requires `email`, when "sms" it requires `phone`. The
         * server-side validator mirrors the DB CHECK constraints, so
         * a tampered client gets a 400 rather than a half-stored row.
         */
        beginGuestSession: (data: GuestCheckoutSessionRequest) => Promise<GuestCheckoutSessionResponse>;
        /**
         * Upload the screenshot a `type:"image"` delivery field requires
         * (Vendoria image-SKUs) BEFORE checkout — multipart POST
         * /checkout/delivery-image. Put the returned `key` verbatim into the
         * cart item's `deliveryData` under the image field's id; everything
         * downstream (validate-delivery preview, checkout, fulfillment) rides
         * the existing string rails.
         *
         * Works WITHOUT authentication (guest checkout parity). Only valid
         * for products whose delivery schema actually contains an image
         * field, on sites with the `vendoria_image_upload` module enabled —
         * anything else returns a generic 404.
         *
         * Accepts JPEG / PNG / WebP up to 8MB and 25 megapixels. IMPORTANT:
         * downscale client-side before calling (canvas, ≤4096px on the long
         * edge) — phone screenshots routinely exceed the caps, and the 8MB
         * transport limit is global (larger bodies are rejected before the
         * route runs). Rate-limited to 5/min per IP.
         *
         * Errors: 404 (module off / product not eligible), 422
         * `invalid_mime` | `not_an_image` | `invalid_resolution`, 429 (rate
         * limit), 503 `upload_unavailable` (site has no supplier
         * credentials), 502 `upload_failed` (supplier-side failure — safe to
         * retry).
         */
        uploadDeliveryImage: (productId: number, file: File | Blob) => Promise<DeliveryImageUpload>;
    };
    orders: {
        /** List all orders for authenticated user */
        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).
         *
         * 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: PaymentInfo;
            orders: Order[];
            guestAccount?: boolean;
        }>;
        /** Preview cancel — check if cancellable and refund amount */
        cancelPreview: (code: string) => Promise<{
            canCancel: boolean;
            reason?: string;
            refundAmount?: number;
            refundTo?: string;
            message?: string;
        }>;
        /** Cancel a pending order */
        cancel: (code: string) => Promise<{
            status: string;
        }>;
        /**
         * Supplier-aware cancel for a PROCESSING single-item order. Server
         * enforces the single-item + live-supplier fence, IDOR (userId/siteId)
         * and the CAS double-cancel guard, then classifies by the supplier's
         * authoritative status into one of the `CustomerCancelOutcome` states
         * (cancelled / refund-pending / not-cancellable / retry / unsupported /
         * idempotent). Render by `outcome`, NOT by HTTP code.
         *
         * The server maps these outcomes onto HTTP codes: cancelled / refund-pending
         * / idempotent → 200; not-cancellable / unsupported → 409; retry → 502.
         * Those 409/502 are EXPECTED classified outcomes, not transport errors, so
         * this method tolerates them (`okStatuses: [409, 502]`) and resolves with the
         * parsed `{ success, outcome, message }` body instead of throwing — letting
         * the caller branch on `outcome` across the full discriminator. A genuinely
         * missing order (404) and 401/429 still throw a `GameCoreError`.
         *
         * For PENDING (unpaid) orders keep using `cancel` — that is a separate
         * path. This endpoint returns the RAW body `{ success, outcome, message }`
         * with NO `{ success, data }` envelope, so the SDK auto-unwrap is a
         * no-op and `outcome`/`message` are read directly. Brand-neutral by
         * contract: the response never names the fulfilling party.
         */
        requestCancel: (code: string) => Promise<CustomerCancelResult>;
        /**
         * Customer signals «я готов принять код» for ONE order item — show this
         * button when the item's `codeAffordance === "client_ready"` (and enable
         * it only while `affordanceActive` is true). Item-scoped so a multi-item
         * order never fires at a sibling item.
         *
         * The server classifies business outcomes onto HTTP codes: success 200,
         * stale 409, final 400, not_found 404, cooldown 429 (with `resetIn`
         * seconds for the countdown), error 502. ALL of those resolve with the
         * parsed `CodeReadinessResult` (`okStatuses`) instead of throwing —
         * branch on `outcome`, NOT on HTTP code. Note 429 here is a CLASSIFIED
         * cooldown outcome, not the generic rate-limit throw. Only 401 (auth)
         * and unexpected statuses still throw a `GameCoreError`.
         *
         * On success the affordance flips server-side — refetch the order to
         * re-render the buttons. Store-neutral by contract: the response never
         * names the fulfilling party.
         */
        clientReady: (code: string, itemId: number) => Promise<CodeReadinessResult>;
        /**
         * Customer asks for a FRESH code for ONE order item (prior code expired /
         * didn't work) — show this when `codeAffordance === "request_retry"`
         * (primary button, enabled while `affordanceActive`) or as the
         * `enter_code` escape while `retryAvailable` is true.
         *
         * Same classified-outcome contract as `clientReady`: every known outcome
         * (stale/final/not_found/cooldown/error) resolves with
         * `CodeReadinessResult` at its real HTTP status — branch on `outcome`,
         * and drive the retry-cooldown countdown from `resetIn` (seconds) on
         * the `cooldown` outcome.
         */
        requestRetry: (code: string, itemId: number) => Promise<CodeReadinessResult>;
        /**
         * Customer marks ONE delivered code as activated or not working — the
         * write half of `OrderItem.keys`. Item-scoped like the two actions
         * above, so a multi-item order never marks a sibling's key.
         *
         * `keyRef` MUST come from the entry you rendered
         * (`item.keys[i].keyRef`). Never build it, never send the code, never
         * send an index: the ref is a salted digest the server re-derives from
         * the codes actually delivered on this item, and matching by anything
         * else is how a mark lands on the wrong code.
         *
         * `state` is required and separately nullable — pass `"activated"`,
         * `"not_working"`, or an explicit `null` to CLEAR the mark. There is no
         * default on purpose: on the wire an absent `state` is a 422 rather
         * than a clear, and a defaulted parameter here would quietly
         * manufacture the request the server is refusing to guess at.
         *
         * Only `not_found` / `unknown_key` are classified outcomes; both arrive
         * at 404 and resolve with an {@link OrderKeyStateResult} instead of
         * throwing (`okStatuses: [404]`) — branch on `outcome`, since the
         * status cannot tell them apart. Everything else stays a throw, and
         * that asymmetry is deliberate: 422 (missing/out-of-union `state`) and
         * 400 (bad item id) are CALLER bugs, not states a buyer can be in, so
         * they must surface loudly rather than hide behind a falsy `success`.
         * 401 throws and fires `onAuthError` as everywhere else.
         *
         * 429 also throws. The endpoint is rate-limited at 30/min per user —
         * an anti-abuse bound on the staff alert a `not_working` mark raises,
         * not a buyer state: real tapping never approaches it. It is NOT in
         * `okStatuses` on purpose, matching `requestCancel`, whose own limiter
         * 429 throws too; a classified outcome would invite the UI to render a
         * throttle as if it were a normal answer.
         *
         * Idempotent: re-marking what is already marked answers a plain
         * `{ success: true }` without a write, so every tap can be sent. Staff
         * are alerted only on a real transition INTO `not_working` — a repeat
         * tap and a clear are both silent, so the UI needs no debounce for
         * their sake.
         *
         * A mark is a SIGNAL only: it never touches order status, refunds or
         * cancellation. On success the server holds the new value; refetch the
         * order (or update your local copy) to re-render the marks.
         */
        setKeyState: (code: string, itemId: number, keyRef: string, state: OrderKeyState | null) => Promise<OrderKeyStateResult>;
        /**
         * Buy ONE failed order item AGAIN in a single tap — a NEW single-item
         * order at TODAY's price, paid from balance. Show the button only while
         * the item's `reorderEligible` is true, and quote
         * `reorderCurrentPrice` (ceiled for display) next to it: both are
         * server-decided by the same eligibility core this endpoint runs, so the
         * button and the answer cannot disagree.
         *
         * `deliveryData` is the buyer's CORRECTION (e.g. a fixed `login` when
         * `cancelReasonCode === "wrong_field"`). Omit it for the common
         * "it just failed, try again" case — an absent value re-uses the source
         * item's delivery data verbatim. An explicit `{}` is NOT the same thing:
         * it is submitted and validated like any other input, so a form with
         * required fields rejects it (422).
         *
         * Resolves with a {@link ReorderItemResult}: 201 success plus the buyer
         * states 409 (`not_eligible` + frozen `reason`), 422 (`validation_error`
         * + `field`) and 503 (`reorder_unavailable`, retryable) — branch on the
         * body, never on an HTTP code.
         *
         * THROWS, deliberately: 402 insufficient balance — read it with
         * `getInsufficientBalanceDetails(err)`, the very same call checkout's
         * 402 already needs (one shared refusal body across all balance rails,
         * so there is exactly one way to render «пополните на N ₽»); 404, which
         * collapses "feature off" and "no such item" into one deliberately
         * uninformative answer; 400 (bad item id, a caller bug); 429 (5/min per
         * user+item anti-abuse, not a buyer state — same call as `requestCancel`
         * and `setKeyState`; its `retryAfter` seconds ride in `err.details`);
         * and 500, whose body is a machine token (`reorder_failed`,
         * `coupon_exhausted`, `coupon_conflict`) rather than buyer copy — the
         * order may exist, so refetch before offering the button again.
         *
         * Double-tap safe WITHOUT an idempotency key: the server decides
         * concurrent duplicates inside the insert (one partial unique index per
         * source item), so the loser reads back 409 `already_reordered` with the
         * winner's `reorder_order_code` — never a second charge.
         */
        reorderItem: (orderCode: string, itemId: number, opts?: {
            deliveryData?: Record<string, unknown>;
        }) => Promise<ReorderItemResult>;
    };
    profile: {
        /** Get user balance (permanent + bonus with details) */
        getBalance: () => Promise<UserBalance>;
        /** Get level status with progress toward next level */
        getLevelStatus: () => Promise<LevelStatus>;
        /** Get balance transaction history */
        getTransactions: (params?: {
            limit?: number;
            offset?: number;
        }) => Promise<Transaction[]>;
        /** Get user's orders */
        getOrders: () => Promise<Order[]>;
        /** Get notifications */
        getNotifications: () => Promise<Notification[]>;
        /** Get unread notification count */
        getUnreadCount: () => Promise<{
            count: number;
        }>;
        /** Mark notification as read */
        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>;
        /**
         * Upload a screenshot file directly (task 174 — multipart
         * alternative to `submitReviewProof`, which expects a URL). The
         * server stores the image, then runs the same submission
         * pipeline as the URL-based path — platform whitelist, pending
         * rate limit, and DB shape are identical. Accepts JPEG / PNG /
         * WebP up to 5MB; 413 on oversize, 422 on mime / extension /
         * content rejection, 429 if the per-user pending queue is full.
         */
        uploadReviewProof: (input: {
            file: File | Blob;
            platform: 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. Pays a flat 1₽ per claim (since 2026-06-29; the streak is
         * tracked for gamification but no longer scales the reward).
         */
        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) */
        exportData: () => Promise<Record<string, unknown>>;
        /** Get user preferences (language, currency, notifications) */
        getSettings: () => Promise<{
            language: string;
            currency: string;
            emailNotifications: boolean;
        }>;
        /** Update user preferences */
        updateSettings: (data: {
            language?: string;
            currency?: string;
            emailNotifications?: boolean;
        }) => Promise<void>;
        /** Subscribe to broadcast notifications */
        subscribeBroadcast: () => Promise<void>;
        /** Unsubscribe from broadcast notifications */
        unsubscribeBroadcast: () => Promise<void>;
        /** Get broadcast subscription status */
        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;
        }>;
        /**
         * List the current user's "please add this game" requests,
         * newest first. Status is one of `pending` / `reviewed` /
         * `completed` / `rejected` (string-typed because the server
         * may add new states without an SDK bump).
         */
        getGameRequests: () => Promise<GameRequestList>;
        /**
         * Aggregated counters for the header / sidebar — cart size,
         * unread notifications, pending review prompts, balances, and
         * whether the user has an open support thread. One round-trip
         * replaces several smaller calls; useful as a SWR pre-fetch on
         * authenticated route shells.
         */
        getSummary: () => Promise<ProfileSummary>;
    };
    /**
     * Coin Rewards — per-site branded bonus coins (daily claim, reward
     * shop, winners feed) plus the PURCHASE rail (buy coins, poll the
     * purchase, read the coin journal). Default-OFF module: on sites without
     * it these endpoints return 404. Available since gamecore-api 2026-07-22
     * (Coin Rewards v1); the purchase rail since 2026-07-27.
     *
     * Two ledgers, never mixed: coins are denominated in the site's
     * `coinCurrency` (1:1), while the RUB wallet (`gc.profile.getBalance()`)
     * is a separate platform-wide ledger. Never add or compare the two.
     */
    coins: {
        /** Wallet + claim status. Auth required. */
        getMe: () => Promise<CoinWallet>;
        /** Claim the daily coins. Atomic; 409 while on cooldown. */
        claim: () => Promise<{
            claimedAmount: number;
            newStreak: number;
            nextAvailableAt: string;
            currency: "coins";
        }>;
        /** Reward catalog with per-user availability when authenticated. */
        getRewards: () => Promise<CoinReward[]>;
        /**
         * Redeem a reward. `delivery` carries prize delivery fields (e.g.
         * `{ uid }` for PUBG UC). Idempotent when `idempotencyKey` is set.
         */
        redeem: (args: {
            rewardId: number;
            idempotencyKey?: string;
            delivery?: Record<string, string>;
        }) => Promise<CoinRedeemResult>;
        /**
         * Buy coins. `amount` is coins == units of the site's coin currency
         * (1:1, integers only) — read the accepted range from
         * `getMe().minPurchase` / `.maxPurchase`, NOT from a topup limit (those
         * are RUB). `paymentMethod` is a payment-option id from the TOPUP
         * context (`gc.topup.getPaymentMethods()`); omit it to let the server
         * pick the first rail whose invoice currency matches the coin currency.
         *
         * Invoice-first: the purchase row exists before this resolves, so
         * `gc.coins.getPurchase(code)` is pollable immediately. Coins are
         * credited by the payment webhook, never by this call — a resolved
         * promise means "an invoice was minted", not "coins were added". Send
         * the buyer to `paymentUrl`. Do NOT pass an idempotency key: the route
         * derives its own (a repeat of the same amount+method within ~120s
         * replays the same invoice instead of double-charging).
         *
         * Typed failures: 400 `amount_out_of_range` (`details.min` / `.max` /
         * `.currency`) / `coin_currency_mismatch` (the chosen rail bills another
         * currency) / `method_unavailable` (rail cannot credit coin purchases),
         * 409 `purchase_in_progress` (a peer request owns the idempotency claim
         * — retry, do not re-mint), 502 `gateway_error`, 503 `no_gateway`, 404
         * when the Coin Rewards module is off.
         * Available since gamecore-api 2026-07-27.
         */
        purchase: (args: {
            amount: number;
            paymentMethod?: string;
        }) => Promise<CoinPurchaseResult>;
        /**
         * Poll a coin purchase by its `C-…` code (gateway-return page). Owner
         * scoped: someone else's code answers 404 `purchase_not_found`, same as
         * an unknown one. Carries `coinName` so the return screen can name the
         * coin without loading the wallet.
         * Available since gamecore-api 2026-07-27.
         */
        getPurchase: (code: string) => Promise<CoinPurchaseStatus>;
        /**
         * The caller's coin journal — SETTLED movements only (the `reserve` /
         * `release` halves of a checkout hold are not returned). Offset
         * pagination, newest first; the server caps `limit` at 50 (default 20).
         *
         * These rows sum to `balance + reserved`, NOT to the spendable
         * `balance` — the two differ while a checkout hold is open. Do not
         * present the list as reconciling to the balance pill.
         * Available since gamecore-api 2026-07-27.
         */
        getTransactions: (params?: {
            limit?: number;
            offset?: number;
        }) => Promise<CoinTransaction[]>;
        /** Caller's redemption history (latest 50). */
        getRedemptions: () => Promise<CoinRedemption[]>;
        /** Public pseudonymized winners feed (may be disabled per site). */
        getWinners: () => Promise<CoinWinner[]>;
    };
    favorites: {
        /** List user's favorite products */
        list: () => Promise<Favorite[]>;
        /** Add product to favorites */
        add: (productId: number, gameId: string) => Promise<{
            id: number;
        }>;
        /** Remove product from favorites */
        remove: (productId: number) => Promise<void>;
    };
    coupons: {
        /** Apply coupon code (sets active coupon for checkout) */
        apply: (code: string) => Promise<CouponResult>;
        /** Remove active coupon */
        remove: () => Promise<void>;
        /** Validate coupon without applying */
        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 */
        getStats: () => Promise<ReferralStats>;
        /** List user's referral links */
        getLinks: () => Promise<ReferralLink[]>;
        /** Create new referral link */
        createLink: (data?: {
            label?: string;
            slug?: string;
            targetUrl?: string;
        }) => Promise<ReferralLink>;
        /** Update referral link */
        updateLink: (id: number, data: {
            label?: string;
            slug?: string;
            targetUrl?: string;
        }) => Promise<void>;
        /** Delete referral link */
        deleteLink: (id: number) => Promise<void>;
        /** Get stats for a specific link */
        getLinkStats: (id: number) => Promise<{
            link: ReferralLink;
            commissions: ReferralCommission[];
            totalCommission: number;
        }>;
        /** 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>;
        /**
         * Transfer all eligible pending referral commissions to the
         * user's permanent balance. Returns the total transferred amount,
         * how many commissions were moved, and the user's new permanent
         * balance.
         */
        transferToBalance: () => Promise<ReferralTransferResult>;
        /**
         * Count a click on a referral link (code or slug). Public — call it
         * server-side from the storefront's /ref/[code] handler
         * (fire-and-forget). Unknown refs resolve successfully (no existence
         * oracle), so the storefront never has to branch on the outcome —
         * just await (or ignore) the promise and redirect.
         *
         * True beacon semantics: this method NEVER rejects. A click counter
         * must not be able to break a landing redirect, so refs that can't
         * pass the server's validation (shorter than 2 chars after stripping
         * to [A-Za-z0-9_-], longer than 128) are dropped client-side, and
         * transport/HTTP errors (429 during promo bursts, 5xx) are swallowed.
         */
        trackClick: (ref: string) => Promise<void>;
    };
    reviews: {
        /** Get public reviews (paginated) */
        listPublic: (params?: {
            gameSlug?: string;
            productId?: number;
            limit?: number;
            offset?: number;
        }) => Promise<PaginatedResponse<Review>>;
        /** Get review stats (average rating, total count) */
        getStats: (gameSlug?: string) => Promise<ReviewStats>;
        /** Get random reviews for homepage */
        getRandom: (limit?: number) => Promise<Review[]>;
        /** Get user's own reviews */
        getMine: () => Promise<Review[]>;
        /** Get orders eligible for review */
        getPending: () => Promise<Order[]>;
        /**
         * Submit a review for a completed order. Two call forms, both live:
         *
         * ```ts
         * gc.reviews.create(orderId, 5, "Great service!");           // ≤ 0.61.0
         * gc.reviews.create(orderId, { rating: 5, deliveryRating: 4 }); // 0.62.0+
         * ```
         *
         * The positional form builds the exact same body it always did — same
         * keys, same order — so an existing caller is byte-for-byte unchanged on
         * the wire. The options form is the only way to send the optional
         * per-dimension ratings (`deliveryRating`, `supportRating`).
         *
         * The two forms do NOT mix: `create(id, { rating: 5 }, "text")` is a
         * compile error rather than a silently dropped review text — when
         * migrating a positional call, move the text into `options.text`.
         *
         * A dimension the buyer skipped is OMITTED from the body, never sent as
         * `null`: the endpoint validates them as optional integers 1–5, so a
         * literal `null` is a 422 rather than "no answer".
         *
         * 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: (...args: [orderId: number, rating: number, text?: string] | [orderId: number, options: ReviewCreateOptions]) => Promise<ReviewCreateResult>;
        /**
         * Submit a review as a GUEST — a buyer with no account, holding the
         * signed `rt=` token from the review-request email. Public endpoint:
         * the token IS the authorization, so there is no session to establish.
         *
         * ```ts
         * const rt = new URLSearchParams(location.search).get("rt");
         * if (rt) await gc.reviews.createGuest(rt, { rating: 5, authorName: "Иван" });
         * ```
         *
         * The token is single-purpose, tenant-bound and expires after 30 days;
         * re-using one after the order already has a review is harmless and
         * answers 400 (one review per order, whoever leaves it).
         *
         * No bonus is granted — there is no balance to credit — so the result's
         * `bonus` is always absent or `null`; do not render a bonus toast off it.
         */
        createGuest: (token: string, options: ReviewGuestCreateOptions) => Promise<ReviewGuestCreateResult>;
    };
    topup: {
        /**
         * Get available topup payment methods.
         *
         * Forwards the client locale as `?locale=` for region gating (same as
         * checkout.getPaymentMethods); omitted when no locale is set.
         */
        getPaymentMethods: () => Promise<TopupMethod[]>;
        /**
         * Create topup (returns payment URL for redirect).
         *
         * `opts.idempotencyKey` sends `X-Idempotency-Key`; omit it and the server
         * derives its own SHORT-TTL key from user+amount+method, which collapses
         * a double-click but also collapses a deliberate repeat of the same
         * amount minutes later. Automation that means "invoice this gap NOW"
         * (the checkout top-up chain) must therefore pass a FRESH unique key per
         * deliberate attempt — otherwise the derived-key window can report old
         * money as new.
         *
         * An EMPTY STRING counts as omitted: the header is set only for a truthy
         * key, so `{ idempotencyKey: "" }` sends nothing and the server derives.
         * That truthy gate also shields a server sharp edge — the route reads the
         * header with `??`, so an empty one would be KEPT as the literal key `""`
         * (while still being classified as derived), i.e. a single site-wide key
         * every such caller would collide on.
         */
        create: (amount: number, paymentMethod?: string, opts?: TopupCreateOptions) => Promise<TopupResponse>;
        /** Get topup status by code */
        getStatus: (code: string) => Promise<TopupStatus>;
    };
    giftCards: {
        /**
         * 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;
        }>;
        /** Check gift card status */
        check: (code: string) => Promise<GiftCard>;
        /** Get user's purchased gift cards */
        getMine: () => Promise<GiftCard[]>;
    };
    announcements: {
        /**
         * List published announcements.
         *
         * `locale` sends `?locale=` — forwarded for forward-compat; the CMS
         * stores a single language today (see backend per-locale content
         * model), so the param is currently a no-op server-side but lets the
         * storefront pass the page locale without a future SDK bump.
         */
        list: (limit?: number, locale?: string) => Promise<Announcement[]>;
        /** Get single announcement */
        get: (id: number, locale?: string) => Promise<Announcement>;
    };
    sse: {
        /** Connect to authenticated notification stream. Returns EventSource. */
        connectEvents: () => EventSource;
        /** Track order status by code (no auth required). Returns EventSource. */
        trackOrder: (orderCode: string) => EventSource;
    };
    analytics: {
        /** Record game page view (for ranking) */
        recordView: (gameId: string) => Promise<void>;
    };
    marketing: {
        /**
         * Fire the marketing visit beacon (POST /marketing/visit) for a
         * first-page landing. Call it ONCE per landing, server-side through
         * the storefront's same-origin proxy (the endpoint needs X-Api-Key
         * and the ORIGINAL browser User-Agent forwarded).
         *
         * Persist the returned `visitId`: the FIRST one ever seen becomes
         * `mvFirst`, the latest one `mvLast` — pass both to the auth methods
         * and `checkout.create` so registrations/orders get attributed.
         *
         * Fire-and-forget contract: this NEVER throws. A rate-limited,
         * failed, or bot-filtered beacon resolves to `{}` (no visitId) — a
         * marketing counter must never break a page render.
         */
        trackVisit: (body: MarketingTrackVisitRequest) => Promise<MarketingTrackVisitResult>;
    };
    seo: {
        /** Get SEO content for a page */
        getContent: (pageType: string, entityId: string | number, locale?: string) => Promise<Record<string, unknown>>;
        /** Get schema.org JSON-LD for a page */
        getSchema: (pageType: string, entityId: string | number) => Promise<Record<string, unknown>>;
    };
    /**
     * Public Roblox SuperPass catalog. Three GETs — list all games,
     * fetch one with passes + RUB prices + related games, and
     * verify a Roblox username before checkout. Verification is
     * rate-limited (10 req/min) and surfaces failures as
     * `GameCoreError(404)`.
     */
    superpasses: {
        /** All active SuperPass games sorted by superpass-order volume. */
        list: () => Promise<SuperpassGameSummary[]>;
        /**
         * Single game with all available passes (RUB-priced via the
         * live FX + global markup), plus up to 6 related games sharing
         * at least one tag.
         *
         * `locale` sends `?locale=` so the returned `seo` block resolves
         * against the page's display locale instead of the base RU copy —
         * needed so the storefront's per-locale cache key gets per-locale
         * SEO text.
         */
        get: (slug: string, locale?: string) => Promise<SuperpassGameResponse>;
        /**
         * Verify a Roblox username before allowing checkout for a
         * SuperPass. Server rejects non-alphanumeric usernames (only
         * `[A-Za-z0-9_]{3,20}`) and rate-limits to 10 req/min per IP.
         */
        verifyUser: (username: string) => Promise<SuperpassUserVerification>;
    };
    /**
     * Custom pack requests — «Собери свой пак»: the buyer picks a
     * Vendoria-backed game, uploads a screenshot of the in-game pack they
     * want, and submits a request; the vendor prices it manually, the buyer
     * gets a quote with a payment deadline and pays like a normal checkout.
     *
     * Flow: `listGames()` → `uploadImage()` → `create()` → wait for
     * `status: "priced"` (in-app / TG / email notification carries a
     * deep-link) → `pay()` → redirect to `paymentUrl` → track via
     * `orders.get(orderCode)` / SSE.
     *
     * Requirements:
     *   - the `vendoria_pack_requests` site module must be enabled —
     *     disabled tenants answer a generic 404 on EVERY endpoint;
     *   - ALL endpoints require an authenticated user (guests get a CTA to
     *     log in first) — auth is the notification + refund channel;
     *   - rate limits: upload 5/min/IP, create 3/hour/user plus durable
     *     caps (3 active requests per user, 8 per site → 429 `queue_full`).
     */
    packRequests: {
        /**
         * Vendoria games available for a pack request on this site (a game
         * qualifies when the site sells at least one Vendoria product for
         * it). Server-cached ~5 min. `id` is the supplier game id — feed it
         * back to `uploadImage()` / `create()` verbatim.
         */
        listGames: () => Promise<PackRequestGame[]>;
        /** The authenticated buyer's own pack requests, newest first. */
        list: () => Promise<PackRequest[]>;
        /**
         * One pack request by id (own requests only — a foreign or unknown
         * id answers 404). Poll this on the request page: `status`,
         * `priceRub`, `forms` and `payDeadline` appear once the vendor
         * prices the request.
         */
        get: (id: number) => Promise<PackRequest>;
        /**
         * Upload the pack screenshot (step BEFORE `create()`). Sends
         * multipart to the API which forwards the file to the vendor under
         * the site's own shop token; returns the storage `key` plus a
         * signed `grant` — pass BOTH to `create()` unmodified (the grant is
         * an HMAC binding of site + game + key and expires server-side).
         *
         * Accepted: JPEG / PNG / WebP, ≤8MB, ≤25MP. Rejections are typed:
         * 422 `invalid_mime` / `not_an_image` / `invalid_resolution`, 429
         * on the shared per-site daily quota.
         */
        uploadImage: (supplierGameId: number, file: File | Blob) => Promise<{
            key: string;
            grant: string;
        }>;
        /**
         * Create a pack request from an uploaded screenshot. `imageKey` +
         * `imageGrant` come from `uploadImage()` verbatim; `comment` is the
         * buyer's free-form note to the vendor; `locale` localizes the
         * later notification fan-out. Retry safety is SERVER-side (the
         * endpoint reads no idempotency header): the image-key ledger claim
         * allows at most one request per uploaded screenshot — a retry
         * whose first attempt actually landed answers 409 `image_conflict`.
         *
         * Typed failures: 429 `queue_full` (durable caps / vendor queue),
         * 400 `image_not_verified` / `image_not_found`, 409
         * `image_conflict` (key already claimed by another request), 503
         * `temporarily_unavailable`.
         */
        create: (data: {
            supplierGameId: number;
            imageKey: string;
            imageGrant: string;
            comment?: string;
            locale?: string;
        }) => Promise<PackRequest>;
        /**
         * Pay for a vendor-priced request: pick one of `PackRequest.forms`
         * (`formId`), fill its fields (`deliveryData`: field id → value)
         * and choose a payment method id from
         * `checkout.getPaymentMethods()`. Mints a REAL payment + order and
         * returns the gateway URL (`null` for balance payments — those
         * complete instantly). Idempotency is fully SERVER-side (the
         * endpoint reads no idempotency header): a derived per-request key
         * plus a status CAS guarantee ONE live invoice per pack — repeating
         * the call while the invoice is pending replays the same
         * `paymentUrl` instead of double-charging.
         *
         * Typed failures: 410 `deadline_passed`, 400 `invalid_form` /
         * `invalid_delivery_data` (`details.field` names the bad input) /
         * `amount_below_min` / `amount_above_max` (`details.limit`) /
         * `insufficient_balance`, 409 `already_paid` / `payment_in_flight`
         * / `concurrent_request`.
         */
        pay: (id: number, data: {
            formId: number;
            deliveryData: Record<string, string | number>;
            paymentMethod: string;
        }) => Promise<PackRequestPayResponse>;
        /**
         * Cancel an own request while it is still `submitted` or `priced`
         * (also cancels it vendor-side, freeing the queue slot). Once a
         * payment is completed the request is no longer cancellable — 400
         * `invalid_status` / 409 `conflict`.
         */
        cancel: (id: number) => Promise<{
            success: boolean;
        }>;
    };
    /**
     * Customer support — two distinct flows under one namespace:
     *
     *   1. **Authenticated in-app chat** (`getThread`, `getMessages`,
     *      `sendMessage`, `uploadImage`, `callAdmin`) — persistent
     *      thread per (user × site). Requires the `chat` site module;
     *      404 if disabled. Image attachments go through
     *      `uploadImage()` then attach the returned URL on the next
     *      `sendMessage()` call.
     *
     *   2. **Public guest form** (`submitPublic`) — pre-login support
     *      submission landing in `public_support_tickets`. Honeypot +
     *      per-IP rate limit (3 / 10 min). Requires the `support` site
     *      module. Returns an opaque `ticketCode` (`T-…`) the guest
     *      can quote later.
     */
    support: {
        /**
         * Get or create the authenticated user's support thread. The
         * first call provisions the thread; subsequent calls return
         * the same row with a fresh `unreadCount`.
         */
        getThread: () => Promise<SupportThread>;
        /**
         * Cursor-paginated messages in the user's support thread.
         * `before` is the message id to paginate before — pass the
         * smallest id from the previous batch. The server marks the
         * thread as user-read on every fetch, so polling this endpoint
         * doubles as a read receipt.
         */
        getMessages: (params?: {
            limit?: number;
            before?: number;
        }) => Promise<SupportMessage[]>;
        /**
         * Send a text + optional image message. Pre-upload the image
         * via `uploadImage()` and pass the resulting URL here.
         */
        sendMessage: (data: {
            body: string;
            imageUrl?: string;
        }) => Promise<SupportMessage>;
        /**
         * Upload an image attachment for the support thread. Returns
         * the storage URL — pass it as `imageUrl` to the next
         * `sendMessage()` call. Rate-limited per user.
         */
        uploadImage: (file: File | Blob) => Promise<{
            url: string;
        }>;
        /**
         * Manual handoff — flags the thread for the operator and
         * pauses any AI auto-reply window. Idempotent: a second call
         * while still paused returns the same `aiPausedUntil` without
         * extending it. Server rate-limits to prevent spam.
         */
        callAdmin: () => Promise<SupportCallAdminResult>;
        /**
         * Submit a guest support ticket (pre-login). Tenant must have
         * the `support` module enabled. Per-IP rate limit (3 / 10 min)
         * + honeypot anti-bot. Send EXACTLY one of `email`/`telegram`
         * — both or neither returns 400.
         */
        submitPublic: (data: PublicSupportRequest) => Promise<PublicSupportResponse>;
    };
}