nuxt-telegram-mini-app 0.0.2 → 0.0.3

package/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"

package/README.md

@@ -7,6 +7,7 @@ A comprehensive template for building Telegram Mini Apps using Nuxt 4, Vue 3, Ty
 ![Vue](https://img.shields.io/badge/Vue-3.x-4FC08D)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6)
 ![Tailwind](https://img.shields.io/badge/Tailwind-3.x-38B2AC)
+![Telegram API](https://img.shields.io/badge/Telegram%20API-6.2-26A5E4)
 
 ## ✨ Features
 
@@ -31,7 +32,9 @@ A comprehensive template for building Telegram Mini Apps using Nuxt 4, Vue 3, Ty
 - **⬅️ Back Button** - Navigation back button control
 - **👤 User Data** - Access to Telegram user information
 - **🎨 Theme Integration** - Automatic Telegram theme colors
-- **📐 Viewport Control** - Responsive viewport management
+- **📐 Viewport Control** - Fullscreen, safe-area, and responsive viewport management
+- **🏠 Home Screen Shortcuts** - Add/check Mini App shortcut support
+- **📍 Device APIs** - Feature-detected storage, location, and motion access
 - **🔗 Deep Linking** - External and Telegram link handling
 - **📤 Sharing** - Built-in sharing functionality
 
@@ -159,7 +162,10 @@ import {
   useBackButton, 
   useHapticFeedback,
   useInitData,
-  useThemeParams 
+  useThemeParams,
+  useViewport,
+  useHomeScreen,
+  useTelegramStorage
 } from '~/composables/telegram'
 
 const main = useMainButton()
@@ -167,6 +173,9 @@ const back = useBackButton()
 const haptic = useHapticFeedback()
 const init = useInitData()
 const theme = useThemeParams()
+const viewport = useViewport()
+const homeScreen = useHomeScreen()
+const storage = useTelegramStorage('device')
 
 // Configure main button
 onMounted(() => {
@@ -188,6 +197,17 @@ onMounted(() => {
 // Access user data
 const userName = computed(() => init.user.value?.first_name || 'Guest')
 
+// Newer Telegram APIs are feature-detected
+function openFullscreen() {
+  if (!viewport.fullscreen.value) {
+    viewport.requestFullscreen()
+  }
+}
+
+function rememberPreference() {
+  storage.setItem('preferred_mode', theme.dark.value ? 'dark' : 'light')
+}
+
 // Use theme colors
 const bgColor = computed(() => theme.backgroundColor.value)
 </script>
@@ -399,6 +419,7 @@ export default {
 - `setParams(params)` - Configure button
 - `onClick(callback)` - Handle clicks
 - `visible` - Visibility state
+- Supports shine effect, custom emoji icon, and other current BottomButton params
 
 #### `useBackButton()`
 - `show()` / `hide()` - Control visibility
@@ -420,6 +441,26 @@ export default {
 - `buttonColor` - Theme button color
 - And more theme colors...
 
+#### `useViewport()`
+- `requestFullscreen()` / `exitFullscreen()` - Toggle Telegram fullscreen when supported
+- `insets` - Device safe-area insets
+- `contentInsets` - Content safe-area insets
+
+#### `useMiniApp()`
+- `hideKeyboard()` - Hide the native keyboard when supported
+- `lockOrientation()` / `unlockOrientation()` - Control device orientation when supported
+- `enableVerticalSwipes()` / `disableVerticalSwipes()` - Control vertical swipe gestures
+
+#### New Telegram APIs
+- `useSecondaryButton()` - Control Telegram's secondary bottom button
+- `useSettingsButton()` - Control the Mini App settings menu button
+- `useHomeScreen()` - Add/check home screen shortcuts
+- `useEmojiStatus()` - Request emoji status access and open the set-status dialog
+- `useTelegramStorage(type)` - Use `cloud`, `device`, or `secure` Telegram storage
+- `useLocationManager()` - Initialize and request native location data
+- `useDeviceMotion()` - Access accelerometer, orientation, and gyroscope objects
+- `shareToStory()`, `shareMessage()`, `downloadFile()`, `requestChat()` - Wrappers for newer Telegram actions
+
 ### Components
 
 #### `<TgButton>`
@@ -605,8 +646,7 @@ export default defineNuxtConfig({
   app: {
     head: {
       script: [{
-        src: 'https://telegram.org/js/telegram-web-app.js?58',
-        defer: true
+        src: 'https://telegram.org/js/telegram-web-app.js?62'
       }]
     }
   }
@@ -615,7 +655,7 @@ export default defineNuxtConfig({
 
 ### Telegram WebApp Script
 
-The template automatically includes the Telegram WebApp script. The version can be updated in the Nuxt config.
+The template automatically includes the Telegram WebApp script. The wrapper feature-detects newer APIs because the available API version depends on the user's Telegram client.
 
 ## 🤝 Contributing
 

package/app/composables/telegram.ts

@@ -1,7 +1,15 @@
 import { ref, computed, onMounted } from 'vue'
 import type {
   TelegramWebApp,
-  TelegramWebAppInitData
+  TelegramDownloadFileParams,
+  TelegramEmojiStatusParams,
+  TelegramHomeScreenStatus,
+  TelegramLocationData,
+  TelegramStoryShareParams,
+  TelegramWebAppDeviceStorage,
+  TelegramWebAppInitData,
+  TelegramWebAppSecureStorage,
+  TelegramWebAppInsets
 } from '~/types/telegram-webapp'
 
 // Helper to get WebApp instance
@@ -26,6 +34,29 @@ function initWebApp() {
   }
 }
 
+function ensureWebApp() {
+  initWebApp()
+  return globalWebApp || getWebApp()
+}
+
+const emptyInsets: TelegramWebAppInsets = {
+  top: 0,
+  bottom: 0,
+  left: 0,
+  right: 0
+}
+
+function storageCallback<T>(resolve: (value: T) => void, reject: (reason?: unknown) => void) {
+  return (error: unknown, result?: T) => {
+    if (error) {
+      reject(error)
+      return
+    }
+
+    resolve(result as T)
+  }
+}
+
 // Main composable to access Telegram WebApp
 export function useTelegramWebApp() {
   const webApp = ref<TelegramWebApp | null>(null)
@@ -47,31 +78,39 @@ export function useTelegramWebApp() {
 // Back Button
 export function useBackButton() {
   const visible = ref(false)
+  const mounted = ref(false)
 
   onMounted(() => {
     initWebApp()
     if (globalWebApp?.BackButton) {
-      visible.value = globalWebApp.BackButton.isVisible
+      visible.value = globalWebApp.BackButton.isVisible ?? false
     }
   })
 
   return {
     supported: computed(() => !!globalWebApp?.BackButton),
-    mounted: computed(() => !!globalWebApp?.BackButton),
+    mounted: computed(() => mounted.value),
     visible: computed(() => visible.value),
-    mount: () => true, // Always available with official SDK
-    unmount: () => true,
+    mount: () => {
+      mounted.value = true
+      return true
+    },
+    unmount: () => {
+      mounted.value = false
+      visible.value = false
+      return true
+    },
     show: () => {
-      if (globalWebApp?.BackButton) {
+      if (globalWebApp?.BackButton?.show) {
         globalWebApp.BackButton.show()
-        visible.value = true
       }
+      visible.value = true
     },
     hide: () => {
-      if (globalWebApp?.BackButton) {
+      if (globalWebApp?.BackButton?.hide) {
         globalWebApp.BackButton.hide()
-        visible.value = false
       }
+      visible.value = false
     },
     onClick: (fn: () => void) => {
       if (globalWebApp?.BackButton) {
@@ -96,7 +135,7 @@ export function useHapticFeedback() {
 
   return {
     supported: computed(() => !!globalWebApp?.HapticFeedback),
-    impactOccurred: (style: 'light' | 'medium' | 'heavy' = 'medium') => {
+    impactOccurred: (style: 'light' | 'medium' | 'heavy' | 'rigid' | 'soft' = 'medium') => {
       if (globalWebApp?.HapticFeedback) {
         globalWebApp.HapticFeedback.impactOccurred(style)
       }
@@ -137,6 +176,7 @@ export function useInitData() {
     authDate: computed(() => state.value?.auth_date),
     queryId: computed(() => state.value?.query_id),
     startParam: computed(() => state.value?.start_param),
+    signature: computed(() => state.value?.signature),
     restore: () => {
       // Official SDK handles this automatically
       return true
@@ -146,27 +186,50 @@ export function useInitData() {
 
 // Main Button
 export function useMainButton() {
+  const mounted = ref(false)
+  const state = ref({
+    icon_custom_emoji_id: '',
+    text: '',
+    color: '',
+    text_color: '',
+    has_shine_effect: false,
+    is_active: false,
+    is_visible: false
+  })
+
   onMounted(() => {
     initWebApp()
+    if (globalWebApp?.MainButton) {
+      state.value = {
+        icon_custom_emoji_id: globalWebApp.MainButton.iconCustomEmojiId || '',
+        text: globalWebApp.MainButton.text || '',
+        color: globalWebApp.MainButton.color || '',
+        text_color: globalWebApp.MainButton.textColor || '',
+        has_shine_effect: globalWebApp.MainButton.hasShineEffect || false,
+        is_active: globalWebApp.MainButton.isActive || false,
+        is_visible: globalWebApp.MainButton.isVisible || false
+      }
+    }
   })
 
   return {
-    mounted: computed(() => !!globalWebApp?.MainButton),
-    enabled: computed(() => globalWebApp?.MainButton?.isActive || false),
+    mounted: computed(() => mounted.value),
+    enabled: computed(() => state.value.is_active),
     loaderVisible: computed(() => globalWebApp?.MainButton?.isProgressVisible || false),
-    visible: computed(() => globalWebApp?.MainButton?.isVisible || false),
-    state: computed(() => ({
-      text: globalWebApp?.MainButton?.text || '',
-      color: globalWebApp?.MainButton?.color || '',
-      text_color: globalWebApp?.MainButton?.textColor || '',
-      is_active: globalWebApp?.MainButton?.isActive || false,
-      is_visible: globalWebApp?.MainButton?.isVisible || false
-    })),
-    text: computed(() => globalWebApp?.MainButton?.text || ''),
-    textColor: computed(() => globalWebApp?.MainButton?.textColor),
-    backgroundColor: computed(() => globalWebApp?.MainButton?.color),
-    mount: () => true, // Always available
-    unmount: () => true,
+    visible: computed(() => state.value.is_visible),
+    state: computed(() => state.value),
+    text: computed(() => state.value.text),
+    textColor: computed(() => state.value.text_color || undefined),
+    backgroundColor: computed(() => state.value.color || undefined),
+    mount: () => {
+      mounted.value = true
+      return true
+    },
+    unmount: () => {
+      mounted.value = false
+      state.value.is_visible = false
+      return true
+    },
     onClick: (fn: () => void) => {
       if (globalWebApp?.MainButton) {
         globalWebApp.MainButton.onClick(fn)
@@ -180,19 +243,88 @@ export function useMainButton() {
       }
     },
     setParams: (updates: {
+      icon_custom_emoji_id?: string
       text?: string
       color?: string
       text_color?: string
+      has_shine_effect?: boolean
+      position?: 'left' | 'right' | 'top' | 'bottom'
       is_active?: boolean
       is_visible?: boolean
     }) => {
-      if (globalWebApp?.MainButton) {
+      state.value = {
+        ...state.value,
+        ...updates
+      }
+      if (globalWebApp?.MainButton?.setParams) {
         globalWebApp.MainButton.setParams(updates)
       }
     }
   }
 }
 
+export function useSecondaryButton() {
+  onMounted(() => {
+    initWebApp()
+  })
+
+  return {
+    mounted: computed(() => !!globalWebApp?.SecondaryButton),
+    enabled: computed(() => globalWebApp?.SecondaryButton?.isActive || false),
+    loaderVisible: computed(() => globalWebApp?.SecondaryButton?.isProgressVisible || false),
+    visible: computed(() => globalWebApp?.SecondaryButton?.isVisible || false),
+    text: computed(() => globalWebApp?.SecondaryButton?.text || ''),
+    textColor: computed(() => globalWebApp?.SecondaryButton?.textColor),
+    backgroundColor: computed(() => globalWebApp?.SecondaryButton?.color),
+    position: computed(() => globalWebApp?.SecondaryButton?.position),
+    onClick: (fn: () => void) => {
+      if (globalWebApp?.SecondaryButton) {
+        globalWebApp.SecondaryButton.onClick(fn)
+        return fn
+      }
+      return () => {}
+    },
+    offClick: (fn: () => void) => {
+      globalWebApp?.SecondaryButton?.offClick(fn)
+    },
+    setParams: (updates: {
+      icon_custom_emoji_id?: string
+      text?: string
+      color?: string
+      text_color?: string
+      has_shine_effect?: boolean
+      position?: 'left' | 'right' | 'top' | 'bottom'
+      is_active?: boolean
+      is_visible?: boolean
+    }) => {
+      globalWebApp?.SecondaryButton?.setParams(updates)
+    }
+  }
+}
+
+export function useSettingsButton() {
+  onMounted(() => {
+    initWebApp()
+  })
+
+  return {
+    supported: computed(() => !!globalWebApp?.SettingsButton),
+    visible: computed(() => globalWebApp?.SettingsButton?.isVisible || false),
+    show: () => globalWebApp?.SettingsButton?.show(),
+    hide: () => globalWebApp?.SettingsButton?.hide(),
+    onClick: (fn: () => void) => {
+      if (globalWebApp?.SettingsButton) {
+        globalWebApp.SettingsButton.onClick(fn)
+        return fn
+      }
+      return () => {}
+    },
+    offClick: (fn: () => void) => {
+      globalWebApp?.SettingsButton?.offClick(fn)
+    }
+  }
+}
+
 // Mini App / Theme management
 export function useMiniApp() {
   onMounted(() => {
@@ -203,6 +335,9 @@ export function useMiniApp() {
     supported: computed(() => !!globalWebApp),
     mounted: computed(() => !!globalWebApp),
     active: computed(() => true), // Always active when available
+    foreground: computed(() => globalWebApp?.isActive ?? true),
+    fullscreen: computed(() => globalWebApp?.isFullscreen || false),
+    orientationLocked: computed(() => globalWebApp?.isOrientationLocked || false),
     dark: computed(() => globalWebApp?.colorScheme === 'dark'),
     state: computed(() => globalWebApp || null),
     backgroundColor: computed(() => globalWebApp?.backgroundColor),
@@ -222,7 +357,14 @@ export function useMiniApp() {
       if (globalWebApp) {
         globalWebApp.setBottomBarColor(color)
       }
-    }
+    },
+    enableClosingConfirmation: () => globalWebApp?.enableClosingConfirmation(),
+    disableClosingConfirmation: () => globalWebApp?.disableClosingConfirmation(),
+    enableVerticalSwipes: () => globalWebApp?.enableVerticalSwipes(),
+    disableVerticalSwipes: () => globalWebApp?.disableVerticalSwipes(),
+    lockOrientation: () => globalWebApp?.lockOrientation?.(),
+    unlockOrientation: () => globalWebApp?.unlockOrientation?.(),
+    hideKeyboard: () => globalWebApp?.hideKeyboard?.()
   }
 }
 
@@ -277,16 +419,17 @@ export function useViewport() {
       return vh === svh
     }),
     insets: computed(() => ({
-      top: 0,
-      bottom: 0,
-      left: 0,
-      right: 0
+      ...(globalWebApp?.safeAreaInset || emptyInsets)
+    })),
+    contentInsets: computed(() => ({
+      ...(globalWebApp?.contentSafeAreaInset || emptyInsets)
     })),
+    fullscreen: computed(() => globalWebApp?.isFullscreen || false),
     requestFullscreen: () => {
-      // Not available in Telegram WebApp
+      globalWebApp?.requestFullscreen?.()
     },
     exitFullscreen: () => {
-      // Not available in Telegram WebApp
+      globalWebApp?.exitFullscreen?.()
     },
     expand: () => {
       if (globalWebApp) {
@@ -296,9 +439,155 @@ export function useViewport() {
   }
 }
 
+export function useHomeScreen() {
+  onMounted(() => {
+    initWebApp()
+  })
+
+  const status = ref<TelegramHomeScreenStatus | undefined>()
+
+  return {
+    supported: computed(() => !!globalWebApp?.addToHomeScreen || !!globalWebApp?.checkHomeScreenStatus),
+    status: computed(() => status.value),
+    add: () => globalWebApp?.addToHomeScreen?.(),
+    check: () => {
+      globalWebApp?.checkHomeScreenStatus?.((nextStatus) => {
+        status.value = nextStatus
+      })
+    }
+  }
+}
+
+export function useEmojiStatus() {
+  onMounted(() => {
+    initWebApp()
+  })
+
+  return {
+    supported: computed(() => !!globalWebApp?.setEmojiStatus || !!globalWebApp?.requestEmojiStatusAccess),
+    set: (customEmojiId: string, params?: TelegramEmojiStatusParams) => {
+      return new Promise<boolean>((resolve) => {
+        if (!globalWebApp?.setEmojiStatus) {
+          resolve(false)
+          return
+        }
+
+        globalWebApp.setEmojiStatus(customEmojiId, params, resolve)
+      })
+    },
+    requestAccess: () => {
+      return new Promise<boolean>((resolve) => {
+        if (!globalWebApp?.requestEmojiStatusAccess) {
+          resolve(false)
+          return
+        }
+
+        globalWebApp.requestEmojiStatusAccess(resolve)
+      })
+    }
+  }
+}
+
+export function useTelegramStorage(type: 'cloud' | 'device' | 'secure' = 'cloud') {
+  onMounted(() => {
+    initWebApp()
+  })
+
+  const storage = computed(() => {
+    if (type === 'device') return globalWebApp?.DeviceStorage
+    if (type === 'secure') return globalWebApp?.SecureStorage
+    return globalWebApp?.CloudStorage
+  })
+
+  return {
+    supported: computed(() => !!storage.value),
+    setItem: (key: string, value: string) => {
+      return new Promise<boolean>((resolve, reject) => {
+        if (!storage.value) {
+          resolve(false)
+          return
+        }
+
+        storage.value.setItem(key, value, storageCallback(resolve, reject))
+      })
+    },
+    getItem: (key: string) => {
+      return new Promise<string | null>((resolve, reject) => {
+        if (!storage.value) {
+          resolve(null)
+          return
+        }
+
+        storage.value.getItem(key, storageCallback(resolve, reject))
+      })
+    },
+    removeItem: (key: string) => {
+      return new Promise<boolean>((resolve, reject) => {
+        if (!storage.value) {
+          resolve(false)
+          return
+        }
+
+        storage.value.removeItem(key, storageCallback(resolve, reject))
+      })
+    },
+    clear: () => {
+      return new Promise<boolean>((resolve, reject) => {
+        const currentStorage = storage.value as TelegramWebAppDeviceStorage | TelegramWebAppSecureStorage | undefined
+        if (!currentStorage?.clear) {
+          resolve(false)
+          return
+        }
+
+        currentStorage.clear(storageCallback(resolve, reject))
+      })
+    }
+  }
+}
+
+export function useLocationManager() {
+  onMounted(() => {
+    initWebApp()
+  })
+
+  return {
+    supported: computed(() => !!globalWebApp?.LocationManager),
+    inited: computed(() => globalWebApp?.LocationManager?.isInited || false),
+    available: computed(() => globalWebApp?.LocationManager?.isLocationAvailable || false),
+    accessRequested: computed(() => globalWebApp?.LocationManager?.isAccessRequested || false),
+    accessGranted: computed(() => globalWebApp?.LocationManager?.isAccessGranted || false),
+    init: () => globalWebApp?.LocationManager?.init(),
+    getLocation: () => {
+      return new Promise<TelegramLocationData | null>((resolve) => {
+        if (!globalWebApp?.LocationManager) {
+          resolve(null)
+          return
+        }
+
+        globalWebApp.LocationManager.getLocation(resolve)
+      })
+    },
+    openSettings: () => globalWebApp?.LocationManager?.openSettings()
+  }
+}
+
+export function useDeviceMotion() {
+  onMounted(() => {
+    initWebApp()
+  })
+
+  return {
+    accelerometer: computed(() => globalWebApp?.Accelerometer),
+    deviceOrientation: computed(() => globalWebApp?.DeviceOrientation),
+    gyroscope: computed(() => globalWebApp?.Gyroscope),
+    lockOrientation: () => globalWebApp?.lockOrientation?.(),
+    unlockOrientation: () => globalWebApp?.unlockOrientation?.()
+  }
+}
+
 // Links and sharing
 export function openLink(url: string, options?: { try_instant_view?: boolean }) {
-  const webApp = getWebApp()
+  const webApp = ensureWebApp()
   if (webApp) {
     webApp.openLink(url, options)
   } else {
@@ -308,7 +597,7 @@ export function openLink(url: string, options?: { try_instant_view?: boolean })
 }
 
 export function openTelegramLink(url: string) {
-  const webApp = getWebApp()
+  const webApp = ensureWebApp()
   if (webApp) {
     webApp.openTelegramLink(url)
   } else {
@@ -318,7 +607,7 @@ export function openTelegramLink(url: string) {
 }
 
 export function shareURL(url: string) {
-  const webApp = getWebApp()
+  const webApp = ensureWebApp()
   if (webApp) {
     // Use Web Share API if available, otherwise copy to clipboard
     if (navigator.share) {
@@ -340,3 +629,48 @@ export function shareURL(url: string) {
     }
   }
 }
+
+export function shareToStory(mediaUrl: string, params?: TelegramStoryShareParams) {
+  const webApp = ensureWebApp()
+  if (webApp?.shareToStory) {
+    webApp.shareToStory(mediaUrl, params)
+  } else if (navigator.share) {
+    navigator.share({ url: mediaUrl }).catch(() => {})
+  }
+}
+
+export function shareMessage(messageId: string) {
+  const webApp = ensureWebApp()
+  return new Promise<boolean>((resolve) => {
+    if (!webApp?.shareMessage) {
+      resolve(false)
+      return
+    }
+
+    webApp.shareMessage(messageId, resolve)
+  })
+}
+
+export function downloadFile(params: TelegramDownloadFileParams) {
+  const webApp = ensureWebApp()
+  return new Promise<boolean>((resolve) => {
+    if (!webApp?.downloadFile) {
+      resolve(false)
+      return
+    }
+
+    webApp.downloadFile(params, resolve)
+  })
+}
+
+export function requestChat(reqId: string) {
+  const webApp = ensureWebApp()
+  return new Promise<boolean>((resolve) => {
+    if (!webApp?.requestChat) {
+      resolve(false)
+      return
+    }
+
+    webApp.requestChat(reqId, resolve)
+  })
+}