@gamecore-api/sdk 0.2.0

package/README.md

@@ -0,0 +1,343 @@
+# @gamecore/sdk
+
+TypeScript SDK for GameCore API — zero external dependencies, browser-safe.
+
+## Install
+
+```bash
+npm install @gamecore/sdk
+```
+
+## Quick Start
+
+```typescript
+import { GameCoreClient } from "@gamecore/sdk";
+
+const gc = new GameCoreClient({
+  apiKey: "gc_live_YOUR_KEY",
+  baseUrl: "https://api.gamecore-api.tech",
+  onAuthError: () => window.location.href = "/login",
+});
+
+// Browse catalog
+const games = await gc.catalog.getGames();
+const game = await gc.catalog.getGame("honkai-star-rail");
+const products = await gc.catalog.getProducts("honkai-star-rail");
+
+// Search
+const results = await gc.catalog.search("roblox");
+```
+
+## Authentication
+
+### Telegram Auth Flow
+
+```typescript
+// 1. Start auth → get bot link
+const { token, botLink } = await gc.auth.initTelegram();
+
+// 2. Open Telegram bot (user clicks "Start")
+window.open(botLink, "_blank");
+
+// 3. Poll until user authenticates
+const user = await gc.auth.pollTelegramStatus(token);
+console.log("Logged in:", user.firstName);
+```
+
+### VK Auth
+
+```typescript
+const { user } = await gc.auth.verifyVk(vkAccessToken);
+```
+
+### Session
+
+```typescript
+const me = await gc.auth.getMe();       // Get current user
+await gc.auth.logout();                   // Clear session
+const identities = await gc.auth.getIdentities(); // Linked providers
+```
+
+## Catalog
+
+```typescript
+// All games
+const games = await gc.catalog.getGames({ type: "game" });
+
+// Homepage ranked games
+const homepage = await gc.catalog.getHomepageGames();
+
+// Single game with categories
+const game = await gc.catalog.getGame("genshin-impact");
+
+// Products (optionally filtered by category)
+const products = await gc.catalog.getProducts("genshin-impact", "crystals");
+
+// Products grouped by category
+const grouped = await gc.catalog.getProductsGrouped("genshin-impact");
+
+// Search (returns games + products)
+const { games, products } = await gc.catalog.search("roblox");
+
+// Search suggestions
+const { suggestions } = await gc.catalog.searchSuggestions("rob");
+```
+
+## Cart & Checkout
+
+```typescript
+// Cart
+const items = await gc.cart.get();
+await gc.cart.add({ productId: 10, gameId: "roblox", gameName: "Roblox", productName: "800 Robux", price: 799, deliveryData: { username: "player123" } });
+await gc.cart.remove(itemId);
+await gc.cart.clear();
+
+// Checkout (auto-generates idempotency key)
+const checkout = await gc.checkout.create({
+  items: [{ productId: 10, deliveryData: { username: "player123" } }],
+  paymentMethod: "antilopay",
+});
+
+// Redirect to payment page
+if (checkout.payment?.paymentUrl) {
+  window.location.href = checkout.payment.paymentUrl;
+}
+
+// Or pay with balance
+await gc.checkout.completeWithBalance(checkout.payment.code);
+```
+
+## Orders
+
+```typescript
+const orders = await gc.orders.list();
+const order = await gc.orders.get("ORD-A7X9K2");
+await gc.orders.cancel("ORD-A7X9K2");
+
+// Track order in real-time (SSE)
+const source = gc.sse.trackOrder("ORD-A7X9K2");
+source.addEventListener("order_status", (e) => {
+  const data = JSON.parse(e.data);
+  console.log("Status:", data.status, "Items:", data.items);
+});
+```
+
+## Profile
+
+```typescript
+// Balance (permanent + bonus with expiration details)
+const balance = await gc.profile.getBalance();
+// { permanent: 500, bonus: 100, total: 600, bonusDetails: [{ remaining: 100, expiresAt: "..." }] }
+
+// Level status with progress
+const level = await gc.profile.getLevelStatus();
+// { currentLevel: 3, currentDiscount: 5, nextLevel: 4, requirements: { spending: { current: 5000, required: 10000 } } }
+
+// Transaction history
+const transactions = await gc.profile.getTransactions({ limit: 20 });
+
+// Orders
+const orders = await gc.profile.getOrders();
+
+// Notifications
+const notifications = await gc.profile.getNotifications();
+const { count } = await gc.profile.getUnreadCount();
+await gc.profile.markRead(notificationId);
+await gc.profile.markAllRead();
+```
+
+## Favorites
+
+```typescript
+const favorites = await gc.favorites.list();
+await gc.favorites.add(productId, "genshin-impact"); // gameId as slug string
+await gc.favorites.remove(productId);
+```
+
+## Reviews
+
+```typescript
+// Public reviews (paginated)
+const { data, pagination } = await gc.reviews.listPublic({ limit: 10 });
+
+// Stats
+const stats = await gc.reviews.getStats("genshin-impact");
+// { averageRating: 4.8, totalReviews: 156 }
+
+// Random reviews (for homepage)
+const random = await gc.reviews.getRandom(5);
+
+// Submit review (authenticated)
+const review = await gc.reviews.create(orderId, 5, "Great service!");
+
+// Orders waiting for review
+const pending = await gc.reviews.getPending();
+```
+
+## Coupons & Gift Cards
+
+```typescript
+// Apply coupon
+const result = await gc.coupons.apply("WELCOME10");
+// { type: "bonus_balance", value: 10, code: "WELCOME10", bonusAmount: 100 }
+
+await gc.coupons.remove();
+const active = await gc.coupons.getActive();
+
+// Gift cards
+const card = await gc.giftCards.purchase(5); // amountUsd
+await gc.giftCards.redeem("GC-XXXX-XXXX-XXXX");
+```
+
+## Referrals
+
+```typescript
+const stats = await gc.referrals.getStats();
+const links = await gc.referrals.getLinks();
+const link = await gc.referrals.createLink({ label: "YouTube", slug: "my-channel" });
+await gc.referrals.updateLink(link.id, { label: "Updated" });
+const linkStats = await gc.referrals.getLinkStats(link.id);
+const commissions = await gc.referrals.getCommissions();
+```
+
+## Balance Top-up
+
+```typescript
+const methods = await gc.topup.getPaymentMethods();
+const topup = await gc.topup.create(500, "lava");
+// Redirect to topup.paymentUrl
+const status = await gc.topup.getStatus(topup.code);
+```
+
+## SSE (Real-time Events)
+
+```typescript
+// Authenticated notification stream
+const events = gc.sse.connectEvents();
+events.addEventListener("notification", (e) => {
+  const { type, data } = JSON.parse(e.data);
+  // type: "order_completed", "balance_updated", "level_up", etc.
+});
+
+// Order tracking (no auth, uses order code)
+const tracker = gc.sse.trackOrder("ORD-A7X9K2");
+```
+
+## SEO
+
+```typescript
+// entityId is numeric (canonical game ID), not slug
+const seo = await gc.seo.getContent("game", 1076, "ru");
+// Schema is available for "product" page type
+const schema = await gc.seo.getSchema("product", 42);
+```
+
+## Webhook Verification (Server-side)
+
+```typescript
+// Import from server entrypoint (uses node:crypto)
+import { verifyWebhookSignature, parseWebhookPayload } from "@gamecore/sdk/server";
+
+const isValid = verifyWebhookSignature(
+  requestBody,
+  request.headers["x-webhook-signature"],
+  WEBHOOK_SECRET,
+);
+
+if (isValid) {
+  const payload = parseWebhookPayload(requestBody);
+  console.log(payload.event, payload.data);
+}
+```
+
+## Utilities
+
+```typescript
+import { convertPrice, formatPrice, generateIdempotencyKey } from "@gamecore/sdk";
+
+const rub = convertPrice(1.99, 92.5);       // 184.08
+const formatted = formatPrice(rub, "RUB");   // "184 ₽"
+const key = generateIdempotencyKey();         // UUID v4
+```
+
+## Next.js App Router Examples
+
+### Server Component (SSR catalog)
+
+```typescript
+// app/catalog/page.tsx
+import { GameCoreClient } from "@gamecore/sdk";
+
+const gc = new GameCoreClient({
+  apiKey: process.env.GAMECORE_API_KEY!,
+  baseUrl: process.env.GAMECORE_API_URL!,
+});
+
+export default async function CatalogPage() {
+  const games = await gc.catalog.getGames();
+  return <GameGrid games={games} />;
+}
+```
+
+### Client Component (cart)
+
+```typescript
+"use client";
+import { useEffect, useState } from "react";
+import { gc } from "@/lib/gamecore-browser";
+
+export function CartWidget() {
+  const [items, setItems] = useState([]);
+  useEffect(() => { gc.cart.get().then(setItems); }, []);
+  return <span>{items.length} items</span>;
+}
+```
+
+### Route Handler (webhook)
+
+```typescript
+// app/api/webhooks/gamecore/route.ts
+import { verifyWebhookSignature, parseWebhookPayload } from "@gamecore/sdk/server";
+
+export async function POST(req: Request) {
+  const body = await req.text();
+  const sig = req.headers.get("x-webhook-signature") || "";
+
+  if (!verifyWebhookSignature(body, sig, process.env.WEBHOOK_SECRET!)) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  const payload = parseWebhookPayload(body);
+  // Handle event...
+  return new Response("OK");
+}
+```
+
+## API Namespaces
+
+| Namespace | Methods |
+|-----------|---------|
+| `gc.site` | getConfig, getRates, getLegal |
+| `gc.auth` | initTelegram, pollTelegramStatus, verifyVk, getMe, logout, getIdentities, linkVk, unlinkProvider |
+| `gc.catalog` | getGames, getHomepageGames, getGame, getProducts, getProductsGrouped, search, searchSuggestions, getProduct |
+| `gc.cart` | get, add, sync, remove, clear |
+| `gc.checkout` | create, completeWithBalance, getPaymentMethods |
+| `gc.orders` | list, get, getByPayment, cancel |
+| `gc.profile` | getBalance, getLevelStatus, getTransactions, getOrders, getNotifications, getUnreadCount, markRead, markAllRead |
+| `gc.favorites` | list, add, remove |
+| `gc.coupons` | apply, remove, validate, getActive |
+| `gc.referrals` | getStats, getLinks, createLink, updateLink, deleteLink, getLinkStats, getCommissions |
+| `gc.reviews` | listPublic, getStats, getRandom, getMine, getPending, create |
+| `gc.topup` | getPaymentMethods, create, getStatus |
+| `gc.giftCards` | purchase, redeem, check, getMine |
+| `gc.announcements` | list, get |
+| `gc.analytics` | recordView |
+| `gc.seo` | getContent, getSchema |
+| `gc.sse` | connectEvents, trackOrder |
+
+## Browser vs Server
+
+| Import | Environment | Includes |
+|--------|-------------|----------|
+| `@gamecore/sdk` | Browser + Node | Client, types, utilities |
+| `@gamecore/sdk/server` | Node only | Webhook verification (uses node:crypto) |

