@core-ease/telegram-kit 3.0.1

package/dist/core/index.mjs

@@ -0,0 +1,495 @@
+import { createLocalStorageFallback, callNativeOrFallback, safeInvoke, fullscreenFallback, orientationLockFallback, vibrateFallback, readClipboardFallback, scanQrFallback, shareTextFallback, downloadFileFallback, getLocationFallback, isDevModeActive } from '../chunk-JXK5HCDV.mjs';
+export { safeInvoke } from '../chunk-JXK5HCDV.mjs';
+import { bootstrapTelegramWebApp } from '../chunk-FPWYSKK2.mjs';
+import '../chunk-7AARTHNW.mjs';
+
+// src/core/index.ts
+var cachedWebApp = null;
+function getWebApp() {
+  if (typeof window === "undefined") return null;
+  if (!cachedWebApp) {
+    cachedWebApp = bootstrapTelegramWebApp().webApp;
+  }
+  return cachedWebApp;
+}
+function isInTelegram() {
+  const wa = getWebApp();
+  return Boolean(wa && wa.initData && wa.initData.length > 0);
+}
+function isVersionAtLeast(version) {
+  var _a, _b;
+  return (_b = (_a = getWebApp()) == null ? void 0 : _a.isVersionAtLeast(version)) != null ? _b : false;
+}
+function nativeReady(version) {
+  if (!isInTelegram()) return false;
+  if (isDevModeActive()) return false;
+  if (version && !isVersionAtLeast(version)) return false;
+  return true;
+}
+function getRawUserData() {
+  var _a, _b, _c;
+  return (_c = (_b = (_a = getWebApp()) == null ? void 0 : _a.initDataUnsafe) == null ? void 0 : _b.user) != null ? _c : null;
+}
+function getUserDisplayName(user) {
+  var _a, _b;
+  if (!user) return "User";
+  const fullName = `${(_a = user.first_name) != null ? _a : ""} ${(_b = user.last_name) != null ? _b : ""}`.trim();
+  if (fullName) return fullName;
+  if (user.username) return `@${user.username}`;
+  return `User_${user.id}`;
+}
+function getUserIdentifier(user) {
+  if (user == null ? void 0 : user.username) return user.username;
+  if (user == null ? void 0 : user.id) return String(user.id);
+  return "unknown";
+}
+function getUserAvatarUrl(user, fallback = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMDAiIGhlaWdodD0iMTAwIj48cmVjdCB3aWR0aD0iMTAwJSIgaGVpZ2h0PSIxMDAlIiBmaWxsPSIjNjY2Ii8+PHRleHQgeD0iNTAlIiB5PSI1MCUiIGRvbWluYW50LWJhc2VsaW5lPSJtaWRkbGUiIHRleHQtYW5jaG9yPSJtaWRkbGUiIGZvbnQtc2l6ZT0iNDAiIGZpbGw9IndoaXRlIj4/PC90ZXh0Pjwvc3ZnPg==") {
+  var _a, _b;
+  if (user == null ? void 0 : user.photo_url) return user.photo_url;
+  if (user == null ? void 0 : user.id) {
+    const name = `${(_a = user.first_name) != null ? _a : ""} ${(_b = user.last_name) != null ? _b : ""}`.trim() || user.username || `user_${user.id}`;
+    const initials = name.split(/\s+/).slice(0, 2).map((part) => {
+      var _a2, _b2;
+      return (_b2 = (_a2 = part[0]) == null ? void 0 : _a2.toUpperCase()) != null ? _b2 : "";
+    }).join("");
+    const svg = `
+      <svg xmlns="http://www.w3.org/2000/svg" width="100" height="100">
+        <rect width="100%" height="100%" rx="50" fill="#4F46E5"/>
+        <text
+          x="50%"
+          y="50%"
+          dominant-baseline="middle"
+          text-anchor="middle"
+          font-family="Arial,sans-serif"
+          font-size="40"
+          font-weight="bold"
+          fill="white"
+        >
+          ${initials}
+        </text>
+      </svg>
+    `;
+    const base64 = typeof Buffer !== "undefined" ? Buffer.from(svg).toString("base64") : btoa(svg);
+    return `data:image/svg+xml;base64,${base64}`;
+  }
+  return fallback;
+}
+function getUserInfoWithAvatar() {
+  var _a;
+  const user = (_a = getRawUserData()) != null ? _a : void 0;
+  return {
+    user,
+    avatarUrl: getUserAvatarUrl(user),
+    displayName: getUserDisplayName(user),
+    identifier: getUserIdentifier(user)
+  };
+}
+function openExternalLink(url, tryInstantView = false) {
+  const wa = getWebApp();
+  if (!wa) {
+    if (typeof window !== "undefined") window.open(url, "_blank", "noopener");
+    return;
+  }
+  wa.openLink(url, { try_instant_view: tryInstantView });
+}
+function openTelegramLink(url) {
+  const wa = getWebApp();
+  if (!wa) {
+    if (typeof window !== "undefined") window.open(url, "_blank", "noopener");
+    return;
+  }
+  wa.openTelegramLink(url);
+}
+function openInvoice(url) {
+  return callNativeOrFallback({
+    ready: nativeReady("6.1"),
+    native: () => new Promise((resolve) => getWebApp().openInvoice(url, (status) => resolve(status))),
+    fallback: () => {
+      throw new Error("openInvoice requires the Telegram app (Bot API 6.1+).");
+    }
+  });
+}
+function switchInlineQuery(query, chooseChatTypes) {
+  if (!nativeReady("6.6")) return;
+  safeInvoke(() => getWebApp().switchInlineQuery(query, chooseChatTypes));
+}
+function hideKeyboard() {
+  safeInvoke(() => {
+    var _a;
+    return (_a = getWebApp()) == null ? void 0 : _a.hideKeyboard();
+  });
+}
+function getTheme() {
+  var _a, _b;
+  const wa = getWebApp();
+  return { colorScheme: (_a = wa == null ? void 0 : wa.colorScheme) != null ? _a : "dark", themeParams: (_b = wa == null ? void 0 : wa.themeParams) != null ? _b : {} };
+}
+function getViewport() {
+  var _a, _b, _c;
+  const wa = getWebApp();
+  return {
+    height: (_a = wa == null ? void 0 : wa.viewportHeight) != null ? _a : typeof window !== "undefined" ? window.innerHeight : 0,
+    stableHeight: (_b = wa == null ? void 0 : wa.viewportStableHeight) != null ? _b : typeof window !== "undefined" ? window.innerHeight : 0,
+    isExpanded: (_c = wa == null ? void 0 : wa.isExpanded) != null ? _c : true
+  };
+}
+function expand() {
+  safeInvoke(() => {
+    var _a;
+    return (_a = getWebApp()) == null ? void 0 : _a.expand();
+  });
+}
+function ready() {
+  safeInvoke(() => {
+    var _a;
+    return (_a = getWebApp()) == null ? void 0 : _a.ready();
+  });
+}
+function close() {
+  safeInvoke(() => {
+    var _a;
+    return (_a = getWebApp()) == null ? void 0 : _a.close();
+  });
+}
+var fullscreen = {
+  enter: () => {
+    if (nativeReady("8.0")) {
+      safeInvoke(() => getWebApp().requestFullscreen());
+      return Promise.resolve(true);
+    }
+    return fullscreenFallback(true);
+  },
+  exit: () => {
+    if (nativeReady("8.0")) {
+      safeInvoke(() => getWebApp().exitFullscreen());
+      return Promise.resolve(true);
+    }
+    return fullscreenFallback(false);
+  }
+};
+var orientation = {
+  lock: () => {
+    if (nativeReady("8.0")) {
+      safeInvoke(() => getWebApp().lockOrientation());
+      return Promise.resolve(true);
+    }
+    return orientationLockFallback(true);
+  },
+  unlock: () => {
+    if (nativeReady("8.0")) {
+      safeInvoke(() => getWebApp().unlockOrientation());
+      return Promise.resolve(true);
+    }
+    return orientationLockFallback(false);
+  }
+};
+function enableClosingConfirmation() {
+  safeInvoke(() => {
+    var _a;
+    return (_a = getWebApp()) == null ? void 0 : _a.enableClosingConfirmation();
+  });
+}
+function disableClosingConfirmation() {
+  safeInvoke(() => {
+    var _a;
+    return (_a = getWebApp()) == null ? void 0 : _a.disableClosingConfirmation();
+  });
+}
+function enableVerticalSwipes() {
+  safeInvoke(() => {
+    var _a;
+    return (_a = getWebApp()) == null ? void 0 : _a.enableVerticalSwipes();
+  });
+}
+function disableVerticalSwipes() {
+  safeInvoke(() => {
+    var _a;
+    return (_a = getWebApp()) == null ? void 0 : _a.disableVerticalSwipes();
+  });
+}
+function setHeaderColor(color) {
+  safeInvoke(() => {
+    var _a;
+    return (_a = getWebApp()) == null ? void 0 : _a.setHeaderColor(color);
+  });
+}
+function setBackgroundColor(color) {
+  safeInvoke(() => {
+    var _a;
+    return (_a = getWebApp()) == null ? void 0 : _a.setBackgroundColor(color);
+  });
+}
+function setBottomBarColor(color) {
+  safeInvoke(() => {
+    var _a;
+    return (_a = getWebApp()) == null ? void 0 : _a.setBottomBarColor(color);
+  });
+}
+function addToHomeScreen() {
+  if (!nativeReady("8.0")) return;
+  safeInvoke(() => getWebApp().addToHomeScreen());
+}
+function checkHomeScreenStatus() {
+  return callNativeOrFallback({
+    ready: nativeReady("8.0"),
+    native: () => new Promise((resolve) => getWebApp().checkHomeScreenStatus((status) => resolve(status))),
+    fallback: () => "unsupported"
+  });
+}
+var haptic = {
+  light: () => nativeReady("6.1") ? getWebApp().HapticFeedback.impactOccurred("light") : vibrateFallback("light"),
+  medium: () => nativeReady("6.1") ? getWebApp().HapticFeedback.impactOccurred("medium") : vibrateFallback("medium"),
+  heavy: () => nativeReady("6.1") ? getWebApp().HapticFeedback.impactOccurred("heavy") : vibrateFallback("heavy"),
+  rigid: () => nativeReady("6.1") ? getWebApp().HapticFeedback.impactOccurred("rigid") : vibrateFallback("rigid"),
+  soft: () => nativeReady("6.1") ? getWebApp().HapticFeedback.impactOccurred("soft") : vibrateFallback("soft"),
+  success: () => nativeReady("6.1") ? getWebApp().HapticFeedback.notificationOccurred("success") : vibrateFallback("success"),
+  warning: () => nativeReady("6.1") ? getWebApp().HapticFeedback.notificationOccurred("warning") : vibrateFallback("warning"),
+  error: () => nativeReady("6.1") ? getWebApp().HapticFeedback.notificationOccurred("error") : vibrateFallback("error"),
+  selection: () => nativeReady("6.1") ? getWebApp().HapticFeedback.selectionChanged() : vibrateFallback("selection")
+};
+var cloudStorageFallback = createLocalStorageFallback("cloud");
+var deviceStorageFallback = createLocalStorageFallback("device");
+var secureStorageFallback = createLocalStorageFallback("secure");
+var cloudStorage = {
+  setItem: (key, value) => callNativeOrFallback({
+    ready: nativeReady("6.9"),
+    native: () => new Promise((resolve, reject) => getWebApp().CloudStorage.setItem(key, value, (e, ok) => e ? reject(new Error(e)) : resolve(ok != null ? ok : false))),
+    fallback: () => cloudStorageFallback.setItem(key, value)
+  }),
+  getItem: (key) => callNativeOrFallback({
+    ready: nativeReady("6.9"),
+    native: () => new Promise((resolve, reject) => getWebApp().CloudStorage.getItem(key, (e, v) => e ? reject(new Error(e)) : resolve(v))),
+    fallback: () => cloudStorageFallback.getItem(key)
+  }),
+  getItems: (keys) => callNativeOrFallback({
+    ready: nativeReady("6.9"),
+    native: () => new Promise((resolve, reject) => getWebApp().CloudStorage.getItems(keys, (e, v) => e ? reject(new Error(e)) : resolve(v != null ? v : {}))),
+    fallback: () => cloudStorageFallback.getItems(keys)
+  }),
+  removeItem: (key) => callNativeOrFallback({
+    ready: nativeReady("6.9"),
+    native: () => new Promise((resolve, reject) => getWebApp().CloudStorage.removeItem(key, (e, ok) => e ? reject(new Error(e)) : resolve(ok != null ? ok : false))),
+    fallback: () => cloudStorageFallback.removeItem(key)
+  }),
+  removeItems: (keys) => callNativeOrFallback({
+    ready: nativeReady("6.9"),
+    native: () => new Promise((resolve, reject) => getWebApp().CloudStorage.removeItems(keys, (e, ok) => e ? reject(new Error(e)) : resolve(ok != null ? ok : false))),
+    fallback: () => cloudStorageFallback.removeItems(keys)
+  }),
+  getKeys: () => callNativeOrFallback({
+    ready: nativeReady("6.9"),
+    native: () => new Promise((resolve, reject) => getWebApp().CloudStorage.getKeys((e, keys) => e ? reject(new Error(e)) : resolve(keys != null ? keys : []))),
+    fallback: () => cloudStorageFallback.getKeys()
+  })
+};
+var deviceStorage = {
+  setItem: (key, value) => callNativeOrFallback({
+    ready: nativeReady("9.0"),
+    native: () => new Promise((resolve, reject) => getWebApp().DeviceStorage.setItem(key, value, (e, ok) => e ? reject(new Error(e)) : resolve(ok != null ? ok : false))),
+    fallback: () => deviceStorageFallback.setItem(key, value)
+  }),
+  getItem: (key) => callNativeOrFallback({
+    ready: nativeReady("9.0"),
+    native: () => new Promise((resolve, reject) => getWebApp().DeviceStorage.getItem(key, (e, v) => e ? reject(new Error(e)) : resolve(v))),
+    fallback: () => deviceStorageFallback.getItem(key)
+  }),
+  removeItem: (key) => callNativeOrFallback({
+    ready: nativeReady("9.0"),
+    native: () => new Promise((resolve, reject) => getWebApp().DeviceStorage.removeItem(key, (e, ok) => e ? reject(new Error(e)) : resolve(ok != null ? ok : false))),
+    fallback: () => deviceStorageFallback.removeItem(key)
+  }),
+  clear: () => callNativeOrFallback({
+    ready: nativeReady("9.0"),
+    native: () => new Promise((resolve, reject) => getWebApp().DeviceStorage.clear((e, ok) => e ? reject(new Error(e)) : resolve(ok != null ? ok : false))),
+    fallback: () => deviceStorageFallback.clear()
+  })
+};
+var secureStorage = {
+  setItem: (key, value) => callNativeOrFallback({
+    ready: nativeReady("9.0"),
+    native: () => new Promise((resolve, reject) => getWebApp().SecureStorage.setItem(key, value, (e, ok) => e ? reject(new Error(e)) : resolve(ok != null ? ok : false))),
+    fallback: () => secureStorageFallback.setItem(key, value)
+  }),
+  getItem: (key) => callNativeOrFallback({
+    ready: nativeReady("9.0"),
+    native: () => new Promise(
+      (resolve, reject) => getWebApp().SecureStorage.getItem(key, (e, v, canRestore) => e ? reject(new Error(e)) : resolve({ value: v, canRestore: canRestore != null ? canRestore : false }))
+    ),
+    fallback: async () => ({ value: await secureStorageFallback.getItem(key), canRestore: false })
+  }),
+  removeItem: (key) => callNativeOrFallback({
+    ready: nativeReady("9.0"),
+    native: () => new Promise((resolve, reject) => getWebApp().SecureStorage.removeItem(key, (e, ok) => e ? reject(new Error(e)) : resolve(ok != null ? ok : false))),
+    fallback: () => secureStorageFallback.removeItem(key)
+  }),
+  clear: () => callNativeOrFallback({
+    ready: nativeReady("9.0"),
+    native: () => new Promise((resolve, reject) => getWebApp().SecureStorage.clear((e, ok) => e ? reject(new Error(e)) : resolve(ok != null ? ok : false))),
+    fallback: () => secureStorageFallback.clear()
+  }),
+  restoreItem: (key) => callNativeOrFallback({
+    ready: nativeReady("9.0"),
+    native: () => new Promise((resolve, reject) => getWebApp().SecureStorage.restoreItem(key, (e, v) => e ? reject(new Error(e)) : resolve(v))),
+    fallback: () => secureStorageFallback.getItem(key)
+  })
+};
+var dialog = {
+  alert: (message) => callNativeOrFallback({
+    ready: nativeReady("6.2"),
+    native: () => new Promise((resolve) => getWebApp().showAlert(message, resolve)),
+    fallback: () => {
+      if (typeof window !== "undefined") window.alert(message);
+    }
+  }),
+  confirm: (message) => callNativeOrFallback({
+    ready: nativeReady("6.2"),
+    native: () => new Promise((resolve) => getWebApp().showConfirm(message, resolve)),
+    fallback: () => typeof window !== "undefined" && window.confirm(message)
+  }),
+  popup: (params) => callNativeOrFallback({
+    ready: nativeReady("6.2"),
+    native: () => new Promise((resolve) => getWebApp().showPopup(params, (buttonId) => resolve(buttonId != null ? buttonId : null))),
+    fallback: () => {
+      var _a;
+      if (typeof window === "undefined") return null;
+      const okButton = (_a = params.buttons) == null ? void 0 : _a.find((b) => b.type === "ok" || b.type === "default");
+      const okButtonId = (okButton == null ? void 0 : okButton.id) != null ? String(okButton.id) : null;
+      if (params.buttons && params.buttons.length > 1) {
+        const ok = window.confirm(`${params.title ? params.title + "\n" : ""}${params.message}`);
+        return ok ? okButtonId != null ? okButtonId : "ok" : null;
+      }
+      window.alert(`${params.title ? params.title + "\n" : ""}${params.message}`);
+      return okButtonId;
+    }
+  }),
+  prompt: (message, defaultValue = "") => Promise.resolve(typeof window === "undefined" ? null : window.prompt(message, defaultValue))
+};
+function readClipboard() {
+  return callNativeOrFallback({
+    ready: nativeReady("6.4"),
+    native: () => new Promise((resolve) => getWebApp().readTextFromClipboard((text) => resolve(text != null ? text : null))),
+    fallback: () => readClipboardFallback()
+  });
+}
+function scanQr(text) {
+  return callNativeOrFallback({
+    ready: nativeReady("6.4"),
+    native: () => new Promise((resolve) => {
+      const wa = getWebApp();
+      wa.showScanQrPopup({ text }, (result) => {
+        wa.closeScanQrPopup();
+        resolve(result);
+        return true;
+      });
+    }),
+    fallback: () => scanQrFallback(text)
+  });
+}
+function shareToStory(mediaUrl, params) {
+  if (!nativeReady("7.8")) return;
+  safeInvoke(() => getWebApp().shareToStory(mediaUrl, params));
+}
+function shareMessage(msgId) {
+  return callNativeOrFallback({
+    ready: nativeReady("8.0"),
+    native: () => new Promise((resolve) => getWebApp().shareMessage(msgId, resolve)),
+    fallback: () => shareTextFallback(msgId)
+  });
+}
+function downloadFile(params) {
+  return callNativeOrFallback({
+    ready: nativeReady("8.0"),
+    native: () => new Promise((resolve) => getWebApp().downloadFile(params, resolve)),
+    fallback: () => downloadFileFallback(params.url, params.file_name)
+  });
+}
+function setEmojiStatus(customEmojiId, params) {
+  return callNativeOrFallback({
+    ready: nativeReady("8.0"),
+    native: () => new Promise((resolve) => getWebApp().setEmojiStatus(customEmojiId, params, resolve)),
+    fallback: () => false
+  });
+}
+function requestEmojiStatusAccess() {
+  return callNativeOrFallback({
+    ready: nativeReady("8.0"),
+    native: () => new Promise((resolve) => getWebApp().requestEmojiStatusAccess(resolve)),
+    fallback: () => false
+  });
+}
+function requestWriteAccess() {
+  return callNativeOrFallback({
+    ready: nativeReady("6.9"),
+    native: () => new Promise((resolve) => getWebApp().requestWriteAccess(resolve)),
+    fallback: () => false
+  });
+}
+function requestContact() {
+  return callNativeOrFallback({
+    ready: nativeReady("6.9"),
+    native: () => new Promise((resolve) => getWebApp().requestContact(resolve)),
+    fallback: () => false
+  });
+}
+function requestChat(reqId) {
+  return callNativeOrFallback({
+    ready: nativeReady("9.6"),
+    native: () => new Promise((resolve) => getWebApp().requestChat(reqId, resolve)),
+    fallback: () => false
+  });
+}
+function invokeCustomMethod(method, params = {}) {
+  return callNativeOrFallback({
+    ready: nativeReady("6.9"),
+    native: () => new Promise((resolve, reject) => getWebApp().invokeCustomMethod(method, params, (e, r) => e ? reject(new Error(e)) : resolve(r))),
+    fallback: () => {
+      throw new Error("invokeCustomMethod requires the Telegram app (Bot API 6.9+).");
+    }
+  });
+}
+var biometric = {
+  init: () => callNativeOrFallback({
+    ready: nativeReady("7.2"),
+    native: () => new Promise((resolve) => getWebApp().BiometricManager.init(resolve)),
+    fallback: () => void 0
+  }),
+  requestAccess: (reason) => callNativeOrFallback({
+    ready: nativeReady("7.2"),
+    native: () => new Promise((resolve) => getWebApp().BiometricManager.requestAccess({ reason }, resolve)),
+    fallback: () => false
+  }),
+  authenticate: (reason) => callNativeOrFallback({
+    ready: nativeReady("7.2"),
+    native: () => new Promise(
+      (resolve) => getWebApp().BiometricManager.authenticate({ reason }, (authenticated, token) => resolve({ authenticated, token: token != null ? token : void 0 }))
+    ),
+    fallback: () => ({ authenticated: false })
+  }),
+  updateBiometricToken: (token) => callNativeOrFallback({
+    ready: nativeReady("7.2"),
+    native: () => new Promise((resolve) => getWebApp().BiometricManager.updateBiometricToken(token, resolve)),
+    fallback: () => false
+  }),
+  openSettings: () => {
+    if (!nativeReady("7.2")) return;
+    safeInvoke(() => getWebApp().BiometricManager.openSettings());
+  }
+};
+var location = {
+  init: () => callNativeOrFallback({
+    ready: nativeReady("8.0"),
+    native: () => new Promise((resolve) => getWebApp().LocationManager.init(() => resolve())),
+    fallback: () => void 0
+  }),
+  getLocation: () => callNativeOrFallback({
+    ready: nativeReady("8.0"),
+    native: () => new Promise((resolve) => getWebApp().LocationManager.getLocation((data) => resolve(data))),
+    fallback: () => getLocationFallback()
+  }),
+  openSettings: () => {
+    if (!nativeReady("8.0")) return;
+    safeInvoke(() => getWebApp().LocationManager.openSettings());
+  }
+};
+
+export { addToHomeScreen, biometric, checkHomeScreenStatus, close, cloudStorage, deviceStorage, dialog, disableClosingConfirmation, disableVerticalSwipes, downloadFile, enableClosingConfirmation, enableVerticalSwipes, expand, fullscreen, getRawUserData, getTheme, getUserAvatarUrl, getUserDisplayName, getUserIdentifier, getUserInfoWithAvatar, getViewport, getWebApp, haptic, hideKeyboard, invokeCustomMethod, isInTelegram, isVersionAtLeast, location, openExternalLink, openInvoice, openTelegramLink, orientation, readClipboard, ready, requestChat, requestContact, requestEmojiStatusAccess, requestWriteAccess, scanQr, secureStorage, setBackgroundColor, setBottomBarColor, setEmojiStatus, setHeaderColor, shareMessage, shareToStory, switchInlineQuery };

