@wowlabtech/mini-app-adapter 0.2.3 → 0.2.4

package/dist/index.d.cts

@@ -66,7 +66,7 @@ interface MiniAppInitOptions {
      */
     debug?: boolean;
     /**
-     * Dynamically loads Eruda devtools if supported.
+     * Enables Eruda devtools when host app already exposed `window.eruda`.
      */
     eruda?: boolean;
     /**
@@ -75,13 +75,45 @@ interface MiniAppInitOptions {
     mockForMacOS?: boolean;
 }
 interface MiniAppShareStoryOptions {
+    /**
+     * Shared story caption. Used by Telegram directly.
+     * For VK this value is converted into a simple text sticker when `vk.stickers` is not provided.
+     */
     text?: string;
-    widgetLink?: {
+    /**
+     * Universal CTA link.
+     * Telegram maps it to `widgetLink`, VK maps it to `attachment` when custom VK attachment is not provided.
+     */
+    link?: {
         url: string;
         name?: string;
     };
+    /**
+     * Telegram-specific options.
+     */
+    telegram?: {
+        text?: string;
+        widgetLink?: {
+            url: string;
+            name?: string;
+        };
+    };
+    /**
+     * VK-specific options.
+     */
+    vk?: {
+        backgroundType?: 'image' | 'video';
+        locked?: boolean;
+        attachment?: {
+            type: string;
+            text?: string;
+            url?: string;
+            [key: string]: unknown;
+        };
+        stickers?: Array<Record<string, unknown>>;
+    };
 }
-type MiniAppCapability = 'haptics' | 'popup' | 'qrScanner' | 'closeApp' | 'backButton' | 'backButtonVisibility' | 'bindCssVariables' | 'requestPhone' | 'notifications';
+type MiniAppCapability = 'haptics' | 'popup' | 'qrScanner' | 'closeApp' | 'backButton' | 'backButtonVisibility' | 'bindCssVariables' | 'requestPhone' | 'notifications' | 'openInternalLink' | 'requestFullscreen' | 'verticalSwipes' | 'viewVisibility' | 'shareUrl' | 'shareStory' | 'copyTextToClipboard' | 'downloadFile' | 'addToHomeScreen' | 'checkHomeScreenStatus' | 'denyNotifications';
 interface MiniAppPopupButton {
     id: string;
     text?: string;
@@ -307,7 +339,7 @@ declare abstract class BaseMiniAppAdapter implements MiniAppAdapter {
     onPushToken(callback: (token: string) => void): () => void;
     onDeepLink(callback: (path: string) => void): () => void;
     openExternalLink(url: string): Promise<void>;
-    openInternalLink(_url: string): Promise<void>;
+    openInternalLink(url: string): Promise<void>;
     closeApp(): Promise<void>;
     setBackButtonVisibility(_visible: boolean): void;
     onAppearanceChange(callback: (appearance: 'dark' | 'light' | undefined) => void): () => void;
@@ -361,6 +393,7 @@ declare class MaxMiniAppAdapter extends BaseMiniAppAdapter {
     onBackButton(callback: () => void): () => void;
     setBackButtonVisibility(visible: boolean): void;
     openExternalLink(url: string): Promise<void>;
+    openInternalLink(url: string): Promise<void>;
     closeApp(): Promise<void>;
     vibrateImpact(style: ImpactHapticFeedbackStyle): void;
     vibrateNotification(type: NotificationHapticFeedbackType): void;
@@ -505,6 +538,7 @@ declare class VKMiniAppAdapter extends BaseMiniAppAdapter {
 declare class WebMiniAppAdapter extends BaseMiniAppAdapter {
     private deferredPrompt;
     constructor();
+    supports(capability: MiniAppCapability): boolean | Promise<boolean>;
     downloadFile(url: string, filename: string): Promise<void>;
     scanQRCode(_options?: MiniAppQrScanOptions): Promise<string | null>;
     shareUrl(url: string, text: string): void;

package/dist/index.d.ts

@@ -66,7 +66,7 @@ interface MiniAppInitOptions {
      */
     debug?: boolean;
     /**
-     * Dynamically loads Eruda devtools if supported.
+     * Enables Eruda devtools when host app already exposed `window.eruda`.
      */
     eruda?: boolean;
     /**
@@ -75,13 +75,45 @@ interface MiniAppInitOptions {
     mockForMacOS?: boolean;
 }
 interface MiniAppShareStoryOptions {
+    /**
+     * Shared story caption. Used by Telegram directly.
+     * For VK this value is converted into a simple text sticker when `vk.stickers` is not provided.
+     */
     text?: string;
-    widgetLink?: {
+    /**
+     * Universal CTA link.
+     * Telegram maps it to `widgetLink`, VK maps it to `attachment` when custom VK attachment is not provided.
+     */
+    link?: {
         url: string;
         name?: string;
     };
+    /**
+     * Telegram-specific options.
+     */
+    telegram?: {
+        text?: string;
+        widgetLink?: {
+            url: string;
+            name?: string;
+        };
+    };
+    /**
+     * VK-specific options.
+     */
+    vk?: {
+        backgroundType?: 'image' | 'video';
+        locked?: boolean;
+        attachment?: {
+            type: string;
+            text?: string;
+            url?: string;
+            [key: string]: unknown;
+        };
+        stickers?: Array<Record<string, unknown>>;
+    };
 }
-type MiniAppCapability = 'haptics' | 'popup' | 'qrScanner' | 'closeApp' | 'backButton' | 'backButtonVisibility' | 'bindCssVariables' | 'requestPhone' | 'notifications';
+type MiniAppCapability = 'haptics' | 'popup' | 'qrScanner' | 'closeApp' | 'backButton' | 'backButtonVisibility' | 'bindCssVariables' | 'requestPhone' | 'notifications' | 'openInternalLink' | 'requestFullscreen' | 'verticalSwipes' | 'viewVisibility' | 'shareUrl' | 'shareStory' | 'copyTextToClipboard' | 'downloadFile' | 'addToHomeScreen' | 'checkHomeScreenStatus' | 'denyNotifications';
 interface MiniAppPopupButton {
     id: string;
     text?: string;
@@ -307,7 +339,7 @@ declare abstract class BaseMiniAppAdapter implements MiniAppAdapter {
     onPushToken(callback: (token: string) => void): () => void;
     onDeepLink(callback: (path: string) => void): () => void;
     openExternalLink(url: string): Promise<void>;
-    openInternalLink(_url: string): Promise<void>;
+    openInternalLink(url: string): Promise<void>;
     closeApp(): Promise<void>;
     setBackButtonVisibility(_visible: boolean): void;
     onAppearanceChange(callback: (appearance: 'dark' | 'light' | undefined) => void): () => void;
@@ -361,6 +393,7 @@ declare class MaxMiniAppAdapter extends BaseMiniAppAdapter {
     onBackButton(callback: () => void): () => void;
     setBackButtonVisibility(visible: boolean): void;
     openExternalLink(url: string): Promise<void>;
+    openInternalLink(url: string): Promise<void>;
     closeApp(): Promise<void>;
     vibrateImpact(style: ImpactHapticFeedbackStyle): void;
     vibrateNotification(type: NotificationHapticFeedbackType): void;
@@ -505,6 +538,7 @@ declare class VKMiniAppAdapter extends BaseMiniAppAdapter {
 declare class WebMiniAppAdapter extends BaseMiniAppAdapter {
     private deferredPrompt;
     constructor();
+    supports(capability: MiniAppCapability): boolean | Promise<boolean>;
     downloadFile(url: string, filename: string): Promise<void>;
     scanQRCode(_options?: MiniAppQrScanOptions): Promise<string | null>;
     shareUrl(url: string, text: string): void;

package/dist/index.js

@@ -580,7 +580,8 @@ var BaseMiniAppAdapter = class {
   async openExternalLink(url) {
     window.open(url, "_blank", "noopener,noreferrer");
   }
-  async openInternalLink(_url) {
+  async openInternalLink(url) {
+    window.open(url, "_self", "noopener,noreferrer");
   }
   async closeApp() {
     if (window.history.length > 1) {
@@ -806,6 +807,10 @@ var MaxMiniAppAdapter = class extends BaseMiniAppAdapter {
         return Boolean(bridge2?.BackButton?.onClick);
       case "backButtonVisibility":
         return Boolean(bridge2?.BackButton?.show && bridge2.BackButton.hide);
+      case "openInternalLink":
+        return typeof bridge2?.openMaxLink === "function";
+      case "downloadFile":
+        return typeof bridge2?.downloadFile === "function";
       case "requestPhone":
         if (!bridge2) {
           return false;
@@ -860,6 +865,14 @@ var MaxMiniAppAdapter = class extends BaseMiniAppAdapter {
     }
     await super.openExternalLink(url);
   }
+  async openInternalLink(url) {
+    const bridge2 = getMaxBridge();
+    if (bridge2?.openMaxLink) {
+      bridge2.openMaxLink(url);
+      return;
+    }
+    await super.openInternalLink(url);
+  }
   async closeApp() {
     const bridge2 = getMaxBridge();
     if (bridge2?.close) {
@@ -1287,6 +1300,30 @@ var TelegramMiniAppAdapter = class extends BaseMiniAppAdapter {
         return backButton.hide.isSupported();
       case "bindCssVariables":
         return true;
+      case "openInternalLink":
+        return true;
+      case "requestFullscreen":
+        return Boolean(
+          typeof rawViewport.requestFullscreen === "function" || viewport.requestFullscreen?.isAvailable?.()
+        );
+      case "verticalSwipes":
+        return Boolean(
+          swipeBehavior.enableVertical.isAvailable() || swipeBehavior.disableVertical.isAvailable()
+        );
+      case "viewVisibility":
+        return true;
+      case "shareUrl":
+        return typeof shareURLSdk === "function";
+      case "shareStory":
+        return typeof shareStorySdk === "function";
+      case "copyTextToClipboard":
+        return typeof copyTextToClipboardSdk === "function";
+      case "downloadFile":
+        return typeof downloadFileSdk === "function";
+      case "addToHomeScreen":
+        return typeof addToHomeScreenSdk?.isAvailable === "function" ? addToHomeScreenSdk.isAvailable() : typeof addToHomeScreenSdk === "function";
+      case "checkHomeScreenStatus":
+        return typeof checkHomeScreenStatusSdk === "function";
       case "requestPhone": {
         return Boolean(isFeatureAvailable(requestPhoneAccess) || isFeatureAvailable(requestContact));
       }
@@ -1532,7 +1569,15 @@ var TelegramMiniAppAdapter = class extends BaseMiniAppAdapter {
     await super.downloadFile(url, filename);
   }
   async shareStory(mediaUrl, options) {
-    shareStorySdk(mediaUrl, options);
+    const text = options?.telegram?.text ?? options?.text;
+    const widgetLink = options?.telegram?.widgetLink ?? (options?.link ? {
+      url: options.link.url,
+      ...options.link.name ? { name: options.link.name } : {}
+    } : void 0);
+    shareStorySdk(mediaUrl, {
+      ...text ? { text } : {},
+      ...widgetLink ? { widgetLink } : {}
+    });
   }
   async addToHomeScreen() {
     const isAvailable = typeof addToHomeScreenSdk?.isAvailable === "function" ? addToHomeScreenSdk.isAvailable() : true;
@@ -1889,17 +1934,41 @@ var VKMiniAppAdapter = class extends BaseMiniAppAdapter {
     };
   }
   async supports(capability) {
-    if (capability === "requestPhone") {
-      const [supportsPhoneNumber, supportsPersonalCard] = await Promise.all([
-        this.supportsBridgeMethod("VKWebAppGetPhoneNumber"),
-        this.supportsBridgeMethod("VKWebAppGetPersonalCard")
-      ]);
-      return supportsPhoneNumber || supportsPersonalCard;
-    }
-    if (capability === "notifications") {
-      return this.supportsBridgeMethod("VKWebAppAllowNotifications");
+    switch (capability) {
+      case "haptics": {
+        const [impact, notification, selection] = await Promise.all([
+          this.supportsBridgeMethod("VKWebAppTapticImpactOccurred"),
+          this.supportsBridgeMethod("VKWebAppTapticNotificationOccurred"),
+          this.supportsBridgeMethod("VKWebAppTapticSelectionChanged")
+        ]);
+        return impact || notification || selection;
+      }
+      case "qrScanner":
+        return this.supportsBridgeMethod("VKWebAppOpenCodeReader");
+      case "requestPhone": {
+        const [supportsPhoneNumber, supportsPersonalCard] = await Promise.all([
+          this.supportsBridgeMethod("VKWebAppGetPhoneNumber"),
+          this.supportsBridgeMethod("VKWebAppGetPersonalCard")
+        ]);
+        return supportsPhoneNumber || supportsPersonalCard;
+      }
+      case "notifications":
+        return this.supportsBridgeMethod("VKWebAppAllowNotifications");
+      case "shareUrl":
+        return this.supportsBridgeMethod("VKWebAppShare");
+      case "shareStory":
+        return this.supportsBridgeMethod("VKWebAppShowStoryBox");
+      case "downloadFile":
+        return this.supportsBridgeMethod("VKWebAppDownloadFile");
+      case "addToHomeScreen":
+        return this.supportsBridgeMethod("VKWebAppAddToHomeScreen");
+      case "denyNotifications":
+        return this.supportsBridgeMethod("VKWebAppDenyNotifications");
+      case "viewVisibility":
+        return true;
+      default:
+        return await super.supports(capability);
     }
-    return await super.supports(capability);
   }
   async requestPhone() {
     const [supportsPhoneNumber, supportsPersonalCard] = await Promise.all([
@@ -2001,9 +2070,34 @@ var VKMiniAppAdapter = class extends BaseMiniAppAdapter {
     };
   }
   async shareStory(mediaUrl, _options) {
+    const options = _options;
+    const vkOptions = options?.vk;
+    const fallbackAttachment = options?.link ? {
+      type: "url",
+      text: "open",
+      url: options.link.url
+    } : void 0;
+    const fallbackStickers = options?.text ? [{
+      sticker_type: "native",
+      sticker: {
+        action_type: "text",
+        action: {
+          text: options.text,
+          style: "classic",
+          background_style: "none"
+        },
+        transform: {
+          gravity: "center_bottom",
+          translation_y: -0.2
+        }
+      }
+    }] : void 0;
     const bridgeOptions = {
-      background_type: "image",
-      url: mediaUrl
+      background_type: vkOptions?.backgroundType ?? "image",
+      url: mediaUrl,
+      locked: vkOptions?.locked ?? true,
+      ...vkOptions?.attachment ?? fallbackAttachment ? { attachment: vkOptions?.attachment ?? fallbackAttachment } : {},
+      ...vkOptions?.stickers ?? fallbackStickers ? { stickers: vkOptions?.stickers ?? fallbackStickers } : {}
     };
     await bridge.send("VKWebAppShowStoryBox", bridgeOptions);
   }
@@ -2392,6 +2486,22 @@ var WebMiniAppAdapter = class extends BaseMiniAppAdapter {
       });
     }
   }
+  supports(capability) {
+    switch (capability) {
+      case "copyTextToClipboard":
+        return typeof navigator !== "undefined" && Boolean(navigator.clipboard?.writeText);
+      case "downloadFile":
+        return typeof document !== "undefined";
+      case "shareUrl":
+        return typeof navigator !== "undefined" && (Boolean(navigator.share) || Boolean(navigator.clipboard?.writeText));
+      case "addToHomeScreen":
+        return /android/i.test(navigator.userAgent) && Boolean(this.deferredPrompt);
+      case "checkHomeScreenStatus":
+        return true;
+      default:
+        return super.supports(capability);
+    }
+  }
   async downloadFile(url, filename) {
     try {
       await triggerFileDownload(url, filename, { preferBlob: true });