package/dist/client.d.ts

@@ -0,0 +1,251 @@
+import type { TelegramInitResponse, User, SiteConfig, ExchangeRates, LegalDocument, Game, GameDetail, Product, SearchResult, Category, CartItem, CheckoutRequest, CheckoutResponse, Order, UserBalance, LevelStatus, Transaction, Notification, Favorite, Review, ReviewStats, CouponResult, ReferralStats, ReferralLink, ReferralCommission, TopupMethod, TopupResponse, TopupStatus, GiftCard, Announcement, PaginatedResponse } from "./types";
+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;
+}
+export declare class GameCoreClient {
+    private apiKey;
+    private baseUrl;
+    private onAuthError?;
+    constructor(options: GameCoreOptions);
+    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>;
+    };
+    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>;
+        /** Verify VK access token and login/register */
+        verifyVk: (accessToken: string, ref?: string) => Promise<{
+            status: string;
+            user: User;
+        }>;
+        /** Get current authenticated user */
+        getMe: () => Promise<User>;
+        /** Logout and clear session */
+        logout: () => Promise<void>;
+        /** List linked auth providers (Telegram, VK) */
+        getIdentities: () => Promise<{
+            providers: Array<{
+                provider: string;
+                linked: boolean;
+                displayName: string;
+            }>;
+        }>;
+        /** Link VK account to current user */
+        linkVk: (accessToken: string) => Promise<void>;
+        /** Unlink auth provider */
+        unlinkProvider: (provider: string) => Promise<void>;
+    };
+    catalog: {
+        /** Get all games with product counts */
+        getGames: (params?: {
+            locale?: string;
+            type?: string;
+        }) => Promise<Game[]>;
+        /** Get homepage ranked games */
+        getHomepageGames: () => Promise<Game[]>;
+        /** Get single game with categories */
+        getGame: (slug: string, locale?: string) => Promise<GameDetail>;
+        /** Get products for a game */
+        getProducts: (gameSlug: string, categorySlug?: string) => Promise<Product[]>;
+        /** Get products grouped by category */
+        getProductsGrouped: (gameSlug: string) => Promise<{
+            category: Category;
+            products: Product[];
+        }[]>;
+        /** Search catalog (returns both games and products) */
+        search: (query: string, limit?: number) => Promise<SearchResult>;
+        /** Get search suggestions */
+        searchSuggestions: (query: string, limit?: number) => Promise<{
+            suggestions: string[];
+        }>;
+        /** Get single product by ID */
+        getProduct: (productId: number) => Promise<Product>;
+    };
+    cart: {
+        /** Get cart items for authenticated user */
+        get: () => Promise<CartItem[]>;
+        /** Add single item to cart */
+        add: (item: Omit<CartItem, "id">) => Promise<CartItem>;
+        /** Sync localStorage cart to server (replaces server cart) */
+        sync: (items: Omit<CartItem, "id">[]) => Promise<CartItem[]>;
+        /** Remove item from cart by ID */
+        remove: (id: number) => Promise<void>;
+        /** Clear all cart items */
+        clear: () => Promise<void>;
+    };
+    checkout: {
+        /** Create checkout (payment + orders). Auto-generates idempotency key. */
+        create: (data: CheckoutRequest, idempotencyKey?: string) => Promise<CheckoutResponse>;
+        /** Complete payment with balance (no external gateway) */
+        completeWithBalance: (paymentCode: string) => Promise<{
+            success: boolean;
+        }>;
+        /** Get available payment methods for checkout */
+        getPaymentMethods: () => Promise<{
+            type: string;
+            label: string;
+            description?: string;
+            feePercent?: number;
+            gatewayType?: string;
+        }[]>;
+    };
+    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) */
+        getByPayment: (paymentCode: string) => Promise<{
+            payment: unknown;
+            orders: Order[];
+        }>;
+        /** Cancel a pending order */
+        cancel: (code: string) => Promise<{
+            status: string;
+        }>;
+    };
+    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>;
+    };
+    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>;
+    };
+    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[]>;
+    };
+    reviews: {
+        /** Get public reviews (paginated) */
+        listPublic: (params?: {
+            gameSlug?: string;
+            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 review for a completed order */
+        create: (orderId: number, rating: number, text?: string) => Promise<Review>;
+    };
+    topup: {
+        /** Get available topup payment methods */
+        getPaymentMethods: () => Promise<TopupMethod[]>;
+        /** Create topup (returns payment URL for redirect) */
+        create: (amount: number, paymentMethod?: string) => Promise<TopupResponse>;
+        /** Get topup status by code */
+        getStatus: (code: string) => Promise<TopupStatus>;
+    };
+    giftCards: {
+        /** Purchase a gift card (amount in USD) */
+        purchase: (amountUsd: number) => 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 */
+        list: (limit?: number) => Promise<Announcement[]>;
+        /** Get single announcement */
+        get: (id: number) => 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>;
+    };
+    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>>;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { GameCoreClient } from "./client";
+export type { GameCoreOptions } from "./client";
+export * from "./types";
+export { convertPrice, formatPrice, generateIdempotencyKey } from "./utils";

package/dist/index.js

@@ -0,0 +1,245 @@
+// src/types.ts
+class GameCoreError extends Error {
+  status;
+  code;
+  constructor(message, status, code) {
+    super(message);
+    this.name = "GameCoreError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+// src/utils.ts
+function convertPrice(priceUsd, rate) {
+  return Math.round(priceUsd * rate * 100) / 100;
+}
+function formatPrice(amount, currency = "RUB") {
+  if (currency === "RUB") {
+    const formatted = Math.round(amount).toString().replace(/\B(?=(\d{3})+(?!\d))/g, " ");
+    return `${formatted} ₽`;
+  }
+  if (currency === "USD") {
+    return `$${amount.toFixed(2)}`;
+  }
+  if (currency === "EUR") {
+    return `€${amount.toFixed(2)}`;
+  }
+  return `${amount.toFixed(2)} ${currency}`;
+}
+function generateIdempotencyKey() {
+  return crypto.randomUUID();
+}
+
+// src/client.ts
+class GameCoreClient {
+  apiKey;
+  baseUrl;
+  onAuthError;
+  constructor(options) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.onAuthError = options.onAuthError;
+  }
+  async request(method, path, body, options) {
+    const headers = {
+      "X-Api-Key": this.apiKey,
+      "Content-Type": "application/json"
+    };
+    if (options?.idempotencyKey) {
+      headers["X-Idempotency-Key"] = options.idempotencyKey;
+    }
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+      credentials: "include"
+    });
+    if (res.status === 401) {
+      this.onAuthError?.();
+      throw new GameCoreError("Unauthorized", 401, "UNAUTHORIZED");
+    }
+    if (res.status === 429) {
+      throw new GameCoreError("Rate limit exceeded", 429, "RATE_LIMITED");
+    }
+    if (!res.ok) {
+      const data = await res.json().catch(() => ({}));
+      throw new GameCoreError(data.error || `HTTP ${res.status}`, res.status, data.code);
+    }
+    const json = await res.json();
+    if (!options?.rawResponse && json && typeof json === "object" && "success" in json && "data" in json) {
+      return json.data;
+    }
+    return json;
+  }
+  site = {
+    getConfig: () => this.request("GET", "/site/config"),
+    getRates: () => this.request("GET", "/rates"),
+    getLegal: (type, locale) => this.request("GET", `/legal/${type}${locale ? `?locale=${locale}` : ""}`)
+  };
+  auth = {
+    initTelegram: () => this.request("POST", "/auth/telegram/init"),
+    pollTelegramStatus: (token, intervalMs = 2000) => new Promise((resolve, reject) => {
+      const poll = setInterval(async () => {
+        try {
+          const res = await this.request("GET", `/auth/telegram/status/${token}`, undefined, { rawResponse: true });
+          if (res.status === "authenticated" && res.user) {
+            clearInterval(poll);
+            resolve(res.user);
+          } else if (res.status === "expired" || res.status === "used") {
+            clearInterval(poll);
+            reject(new GameCoreError("Auth token expired", 410, "TOKEN_EXPIRED"));
+          }
+        } catch (err) {
+          clearInterval(poll);
+          reject(err);
+        }
+      }, intervalMs);
+    }),
+    verifyVk: (accessToken, ref) => this.request("POST", "/auth/vk/verify", { accessToken, ref }, { rawResponse: true }),
+    getMe: () => this.request("GET", "/auth/me", undefined, { rawResponse: true }),
+    logout: () => this.request("POST", "/auth/logout"),
+    getIdentities: () => this.request("GET", "/auth/identities", undefined, { rawResponse: true }),
+    linkVk: (accessToken) => this.request("POST", "/auth/link/vk", { accessToken }),
+    unlinkProvider: (provider) => this.request("POST", `/auth/unlink/${provider}`)
+  };
+  catalog = {
+    getGames: (params) => {
+      const qs = new URLSearchParams;
+      if (params?.locale)
+        qs.set("locale", params.locale);
+      if (params?.type)
+        qs.set("type", params.type);
+      const q = qs.toString();
+      return this.request("GET", `/catalog/games${q ? `?${q}` : ""}`);
+    },
+    getHomepageGames: () => this.request("GET", "/catalog/homepage-games"),
+    getGame: (slug, locale) => {
+      const qs = locale ? `?locale=${locale}` : "";
+      return this.request("GET", `/catalog/games/${slug}${qs}`);
+    },
+    getProducts: (gameSlug, categorySlug) => {
+      const qs = categorySlug ? `?category=${categorySlug}` : "";
+      return this.request("GET", `/catalog/games/${gameSlug}/products${qs}`);
+    },
+    getProductsGrouped: (gameSlug) => this.request("GET", `/catalog/games/${gameSlug}/products/grouped`),
+    search: (query, limit = 20) => this.request("GET", `/catalog/search?q=${encodeURIComponent(query)}&limit=${limit}`),
+    searchSuggestions: (query, limit = 5) => this.request("GET", `/catalog/search/suggestions?q=${encodeURIComponent(query)}&limit=${limit}`),
+    getProduct: (productId) => this.request("GET", `/catalog/products/${productId}`)
+  };
+  cart = {
+    get: () => this.request("GET", "/cart"),
+    add: (item) => this.request("POST", "/cart", item),
+    sync: (items) => this.request("POST", "/cart/sync", { items }),
+    remove: (id) => this.request("DELETE", `/cart/${id}`),
+    clear: () => this.request("DELETE", "/cart")
+  };
+  checkout = {
+    create: (data, idempotencyKey) => this.request("POST", "/checkout", data, {
+      idempotencyKey: idempotencyKey || generateIdempotencyKey()
+    }),
+    completeWithBalance: (paymentCode) => this.request("POST", `/checkout/${paymentCode}/complete`),
+    getPaymentMethods: () => this.request("GET", "/payment-methods")
+  };
+  orders = {
+    list: () => this.request("GET", "/orders"),
+    get: (code) => this.request("GET", `/orders/${code}`),
+    getByPayment: (paymentCode) => this.request("GET", `/checkout/orders/payment/${paymentCode}`, undefined, { rawResponse: true }),
+    cancel: (code) => this.request("POST", `/orders/${code}/cancel`)
+  };
+  profile = {
+    getBalance: () => this.request("GET", "/profile/balance"),
+    getLevelStatus: () => this.request("GET", "/profile/level-status"),
+    getTransactions: (params) => {
+      const qs = new URLSearchParams;
+      if (params?.limit)
+        qs.set("limit", String(params.limit));
+      if (params?.offset)
+        qs.set("offset", String(params.offset));
+      const q = qs.toString();
+      return this.request("GET", `/profile/balance/transactions${q ? `?${q}` : ""}`);
+    },
+    getOrders: () => this.request("GET", "/profile/orders"),
+    getNotifications: () => this.request("GET", "/profile/notifications"),
+    getUnreadCount: () => this.request("GET", "/profile/notifications/unread-count"),
+    markRead: (id) => this.request("POST", `/profile/notifications/${id}/read`),
+    markAllRead: () => this.request("POST", "/profile/notifications/read-all")
+  };
+  favorites = {
+    list: () => this.request("GET", "/favorites"),
+    add: (productId, gameId) => this.request("POST", "/favorites", { productId, gameId }),
+    remove: (productId) => this.request("DELETE", `/favorites/${productId}`)
+  };
+  coupons = {
+    apply: (code) => this.request("POST", "/coupons/apply", { code }),
+    remove: () => this.request("DELETE", "/coupons/active"),
+    validate: (code, gameId) => this.request("POST", "/coupons/validate", { code, gameId }),
+    getActive: () => this.request("GET", "/profile/active-coupon")
+  };
+  referrals = {
+    getStats: () => this.request("GET", "/referral/stats"),
+    getLinks: () => this.request("GET", "/referral/links"),
+    createLink: (data) => this.request("POST", "/referral/links", data),
+    updateLink: (id, data) => this.request("PATCH", `/referral/links/${id}`, data),
+    deleteLink: (id) => this.request("DELETE", `/referral/links/${id}`),
+    getLinkStats: (id) => this.request("GET", `/referral/links/${id}/stats`),
+    getCommissions: () => this.request("GET", "/referral/commissions")
+  };
+  reviews = {
+    listPublic: (params) => {
+      const qs = new URLSearchParams;
+      if (params?.gameSlug)
+        qs.set("gameSlug", params.gameSlug);
+      if (params?.limit)
+        qs.set("limit", String(params.limit));
+      if (params?.offset)
+        qs.set("offset", String(params.offset));
+      const q = qs.toString();
+      return this.request("GET", `/reviews/public${q ? `?${q}` : ""}`, undefined, { rawResponse: true });
+    },
+    getStats: (gameSlug) => {
+      const qs = gameSlug ? `?gameSlug=${gameSlug}` : "";
+      return this.request("GET", `/reviews/public/stats${qs}`);
+    },
+    getRandom: (limit = 5) => this.request("GET", `/reviews/public/random?limit=${limit}`),
+    getMine: () => this.request("GET", "/reviews/mine"),
+    getPending: () => this.request("GET", "/reviews/orders-without-reviews"),
+    create: (orderId, rating, text) => this.request("POST", "/reviews", { orderId, rating, text })
+  };
+  topup = {
+    getPaymentMethods: () => this.request("GET", "/topup/payment-methods"),
+    create: (amount, paymentMethod) => this.request("POST", "/topup", { amount, paymentMethod }),
+    getStatus: (code) => this.request("GET", `/topup/${code}`)
+  };
+  giftCards = {
+    purchase: (amountUsd) => this.request("POST", "/gift-cards/purchase", { amountUsd }),
+    redeem: (code) => this.request("POST", "/gift-cards/redeem", { code }),
+    check: (code) => this.request("GET", `/gift-cards/check?code=${code}`),
+    getMine: () => this.request("GET", "/profile/gift-cards")
+  };
+  announcements = {
+    list: (limit = 10) => this.request("GET", `/announcements?limit=${limit}`),
+    get: (id) => this.request("GET", `/announcements/${id}`)
+  };
+  sse = {
+    connectEvents: () => new EventSource(`${this.baseUrl}/sse/events`, { withCredentials: true }),
+    trackOrder: (orderCode) => new EventSource(`${this.baseUrl}/sse/orders/${orderCode}`)
+  };
+  analytics = {
+    recordView: (gameId) => this.request("POST", "/analytics/game-view", { gameId })
+  };
+  seo = {
+    getContent: (pageType, entityId, locale) => {
+      const qs = locale ? `?locale=${locale}` : "";
+      return this.request("GET", `/seo/${pageType}/${entityId}${qs}`, undefined, { rawResponse: true });
+    },
+    getSchema: (pageType, entityId) => this.request("GET", `/seo/schema/${pageType}/${entityId}`, undefined, { rawResponse: true })
+  };
+}
+export {
+  generateIdempotencyKey,
+  formatPrice,
+  convertPrice,
+  GameCoreError,
+  GameCoreClient
+};

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Server-side entrypoint for @gamecore/sdk.
+ * Includes webhook verification (requires node:crypto).
+ *
+ * Usage: import { verifyWebhookSignature } from "@gamecore/sdk/server"
+ */
+export { verifyWebhookSignature, parseWebhookPayload } from "./webhooks";

package/dist/server.js

@@ -0,0 +1,29 @@
+// src/webhooks.ts
+import { createHmac, timingSafeEqual } from "node:crypto";
+function verifyWebhookSignature(payload, signature, secret, maxAgeSeconds = 300) {
+  const expected = `sha256=${createHmac("sha256", secret).update(payload).digest("hex")}`;
+  const sigBuf = Buffer.from(signature);
+  const expectedBuf = Buffer.from(expected);
+  if (sigBuf.length !== expectedBuf.length)
+    return false;
+  if (!timingSafeEqual(sigBuf, expectedBuf))
+    return false;
+  if (maxAgeSeconds > 0) {
+    try {
+      const parsed = JSON.parse(payload);
+      if (parsed.timestamp) {
+        const age = (Date.now() - new Date(parsed.timestamp).getTime()) / 1000;
+        if (age > maxAgeSeconds)
+          return false;
+      }
+    } catch {}
+  }
+  return true;
+}
+function parseWebhookPayload(body) {
+  return JSON.parse(body);
+}
+export {
+  verifyWebhookSignature,
+  parseWebhookPayload
+};

package/dist/types.d.ts

@@ -0,0 +1,353 @@
+export interface TelegramInitResponse {
+    success: boolean;
+    token: string;
+    botLink: string;
+    expiresIn: number;
+}
+export interface AuthStatusResponse {
+    status: "pending" | "verified" | "authenticated" | "expired" | "used";
+    user?: User;
+}
+export interface User {
+    id: number;
+    firstName: string;
+    lastName?: string;
+    username?: string;
+    photoUrl?: string;
+    email?: string;
+    role: string;
+    level: number;
+    telegramId?: string;
+    vkId?: string;
+}
+export interface SiteConfig {
+    apiVersion: string;
+    site: {
+        slug: string;
+        name: string;
+    };
+    modules: Record<string, boolean>;
+    auth: string[];
+    payments: string[];
+    displayCurrency: string;
+    rateMode: "auto" | "manual";
+    currentRate: number;
+    supportedLocales?: string[];
+}
+export interface ExchangeRates {
+    usdToRub: number;
+    base: string;
+    updatedAt: string;
+    rates: Record<string, number>;
+}
+export interface LegalDocument {
+    title: string;
+    content: string;
+    version?: string;
+    locale?: string;
+    updatedAt: string;
+}
+export interface Game {
+    id: number;
+    slug: string;
+    name: string;
+    icon: string | null;
+    localIcon?: string | null;
+    productCount: number;
+    minPrice?: number | null;
+    type?: string;
+}
+export interface GameDetail {
+    id: number;
+    slug: string;
+    name: string;
+    icon: string | null;
+    localIcon?: string | null;
+    description: string | null;
+    categories: Category[];
+}
+export interface Category {
+    id: number;
+    slug: string;
+    name: string;
+    productCount: number;
+}
+export interface Product {
+    id: number;
+    name: string;
+    icon: string | null;
+    price: number | null;
+    priceWithoutDiscount?: number;
+    discountPercent?: number;
+    gameId: string;
+    gameName: string;
+    gameIcon: string | null;
+    categoryId: number;
+    categoryName: string;
+    productType: string;
+    deliveryDataSchema: unknown[];
+    region?: string;
+}
+export interface SearchResult {
+    games: Game[];
+    products: Product[];
+}
+export interface CartItem {
+    id?: number;
+    productId: number;
+    gameId: string;
+    gameName: string;
+    productName: string;
+    price: number;
+    deliveryData: Record<string, string>;
+}
+export interface CheckoutRequest {
+    email?: string;
+    items: Array<{
+        productId: number;
+        gameId?: string;
+        gameName?: string;
+        productName?: string;
+        amount?: number;
+        deliveryData?: Record<string, string>;
+    }>;
+    paymentMethod?: string;
+    couponCode?: string;
+}
+export interface CheckoutResponse {
+    payment?: {
+        code: string;
+        total: number;
+        paymentUrl?: string;
+        status?: string;
+    };
+    orders?: Array<{
+        code: string;
+        status: string;
+    }>;
+}
+export type OrderStatus = "pending" | "paid" | "processing" | "completed" | "cancelled" | "refunded" | "failed";
+export interface Order {
+    id: number;
+    code: string;
+    status: OrderStatus;
+    totalAmount: number;
+    gameName: string;
+    gameId: string;
+    paymentCode?: string;
+    items: OrderItem[];
+    payment?: {
+        code: string;
+        status: string;
+        totalAmount: number;
+    };
+    createdAt: string;
+    completedAt?: string;
+}
+export interface OrderItem {
+    id: number;
+    productId: number;
+    productName: string;
+    gameName: string;
+    price: number;
+    amount: number;
+    status?: string;
+    supplierStatus?: string;
+    cdKey?: string;
+    deliveryData: Record<string, unknown>;
+}
+export interface UserBalance {
+    permanent: number;
+    bonus: number;
+    total: number;
+    level: number;
+    levelDiscount: number;
+    totalSpent: number;
+    bonusDetails: Array<{
+        id: number;
+        remaining: number;
+        expiresAt: string;
+    }>;
+}
+export interface LevelStatus {
+    currentLevel: number;
+    currentDiscount: number;
+    nextLevel: number | null;
+    nextDiscount: number | null;
+    isMaxLevel: boolean;
+    requirements?: {
+        spending?: {
+            current: number;
+            required: number;
+            met: boolean;
+        };
+        reviews?: {
+            current: number;
+            required: number;
+            met: boolean;
+        };
+        referrals?: {
+            current: number;
+            required: number;
+            met: boolean;
+        };
+    };
+}
+export interface Transaction {
+    id: number;
+    type: string;
+    amount: number;
+    description: string;
+    createdAt: string;
+}
+export interface Notification {
+    id: number;
+    type: string;
+    title: string;
+    body: string;
+    isRead: boolean;
+    data?: Record<string, unknown>;
+    createdAt: string;
+}
+export interface Favorite {
+    id: number;
+    productId: number;
+    productName: string;
+    productSlug?: string;
+    productIcon?: string | null;
+    price: number;
+    gameId: string;
+    gameSlug?: string;
+    gameName: string;
+    gameIcon?: string | null;
+    categorySlug?: string;
+    createdAt: string;
+}
+export interface Review {
+    id: number;
+    userId: number;
+    userName?: string;
+    orderId: number;
+    orderCode?: string;
+    rating: number;
+    text?: string;
+    gameName?: string;
+    bonus?: {
+        amount: number;
+        percent: number;
+        expiresAt: string;
+    };
+    createdAt: string;
+}
+export interface ReviewStats {
+    averageRating: number;
+    totalCount: number;
+    distribution?: Record<string, number>;
+}
+export interface CouponResult {
+    type: string;
+    value: number;
+    code: string;
+    gameId?: number | null;
+    bonusAmount?: number;
+}
+export interface ReferralStats {
+    totalReferrals: number;
+    lifetimeEarnings: number;
+    commissionRate: number;
+    commissionBasis: string;
+    links?: ReferralLink[];
+}
+export interface ReferralLink {
+    id: number;
+    code: string;
+    slug?: string | null;
+    label?: string;
+    targetUrl?: string | null;
+    clicks: number;
+    registrations: number;
+    url?: string;
+    createdAt: string;
+}
+export interface ReferralCommission {
+    id: number;
+    referredUserId: number;
+    orderId: number;
+    orderAmount: number;
+    commissionAmount: number;
+    commissionPercent: number;
+    createdAt: string;
+}
+export interface TopupMethod {
+    type: string;
+    label: string;
+    description?: string;
+    feePercent?: number;
+    gatewayType?: string;
+    invoiceCurrency?: string;
+}
+export interface TopupResponse {
+    code: string;
+    amount: number;
+    paymentUrl?: string;
+}
+export interface TopupStatus {
+    code: string;
+    status: string;
+    amount: number;
+    createdAt?: string;
+}
+export interface GiftCard {
+    id: number;
+    code: string;
+    denomination: number;
+    status: string;
+    createdAt: string;
+    redeemedAt?: string;
+}
+export interface Announcement {
+    id: number;
+    title: string;
+    body: string;
+    type?: string;
+    imageUrl?: string | null;
+    createdAt: string;
+}
+export interface OrderUpdateEvent {
+    orderId: number;
+    orderCode: string;
+    status: string;
+    items?: Array<{
+        productName: string;
+        status: string;
+        cdKey?: string;
+    }>;
+}
+export type WebhookEvent = "order.created" | "order.completed" | "order.failed" | "order.cancelled" | "payment.received" | "payment.failed" | "user.registered" | "catalog.updated";
+export interface WebhookPayload {
+    event: WebhookEvent;
+    timestamp: string;
+    siteId: number;
+    sandbox: boolean;
+    data: Record<string, unknown>;
+}
+/** Standard API response wrapper. Most endpoints return { success, data } or { success, error }. */
+export interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+export interface PaginatedResponse<T> {
+    data: T[];
+    pagination: {
+        limit: number;
+        offset: number;
+        total: number;
+        hasMore: boolean;
+    };
+}
+export declare class GameCoreError extends Error {
+    status: number;
+    code?: string;
+    constructor(message: string, status: number, code?: string);
+}

package/dist/utils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Convert a price from USD to target currency.
+ */
+export declare function convertPrice(priceUsd: number, rate: number): number;
+/**
+ * Format a price with currency symbol.
+ * Examples: "1 234 ₽", "$12.34", "€12.34"
+ */
+export declare function formatPrice(amount: number, currency?: string): string;
+/**
+ * Generate a unique idempotency key for checkout requests.
+ */
+export declare function generateIdempotencyKey(): string;

package/dist/webhooks.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Webhook verification utilities — SERVER-SIDE ONLY.
+ * Uses node:crypto, do not import in browser bundles.
+ *
+ * Import from "@gamecore/sdk/server" instead of "@gamecore/sdk".
+ */
+import type { WebhookPayload } from "./types";
+/**
+ * Verify webhook signature (HMAC-SHA256) with timing-safe comparison.
+ * Use on your server to validate incoming webhooks from GameCore.
+ *
+ * @param payload - Raw request body string
+ * @param signature - Value of X-Webhook-Signature header
+ * @param secret - Your webhook secret from site settings
+ * @param maxAgeSeconds - Max age of webhook (default 300 = 5 minutes). Set to 0 to disable.
+ */
+export declare function verifyWebhookSignature(payload: string, signature: string, secret: string, maxAgeSeconds?: number): boolean;
+/**
+ * Parse a webhook payload string into a typed object.
+ */
+export declare function parseWebhookPayload(body: string): WebhookPayload;

package/package.json

@@ -0,0 +1,31 @@
+{
+	"name": "@gamecore-api/sdk",
+	"version": "0.2.0",
+	"description": "TypeScript SDK for GameCore API — browser-safe, zero dependencies",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"module": "dist/index.mjs",
+	"exports": {
+		".": {
+			"import": "./dist/index.js",
+			"require": "./dist/index.js",
+			"types": "./dist/index.d.ts"
+		},
+		"./server": {
+			"import": "./dist/server.js",
+			"require": "./dist/server.js",
+			"types": "./dist/server.d.ts"
+		}
+	},
+	"files": ["dist"],
+	"scripts": {
+		"build": "bun build src/index.ts --outdir dist --target browser && bun build src/server.ts --outdir dist --target node && bun x tsc --emitDeclarationOnly",
+		"typecheck": "bun x tsc --noEmit"
+	},
+	"devDependencies": {
+		"@types/node": "^25.5.0",
+		"typescript": "^5.0.0"
+	},
+	"keywords": ["gamecore", "game-donation", "sdk", "api-client", "typescript"],
+	"license": "MIT"
+}