@tma-ts/sdk

A tiny, fully typed wrapper around the Telegram WebApp client that helps you build Mini Apps in TypeScript. It exposes the complete Telegram.WebApp surface, automatically binds methods to the live instance, and lets you inject mocks for unit tests.

Features

• 🔄 Lazy proxy that binds every WebApp method/property on demand.
• ✅ Full type coverage mirroring the official Telegram Mini App API.

Installation

bun install @tma-ts/sdk
# or with npm / pnpm / yarn depending on your tooling

This package ships compiled JavaScript under dist/ together with types.d.ts, so it works out of the box in both Bun and Node projects.

Prerequisites

Telegram only injects window.Telegram.WebApp inside the in-app WebView. Add the official loader script before your app bundle:

<script src="https://telegram.org/js/telegram-web-app.js?59"></script>

When running outside Telegram (local dev, unit tests), you must provide your own mock via setSource.

Quick Start

import { WebApp, isTMA, TelegramWebAppUnavailableError } from '@tma-ts/sdk';

await isTMA();              // waits until Telegram.WebApp is ready
WebApp.MainButton.show();   // auto-binds to the underlying instance

try {
  WebApp.showAlert('Hello from Telegram Mini App!');
} catch (err) {
  if (err instanceof TelegramWebAppUnavailableError) {
    console.warn('Not inside Telegram yet.');
  } else {
    throw err;
  }
}

Because WebApp is a proxy, you can destructure members that you use frequently:

import { WebApp, MainButton, HapticFeedback } from '@tma-ts/sdk'

MainButton.setText('Submit')
MainButton.onClick(() => WebApp.sendData('payload'))
HapticFeedback.impactOccurred('light')

Testing & Dependency Injection

Inject your own implementation to run outside Telegram:

import { setSource, WebApp } from '@tma-ts/sdk';

setSource({
  version: 'test',
  MainButton: {
    isVisible: false,
    show() {
      this.isVisible = true;
    },
// ...provide all fields you assert against
  },
  sendData: (data: string) => console.log('Mock sendData', data),
// ...rest of WebApp surface you exercise in tests
});

// Reset after each test run
afterEach(() => setSource(null));

isTMA() simply resolves once a WebApp instance exists; it never throws.

Build Scripts

Clean + compile TypeScript (tsconfig.prod.json) + copy types.d.ts:

bun run build

Consumers normally install from npm, but you can build locally to inspect the bundle.

Contributing

1. Install dependencies with Bun (bun install).
2. Make changes in src/.
3. Run bun run build to generate dist/.
4. Commit with your preferred tooling.

Feel free to open issues or PRs for missing typings or new Telegram Mini App APIs.

License

MIT © Andrey Reznik