package/dist/dev/index.d.mts

@@ -0,0 +1,77 @@
+import '../webapp-BDi9q3-a.mjs';
+import { W as WebAppUser } from '../webapp-B-3_74nK.mjs';
+
+/**
+ * `@core-ease/telegram-kit/dev`
+ *
+ * Dev mode used to work by building a large plain-object mock that
+ * re-implemented (and had to keep in sync with) the entire `TgWebApp`
+ * surface by hand. That duplication is gone: `installDevMode()` now seeds
+ * fake `tgWebAppData` / `tgWebAppThemeParams` / `tgWebAppVersion` /
+ * `tgWebAppPlatform` into the exact session-storage slot the bundled SDK
+ * reads on bootstrap (`sdk/_internal/core/webview.ts`), so the *real*
+ * `WebApp` class boots up thinking it's talking to a (very quiet) native
+ * client - no parallel implementation to maintain.
+ *
+ * Because there's no real native client behind it, response-required
+ * calls (storage, biometrics, location, popups, clipboard, ...) would
+ * naturally time out. `core/index.ts` already knows this: it marks the
+ * session as dev-mode-active (see `isDevModeActive()` in `./fallback`) so
+ * those calls skip straight to their fast browser-native fallback
+ * (`localStorage`, `window.confirm`, `navigator.geolocation`, ...)
+ * instead of waiting out a timeout. Fire-and-forget calls (buttons, theme
+ * colors, haptics, ...) flow through the real SDK either way and simply
+ * no-op harmlessly.
+ *
+ * **Call `installDevMode()` first thing** in your app's entry point,
+ * before any other `@core-ease/telegram-kit` import touches
+ * `getWebApp()` (hooks, `<TelegramProvider>`, `core/index.ts` functions,
+ * ...) - the SDK bootstraps once and caches the result, so seeding after
+ * that point has no effect.
+ */
+
+interface DevModeOptions {
+    /** Defaults to a generic "Dev User". */
+    user?: Partial<WebAppUser>;
+    /** Forces light/dark theme. Defaults to reading the host page's CSS variables (see `getAppTheme()`), falling back to dark. */
+    colorScheme?: 'light' | 'dark';
+    /** Simulated `Telegram.WebApp.platform`. Defaults to `'tdesktop'`. */
+    platform?: string;
+    /** Simulated Bot API version. Defaults to `'8.0'`. */
+    version?: string;
+    /** Simulated `start_param` (deep-link payload). */
+    startParam?: string;
+    /** Shows a small "dev mode" badge in the corner of the page. Defaults to `true`. */
+    showIndicator?: boolean;
+}
+interface InstallDevModeOptions extends DevModeOptions {
+    /** Seed fake data even if this looks like it's already running inside real Telegram. */
+    force?: boolean;
+}
+/**
+ * Seeds fake Telegram init data (a fake user, theme, platform, and Bot API
+ * version) so the bundled SDK bootstraps exactly as it would inside real
+ * Telegram - just talking to a client that never answers. Every
+ * `@core-ease/telegram-kit` feature keeps working through its browser
+ * fallback (see `core/fallback.ts`).
+ *
+ * Call this **before** anything else touches `getWebApp()` (any hook, the
+ * `<TelegramProvider>`, or any `core/index.ts` function) - the SDK
+ * bootstraps once and caches the result.
+ *
+ * Returns `false` (and does nothing) if it looks like the app is already
+ * running inside real Telegram, unless `options.force` is set.
+ */
+declare function installDevMode(options?: InstallDevModeOptions): boolean;
+/**
+ * Environment heuristic (NOT the same as "dev mode is active" - see
+ * `isDevModeActive()` in `./fallback` for that) you can use to decide
+ * *whether* to call `installDevMode()` at all, e.g.:
+ *
+ * ```ts
+ * if (isDevMode()) installDevMode();
+ * ```
+ */
+declare function isDevMode(): boolean;
+
+export { type DevModeOptions, type InstallDevModeOptions, installDevMode, isDevMode };

