implement WorldApp global var check

src/global.d.ts

@@ -12,4 +12,14 @@ interface Window {
   };
 
   MiniKit?: import("./minikit").MiniKit;
+
+  WorldApp?: {
+    world_app_version: number;
+    device_os: "ios" | "android";
+
+    supported_commands: Array<{
+      name: import("./types/commands").Command;
+      supported_versions: Array<number>;
+    }>;
+  };
 }

src/index.ts

@@ -12,6 +12,8 @@ export {
   PaymentErrorMessage,
   WalletAuthErrorCodes,
   WalletAuthErrorMessage,
+  MiniKitInstallErrorCode,
+  MiniKitInstallErrorMessage as miniKitInstallErrorMessages,
 } from "types/errors";
 
 export { MiniKit } from "./minikit";
@@ -37,5 +39,4 @@ export {
 
 export { Tokens, Network, TokenDecimals } from "./types/payment";
 export { tokenToDecimals } from "helpers/payment/client";
-
 export { VerificationLevel } from "@worldcoin/idkit-core";

src/minikit.ts

@@ -18,6 +18,11 @@ import {
 import { VerificationLevel } from "@worldcoin/idkit-core";
 import { validateWalletAuthCommandInput } from "helpers/siwe/validate-wallet-auth-command-input";
 import { generateSiweMessage } from "helpers/siwe/siwe";
+import {
+  MiniKitInstallErrorCode,
+  MiniKitInstallReturnType,
+  miniKitInstallErrorMessages,
+} from "types";
 
 export const sendMiniKitEvent = <
   T extends WebViewBasePayload = WebViewBasePayload,
@@ -28,12 +33,27 @@ export const sendMiniKitEvent = <
 };
 
 export class MiniKit {
+  private static readonly MINIKIT_VERSION = 1;
+
+  private static readonly commandVersion = {
+    [Command.Verify]: 1,
+    [Command.Pay]: 1,
+    [Command.WalletAuth]: 1,
+  };
+
   private static listeners: Record<ResponseEvent, EventHandler> = {
     [ResponseEvent.MiniAppVerifyAction]: () => {},
     [ResponseEvent.MiniAppPayment]: () => {},
     [ResponseEvent.MiniAppWalletAuth]: () => {},
   };
 
+  private static sendInit() {
+    sendWebviewEvent({
+      command: "init",
+      payload: { version: this.MINIKIT_VERSION },
+    });
+  }
+
   public static subscribe<E extends ResponseEvent>(
     event: E,
     handler: EventHandler<E>
@@ -54,14 +74,59 @@ export class MiniKit {
     this.listeners[event](payload);
   }
 
-  public static install() {
-    if (typeof window !== "undefined" && !Boolean(window.MiniKit)) {
-      try {
-        window.MiniKit = MiniKit;
-      } catch (error) {
-        console.error("Failed to install MiniKit", error);
-        return { success: false, error };
-      }
+  private static commandsValid(
+    input: NonNullable<typeof window.WorldApp>["supported_commands"]
+  ) {
+    return input.every((command) =>
+      command.supported_versions.includes(this.commandVersion[command.name])
+    );
+  }
+
+  public static install(): MiniKitInstallReturnType {
+    if (typeof window === "undefined" || Boolean(window.MiniKit)) {
+      return {
+        success: false,
+        errorCode: MiniKitInstallErrorCode.AlreadyInstalled,
+        errorMessage:
+          miniKitInstallErrorMessages[MiniKitInstallErrorCode.AlreadyInstalled],
+      };
+    }
+
+    if (!window.WorldApp) {
+      return {
+        success: false,
+        errorCode: MiniKitInstallErrorCode.OutsideOfWorldApp,
+        errorMessage:
+          miniKitInstallErrorMessages[
+            MiniKitInstallErrorCode.OutsideOfWorldApp
+          ],
+      };
+    }
+
+    if (!this.commandsValid(window.WorldApp.supported_commands)) {
+      return {
+        success: false,
+        errorCode: MiniKitInstallErrorCode.AppOutOfDate,
+        errorMessage:
+          miniKitInstallErrorMessages[MiniKitInstallErrorCode.AppOutOfDate],
+      };
+    }
+
+    try {
+      window.MiniKit = MiniKit;
+      this.sendInit();
+    } catch (error) {
+      console.error(
+        miniKitInstallErrorMessages[MiniKitInstallErrorCode.Unknown],
+        error
+      );
+
+      return {
+        success: false,
+        errorCode: MiniKitInstallErrorCode.Unknown,
+        errorMessage:
+          miniKitInstallErrorMessages[MiniKitInstallErrorCode.Unknown],
+      };
     }
 
     return { success: true };
@@ -83,7 +148,7 @@ export class MiniKit {
       };
       sendMiniKitEvent({
         command: Command.Verify,
-        version: 1,
+        version: this.commandVersion[Command.Verify],
         payload: eventPayload,
       });
 
@@ -113,7 +178,7 @@ export class MiniKit {
 
       sendMiniKitEvent<WebViewBasePayload>({
         command: Command.Pay,
-        version: 1,
+        version: this.commandVersion[Command.Pay],
         payload: eventPayload,
       });
 
@@ -168,7 +233,7 @@ export class MiniKit {
 
       sendMiniKitEvent<WebViewBasePayload>({
         command: Command.WalletAuth,
-        version: 1,
+        version: this.commandVersion[Command.WalletAuth],
         payload: walletAuthPayload,
       });
 

src/types/commands.ts

@@ -1,5 +1,6 @@
 import { IDKitConfig, VerificationLevel } from "@worldcoin/idkit-core/*";
 import { Network, Tokens } from "./payment";
+import { MiniKitInstallErrorCode, miniKitInstallErrorMessages } from "./";
 
 export enum Command {
   Verify = "verify",
@@ -47,3 +48,11 @@ export type PayCommandPayload = PayCommandInput & {
 export type WalletAuthPayload = {
   siweMessage: string;
 };
+
+export type MiniKitInstallReturnType =
+  | { success: true }
+  | {
+      success: false;
+      errorCode: MiniKitInstallErrorCode;
+      errorMessage: (typeof miniKitInstallErrorMessages)[MiniKitInstallErrorCode];
+    };

src/types/errors.ts

@@ -61,3 +61,21 @@ export const WalletAuthErrorMessage = {
     "Provided parameters in the request are invalid.",
   [WalletAuthErrorCodes.UserRejected]: "User rejected the request.",
 };
+
+export enum MiniKitInstallErrorCode {
+  Unknown = "unknown",
+  AlreadyInstalled = "already_installed",
+  OutsideOfWorldApp = "outside_of_worldapp",
+  NotOnClient = "not_on_client",
+  AppOutOfDate = "app_out_of_date",
+}
+
+export const MiniKitInstallErrorMessage = {
+  [MiniKitInstallErrorCode.Unknown]: "Failed to install MiniKit.",
+  [MiniKitInstallErrorCode.AlreadyInstalled]: "MiniKit is already installed.",
+  [MiniKitInstallErrorCode.OutsideOfWorldApp]:
+    "MiniApp launched outside of WorldApp.",
+  [MiniKitInstallErrorCode.NotOnClient]: "Window object is not available.",
+  [MiniKitInstallErrorCode.AppOutOfDate]:
+    "WorldApp is out of date. Please update the app.",
+};

src/types/index.ts

@@ -3,6 +3,7 @@ export {
   PayCommandInput,
   WebViewBasePayload,
   Command,
+  MiniKitInstallReturnType,
 } from "./commands";
 
 export {
@@ -13,5 +14,8 @@ export {
 } from "./responses";
 
 export { Tokens } from "./payment";
-
 export { SiweMessage } from "./wallet-auth";
+export {
+  MiniKitInstallErrorCode,
+  MiniKitInstallErrorMessage as miniKitInstallErrorMessages,
+} from "./errors";