Версия 0.1.3 · Команды установки используют точные версии.

Node.js / TypeScript: безопасная интеграция покупки Telegram Stars

Node.js / TypeScript backend: username, баланс, подарки Telegram Stars/Premium и 429 без автоматического повторения покупки.

При покупке mnemonic кошелька и сессия/cookie Fragment передаются оператору API.

Начните с публичной проверки username через Node.js / TypeScript: аккаунт сервиса и данные кошелька не нужны. Проверьте статус пакета до установки или соберите SDK из исходного каталога.

Передайте mnemonic кошелька и сессию Fragment во время выполнения. Сначала проверьте баланс, сохраняя decimal-строки. Покупки в примере требуют FRAGMENT_ALLOW_PURCHASES=yes и FRAGMENT_PURCHASE_KIND=stars либо premium; выполняется только один выбранный подарок.

Выберите один нужный подарок: 50–1 000 000 Stars или Premium на 3/6/12 месяцев. Оба метода показаны для справки, а не как команда выполнить две покупки. Каждая покупка расходует реальные средства.

Обработайте типизированный flood-wait и передайте время ожидания планировщику. Не повторяйте покупку автоматически. После timeout/unconfirmed сверяйте кошелёк и получателя перед новым намеренным запросом.

Установка

npm install fragment-donor-sdk@0.1.3

Пример

// Trusted server example. Opt in and choose exactly one purchase kind.
import {
  ApiError,
  FloodWaitError,
  FragmentDonorClient,
  WalletCredentials,
} from "fragment-donor-sdk";

const allowPurchase = process.env.FRAGMENT_ALLOW_PURCHASES === "yes";
const purchaseKind = process.env.FRAGMENT_PURCHASE_KIND;
if (allowPurchase && !["stars", "premium"].includes(purchaseKind)) {
  throw new Error(
    "Set FRAGMENT_PURCHASE_KIND=stars or premium; no purchase sent",
  );
}
const client = new FragmentDonorClient();
const username = process.env.FRAGMENT_USERNAME ?? "durov";
try {
  console.log("Username:", (await client.getUserInfo(username)).username);
  if (process.env.FRAGMENT_MNEMONIC) {
    const credentials = new WalletCredentials({
      mnemonic: process.env.FRAGMENT_MNEMONIC,
      cookie: process.env.FRAGMENT_COOKIE,
      providerKey: process.env.TONCONSOLE_API_KEY,
    });
    const balance = await client.walletBalance({ credentials });
    console.log("TON:", balance.ton, "USDT:", balance.usdt_ton);
    if (allowPurchase && purchaseKind === "stars") {
      // One intentional operation; NEVER retry automatically.
      await client.buyStars(username, 50, { credentials });
    } else if (allowPurchase && purchaseKind === "premium") {
      await client.buyPremium(username, 3, { credentials });
    }
  }
} catch (error) {
  if (error instanceof FloodWaitError)
    console.log("FLOOD_WAIT seconds:", error.retryAfter);
  else if (error instanceof ApiError)
    console.log(
      error.name,
      error.status,
      "unknown purchase outcome:",
      error.purchaseOutcomeUnknown,
    );
  else throw error;
}

Читайте дальше

API Telegram Stars: отправка Stars по username · Node.js / TypeScript SDK для Telegram Stars и Premium · Timeout платежа: защита от повторной покупки Telegram Stars

OpenAPI 3.0 · Postman collection