package/dist/dev/index.d.ts

@@ -0,0 +1,77 @@
+import '../webapp-YvmwFYUQ.js';
+import { W as WebAppUser } from '../webapp-B-3_74nK.js';
+
+/**
+ * `@core-ease/telegram-kit/dev`
+ *
+ * Dev mode used to work by building a large plain-object mock that
+ * re-implemented (and had to keep in sync with) the entire `TgWebApp`
+ * surface by hand. That duplication is gone: `installDevMode()` now seeds
+ * fake `tgWebAppData` / `tgWebAppThemeParams` / `tgWebAppVersion` /
+ * `tgWebAppPlatform` into the exact session-storage slot the bundled SDK
+ * reads on bootstrap (`sdk/_internal/core/webview.ts`), so the *real*
+ * `WebApp` class boots up thinking it's talking to a (very quiet) native
+ * client - no parallel implementation to maintain.
+ *
+ * Because there's no real native client behind it, response-required
+ * calls (storage, biometrics, location, popups, clipboard, ...) would
+ * naturally time out. `core/index.ts` already knows this: it marks the
+ * session as dev-mode-active (see `isDevModeActive()` in `./fallback`) so
+ * those calls skip straight to their fast browser-native fallback
+ * (`localStorage`, `window.confirm`, `navigator.geolocation`, ...)
+ * instead of waiting out a timeout. Fire-and-forget calls (buttons, theme
+ * colors, haptics, ...) flow through the real SDK either way and simply
+ * no-op harmlessly.
+ *
+ * **Call `installDevMode()` first thing** in your app's entry point,
+ * before any other `@core-ease/telegram-kit` import touches
+ * `getWebApp()` (hooks, `<TelegramProvider>`, `core/index.ts` functions,
+ * ...) - the SDK bootstraps once and caches the result, so seeding after
+ * that point has no effect.
+ */
+
+interface DevModeOptions {
+    /** Defaults to a generic "Dev User". */
+    user?: Partial<WebAppUser>;
+    /** Forces light/dark theme. Defaults to reading the host page's CSS variables (see `getAppTheme()`), falling back to dark. */
+    colorScheme?: 'light' | 'dark';
+    /** Simulated `Telegram.WebApp.platform`. Defaults to `'tdesktop'`. */
+    platform?: string;
+    /** Simulated Bot API version. Defaults to `'8.0'`. */
+    version?: string;
+    /** Simulated `start_param` (deep-link payload). */
+    startParam?: string;
+    /** Shows a small "dev mode" badge in the corner of the page. Defaults to `true`. */
+    showIndicator?: boolean;
+}
+interface InstallDevModeOptions extends DevModeOptions {
+    /** Seed fake data even if this looks like it's already running inside real Telegram. */
+    force?: boolean;
+}
+/**
+ * Seeds fake Telegram init data (a fake user, theme, platform, and Bot API
+ * version) so the bundled SDK bootstraps exactly as it would inside real
+ * Telegram - just talking to a client that never answers. Every
+ * `@core-ease/telegram-kit` feature keeps working through its browser
+ * fallback (see `core/fallback.ts`).
+ *
+ * Call this **before** anything else touches `getWebApp()` (any hook, the
+ * `<TelegramProvider>`, or any `core/index.ts` function) - the SDK
+ * bootstraps once and caches the result.
+ *
+ * Returns `false` (and does nothing) if it looks like the app is already
+ * running inside real Telegram, unless `options.force` is set.
+ */
+declare function installDevMode(options?: InstallDevModeOptions): boolean;
+/**
+ * Environment heuristic (NOT the same as "dev mode is active" - see
+ * `isDevModeActive()` in `./fallback` for that) you can use to decide
+ * *whether* to call `installDevMode()` at all, e.g.:
+ *
+ * ```ts
+ * if (isDevMode()) installDevMode();
+ * ```
+ */
+declare function isDevMode(): boolean;
+
+export { type DevModeOptions, type InstallDevModeOptions, installDevMode, isDevMode };