com.crossx.sdk.cocos-creator2 0.0.0-beta.1

package/Plugins/Android/src/main/java/com/crossx/sdk/cocos/CROSSxAndroidNativeClient.java

@@ -0,0 +1,103 @@
+package com.crossx.sdk.cocos;
+
+import android.app.Activity;
+import android.content.Intent;
+import android.net.Uri;
+import java.lang.reflect.Method;
+import org.json.JSONObject;
+
+/**
+ * Default Android native client.
+ *
+ * <p>OAuth is delegated to {@link CROSSxOAuthBridge}, which wraps the external
+ * {@code io.crosstoken.crossxwebkit.CustomTabsWebAuthAdapter} (provided via the
+ * CROSSx Android SDK BOM). When the Cocos {@link Activity} cannot be resolved or the
+ * OAuth flow fails to start, we fall back to a plain {@code ACTION_VIEW} intent so the
+ * user is never stranded. Wallet operations still need to be wired to the native SDK.</p>
+ */
+public class CROSSxAndroidNativeClient extends PendingCROSSxCocosNativeClient {
+    @Override
+    public Object openOAuth(JSONObject payload) throws Exception {
+        String authUrl = payload.optString("authUrl", "");
+        if (authUrl.length() == 0) {
+            throw new IllegalArgumentException("openOAuth requires authUrl");
+        }
+
+        String callbackScheme = payload.optString("callbackScheme", "");
+        boolean nativeOpened = openWithCrossxOAuth(authUrl, callbackScheme);
+        if (!nativeOpened) {
+            openUrl(authUrl);
+        }
+
+        JSONObject result = new JSONObject();
+        result.put("url", authUrl);
+        result.put("status", "opened");
+        result.put("nativeOAuth", nativeOpened);
+        return result;
+    }
+
+    public boolean handleCallbackUrl(String url) {
+        if (url == null || url.length() == 0) return false;
+        // Our own bridge is a sibling in the same package — call it directly so this
+        // path is robust against ProGuard / R8 stripping the reflection target.
+        if (CROSSxOAuthBridge.handleCallbackUrl(url)) return true;
+        // Fall back to the Unity SDK bridge if a Unity OAuth flow was started in the
+        // same process (e.g. side-by-side integration). This is a soft dependency, so
+        // we keep it as reflection.
+        return invokeUnityBridgeBoolean("handleCallbackUrl", new Class<?>[] { String.class }, new Object[] { url });
+    }
+
+    private boolean openWithCrossxOAuth(String authUrl, String callbackScheme) {
+        if (callbackScheme == null || callbackScheme.length() == 0) return false;
+        // Compile-time call to our own OAuth bridge — this guarantees we know exactly
+        // whether the flow actually started, instead of relying on reflection swallowing
+        // a silent "no activity" return as success. If no activity is available right
+        // now we report false so the caller falls back to ACTION_VIEW.
+        if (CROSSxCocosActivityProvider.currentActivity() != null) {
+            try {
+                CROSSxOAuthBridge.startOAuthFlow(authUrl, callbackScheme);
+                return true;
+            } catch (Throwable ignored) {
+                // Fall through to the Unity legacy bridge and finally to ACTION_VIEW.
+            }
+        }
+        return invokeUnityBridgeVoid(
+            "startOAuthFlow",
+            new Class<?>[] { String.class, String.class },
+            new Object[] { authUrl, callbackScheme }
+        );
+    }
+
+    private boolean invokeUnityBridgeVoid(String methodName, Class<?>[] argTypes, Object[] args) {
+        try {
+            Class<?> bridge = Class.forName("com.nexus.cross.sdk.unity.CROSSxOAuthBridge");
+            Method method = bridge.getMethod(methodName, argTypes);
+            method.invoke(null, args);
+            return true;
+        } catch (Exception ignored) {
+            return false;
+        }
+    }
+
+    private boolean invokeUnityBridgeBoolean(String methodName, Class<?>[] argTypes, Object[] args) {
+        try {
+            Class<?> bridge = Class.forName("com.nexus.cross.sdk.unity.CROSSxOAuthBridge");
+            Method method = bridge.getMethod(methodName, argTypes);
+            Object result = method.invoke(null, args);
+            return result instanceof Boolean && (Boolean) result;
+        } catch (Exception ignored) {
+            return false;
+        }
+    }
+
+    protected void openUrl(String url) {
+        Activity activity = CROSSxCocosActivityProvider.currentActivity();
+        if (activity == null) {
+            throw new IllegalStateException("Cocos Android Activity is unavailable");
+        }
+
+        Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(url));
+        intent.addCategory(Intent.CATEGORY_BROWSABLE);
+        activity.startActivity(intent);
+    }
+}

package/Plugins/Android/src/main/java/com/crossx/sdk/cocos/CROSSxAndroidSecureStorage.java

@@ -0,0 +1,138 @@
+package com.crossx.sdk.cocos;
+
+import android.app.Activity;
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.os.Build;
+import android.security.keystore.KeyGenParameterSpec;
+import android.security.keystore.KeyProperties;
+import android.util.Base64;
+import java.security.KeyStore;
+import java.util.Arrays;
+import javax.crypto.Cipher;
+import javax.crypto.KeyGenerator;
+import javax.crypto.SecretKey;
+import javax.crypto.spec.GCMParameterSpec;
+
+/**
+ * Secure token storage backed by Android Keystore + AES-256-GCM.
+ *
+ * <p>On API 23+ (Marshmallow), values are encrypted with a key stored in the
+ * Android Keystore (hardware-backed on supported devices). On older API levels
+ * values are stored unencrypted in a MODE_PRIVATE SharedPreferences file as a
+ * best-effort fallback.
+ *
+ * <p>Requires compileSdkVersion >= 23 in the host project's build.gradle.
+ * No additional Gradle dependencies are needed — all APIs are part of the
+ * standard Android SDK.
+ *
+ * <p>Called from TypeScript via jsb.reflection.callStaticMethod:
+ * <ul>
+ *   <li>getItem(String key)            → (Ljava/lang/String;)Ljava/lang/String;</li>
+ *   <li>setItem(String key, String val) → (Ljava/lang/String;Ljava/lang/String;)V</li>
+ *   <li>removeItem(String key)         → (Ljava/lang/String;)V</li>
+ *   <li>clear()                        → ()V</li>
+ * </ul>
+ */
+public final class CROSSxAndroidSecureStorage {
+    private static final String KEYSTORE_ALIAS  = "crossx_sdk_storage_key";
+    private static final String ANDROID_KEYSTORE = "AndroidKeyStore";
+    private static final String PREFS_FILE       = "crossx_secure_prefs";
+    private static final String TRANSFORMATION   = "AES/GCM/NoPadding";
+    private static final int    IV_SIZE          = 12;
+    private static final int    TAG_BIT_LENGTH   = 128;
+
+    private CROSSxAndroidSecureStorage() {}
+
+    public static String getItem(String key) {
+        Activity activity = CROSSxCocosActivityProvider.currentActivity();
+        if (activity == null || key == null) return null;
+        String stored = prefs(activity).getString(key, null);
+        if (stored == null) return null;
+        if (Build.VERSION.SDK_INT < 23) return stored;
+        try {
+            return decrypt(stored);
+        } catch (Exception e) {
+            return null;
+        }
+    }
+
+    public static void setItem(String key, String value) {
+        Activity activity = CROSSxCocosActivityProvider.currentActivity();
+        if (activity == null || key == null || value == null) return;
+        String stored = value;
+        if (Build.VERSION.SDK_INT >= 23) {
+            try {
+                stored = encrypt(value);
+            } catch (Exception ignored) {
+                // encryption failed — store plaintext so the app still works
+            }
+        }
+        prefs(activity).edit().putString(key, stored).apply();
+    }
+
+    public static void removeItem(String key) {
+        Activity activity = CROSSxCocosActivityProvider.currentActivity();
+        if (activity == null || key == null) return;
+        prefs(activity).edit().remove(key).apply();
+    }
+
+    public static void clear() {
+        Activity activity = CROSSxCocosActivityProvider.currentActivity();
+        if (activity == null) return;
+        prefs(activity).edit().clear().apply();
+    }
+
+    // ── internals ─────────────────────────────────────────────────────────────
+
+    private static SharedPreferences prefs(Context context) {
+        return context.getSharedPreferences(PREFS_FILE, Context.MODE_PRIVATE);
+    }
+
+    @SuppressWarnings("NewApi")
+    private static SecretKey getOrCreateKey() throws Exception {
+        KeyStore ks = KeyStore.getInstance(ANDROID_KEYSTORE);
+        ks.load(null);
+        if (ks.containsAlias(KEYSTORE_ALIAS)) {
+            KeyStore.SecretKeyEntry entry =
+                (KeyStore.SecretKeyEntry) ks.getEntry(KEYSTORE_ALIAS, null);
+            if (entry != null) return entry.getSecretKey();
+        }
+        KeyGenerator kg = KeyGenerator.getInstance(
+            KeyProperties.KEY_ALGORITHM_AES, ANDROID_KEYSTORE
+        );
+        kg.init(new KeyGenParameterSpec.Builder(
+                KEYSTORE_ALIAS,
+                KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
+            .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+            .setKeySize(256)
+            .build());
+        return kg.generateKey();
+    }
+
+    @SuppressWarnings("NewApi")
+    private static String encrypt(String value) throws Exception {
+        Cipher cipher = Cipher.getInstance(TRANSFORMATION);
+        cipher.init(Cipher.ENCRYPT_MODE, getOrCreateKey());
+        byte[] iv         = cipher.getIV();
+        byte[] ciphertext = cipher.doFinal(value.getBytes("UTF-8"));
+        byte[] combined   = new byte[IV_SIZE + ciphertext.length];
+        System.arraycopy(iv,         0, combined, 0,       IV_SIZE);
+        System.arraycopy(ciphertext, 0, combined, IV_SIZE, ciphertext.length);
+        return Base64.encodeToString(combined, Base64.NO_WRAP);
+    }
+
+    @SuppressWarnings("NewApi")
+    private static String decrypt(String encoded) throws Exception {
+        byte[] combined   = Base64.decode(encoded, Base64.NO_WRAP);
+        if (combined.length <= IV_SIZE) throw new IllegalArgumentException("Invalid ciphertext");
+        byte[] iv         = Arrays.copyOfRange(combined, 0,       IV_SIZE);
+        byte[] ciphertext = Arrays.copyOfRange(combined, IV_SIZE, combined.length);
+        Cipher cipher = Cipher.getInstance(TRANSFORMATION);
+        cipher.init(Cipher.DECRYPT_MODE, getOrCreateKey(),
+                    new GCMParameterSpec(TAG_BIT_LENGTH, iv));
+        byte[] plaintext  = cipher.doFinal(ciphertext);
+        return new String(plaintext, "UTF-8");
+    }
+}

package/Plugins/Android/src/main/java/com/crossx/sdk/cocos/CROSSxCocosActivityProvider.java

@@ -0,0 +1,33 @@
+package com.crossx.sdk.cocos;
+
+import android.app.Activity;
+
+/**
+ * Resolves the currently attached Cocos {@link Activity} for native SDK calls
+ * that need a presentation context (OAuth Custom Tabs, deep links, etc.).
+ *
+ * <p>Cocos Creator 3.x exposes the activity via {@code com.cocos.lib.GlobalObject#getActivity()};
+ * {@code CocosActivity.onCreate} registers itself there via {@code GlobalObject.init(context, this)}.
+ * The legacy Cocos2d-x location ({@code org.cocos2dx.lib.CocosHelper}) is kept as a fallback
+ * for older host projects. Both lookups are done via reflection so this class stays loadable in
+ * unit tests / standalone library builds where the Cocos engine is not on the classpath.</p>
+ */
+final class CROSSxCocosActivityProvider {
+    private CROSSxCocosActivityProvider() {}
+
+    static Activity currentActivity() {
+        // Cocos Creator 2.x (Cocos2d-x legacy)
+        try {
+            Class<?> clazz = Class.forName("org.cocos2dx.lib.CocosHelper");
+            Object activity = clazz.getMethod("getActivity").invoke(null);
+            if (activity instanceof Activity) return (Activity) activity;
+        } catch (Exception ignored) {}
+        // Cocos Creator 3.x
+        try {
+            Class<?> clazz = Class.forName("com.cocos.lib.GlobalObject");
+            Object activity = clazz.getMethod("getActivity").invoke(null);
+            if (activity instanceof Activity) return (Activity) activity;
+        } catch (Exception ignored) {}
+        return null;
+    }
+}

package/Plugins/Android/src/main/java/com/crossx/sdk/cocos/CROSSxCocosBridge.java

@@ -0,0 +1,159 @@
+package com.crossx.sdk.cocos;
+
+import android.content.Intent;
+import android.net.Uri;
+import java.lang.reflect.Method;
+import org.json.JSONException;
+import org.json.JSONObject;
+
+/**
+ * Cocos JSB entrypoint for Android.
+ *
+ * Unity SDK pattern:
+ * - Kotlin plugin + Maven repository are injected at build time.
+ * - CROSSx Android SDK is resolved from Maven using the CROSSx BOM.
+ * - This bridge stays as source in the SDK package and delegates to native SDK APIs.
+ */
+public final class CROSSxCocosBridge {
+    private static CROSSxCocosNativeClient nativeClient = new PendingCROSSxCocosNativeClient();
+
+    private CROSSxCocosBridge() {}
+
+    public static void setNativeClient(CROSSxCocosNativeClient client) {
+        nativeClient = client == null ? new PendingCROSSxCocosNativeClient() : client;
+    }
+
+    public static String request(String payload) {
+        try {
+            JSONObject request = new JSONObject(payload == null ? "{}" : payload);
+            String method = request.optString("method", "");
+            JSONObject methodPayload = normalizePayload(request);
+
+            return ok(dispatch(method, methodPayload));
+        } catch (JSONException e) {
+            return error("INVALID_REQUEST", e.getMessage());
+        } catch (UnsupportedOperationException e) {
+            return error("NATIVE_METHOD_PENDING", e.getMessage());
+        } catch (Exception e) {
+            return error("NATIVE_BRIDGE_ERROR", e.getMessage());
+        }
+    }
+
+    public static boolean handleDeepLink(Intent intent) {
+        if (intent == null) return false;
+        Uri data = intent.getData();
+        return data != null && handleDeepLink(data.toString());
+    }
+
+    public static boolean handleDeepLink(String url) {
+        if (url == null || url.length() == 0) return false;
+        if (nativeClient instanceof CROSSxAndroidNativeClient) {
+            ((CROSSxAndroidNativeClient) nativeClient).handleCallbackUrl(url);
+        }
+        return dispatchDeepLinkToJs(url);
+    }
+
+    private static JSONObject normalizePayload(JSONObject request) {
+        JSONObject payload = request.optJSONObject("payload");
+        return payload == null ? new JSONObject() : payload;
+    }
+
+    private static Object dispatch(String method, JSONObject payload) throws Exception {
+        switch (method) {
+            case "initialize": return nativeClient.initialize(payload);
+            case "signIn": return nativeClient.signIn(payload);
+            case "signOut": return nativeClient.signOut(payload);
+            case "isLoggedIn": return nativeClient.isLoggedIn(payload);
+            case "setupWallet": return nativeClient.setupWallet(payload);
+            case "getAddress": return nativeClient.getAddress(payload);
+            case "getAddresses": return nativeClient.getAddresses(payload);
+            case "getUserInfo": return nativeClient.getUserInfo(payload);
+            case "signMessage": return nativeClient.signMessage(payload);
+            case "signTypedData": return nativeClient.signTypedData(payload);
+            case "signTransaction": return nativeClient.signTransaction(payload);
+            case "sendTransaction": return nativeClient.sendTransaction(payload);
+            case "getBalance": return nativeClient.getBalance(payload);
+            case "getNonce": return nativeClient.getNonce(payload);
+            case "walletRpc": return nativeClient.walletRpc(payload);
+            case "openOAuth": return nativeClient.openOAuth(payload);
+            case "handleOAuthCallback":
+                if (nativeClient instanceof CROSSxAndroidNativeClient) {
+                    return ((CROSSxAndroidNativeClient) nativeClient).handleCallbackUrl(payload.optString("url", ""));
+                }
+                return false;
+            default:
+                throw new UnsupportedOperationException("Android bridge method is not implemented: " + method);
+        }
+    }
+
+    private static String ok(Object result) throws JSONException {
+        JSONObject response = new JSONObject();
+        response.put("ok", true);
+        response.put("result", result);
+        return response.toString();
+    }
+
+    private static String error(String code, String message) {
+        try {
+            JSONObject err = new JSONObject();
+            err.put("code", code);
+            err.put("message", message);
+            JSONObject response = new JSONObject();
+            response.put("ok", false);
+            response.put("error", err);
+            return response.toString();
+        } catch (JSONException ignored) {
+            return "{\"ok\":false,\"error\":{\"code\":\"" + code + "\",\"message\":\"" + message + "\"}}";
+        }
+    }
+
+    // Cocos Creator 2.x uses `org.cocos2dx.lib.*` (Cocos2d-x). We try the 2.x names
+    // first and keep the 3.x `com.cocos.lib.*` names as a fallback for newer host
+    // integrations that may have upgraded.
+    private static boolean dispatchDeepLinkToJs(String url) {
+        final String quotedUrl = JSONObject.quote(url).replace("
", "\\u2028").replace("
", "\\u2029");
+        final String script = "(function(u){var g=globalThis;if(g.CROSSxCocosHandleDeepLink){g.CROSSxCocosHandleDeepLink(u);}else{(g.CROSSxCocosPendingDeepLinks||(g.CROSSxCocosPendingDeepLinks=[])).push(u);}})(" + quotedUrl + ");";
+        Runnable task = new Runnable() {
+            @Override
+            public void run() {
+                evalString(script);
+            }
+        };
+
+        // Cocos Creator 2.x (Cocos2d-x legacy)
+        try {
+            Class<?> helper = Class.forName("org.cocos2dx.lib.CocosHelper");
+            helper.getMethod("runOnGameThread", Runnable.class).invoke(null, task);
+            return true;
+        } catch (Exception ignored) {}
+        // Cocos Creator 3.x
+        try {
+            Class<?> helper = Class.forName("com.cocos.lib.CocosHelper");
+            helper.getMethod("runOnGameThread", Runnable.class).invoke(null, task);
+            return true;
+        } catch (Exception ignored) {}
+        return evalString(script);
+    }
+
+    private static boolean evalString(String script) {
+        // Cocos Creator 2.x (Cocos2d-x legacy, lib package)
+        try {
+            Class<?> bridge = Class.forName("org.cocos2dx.lib.CocosJavascriptJavaBridge");
+            bridge.getMethod("evalString", String.class).invoke(null, script);
+            return true;
+        } catch (Exception ignored) {}
+        // Cocos Creator 2.x (Cocos2d-x legacy, javascript package)
+        try {
+            Class<?> bridge = Class.forName("org.cocos2dx.javascript.CocosJavascriptJavaBridge");
+            bridge.getMethod("evalString", String.class).invoke(null, script);
+            return true;
+        } catch (Exception ignored) {}
+        // Cocos Creator 3.x
+        try {
+            Class<?> bridge = Class.forName("com.cocos.lib.CocosJavascriptJavaBridge");
+            bridge.getMethod("evalString", String.class).invoke(null, script);
+            return true;
+        } catch (Exception ignored) {}
+        return false;
+    }
+}

package/Plugins/Android/src/main/java/com/crossx/sdk/cocos/CROSSxCocosBridgeInstaller.java

@@ -0,0 +1,9 @@
+package com.crossx.sdk.cocos;
+
+public final class CROSSxCocosBridgeInstaller {
+    private CROSSxCocosBridgeInstaller() {}
+
+    public static void installDefaultClients() {
+        CROSSxCocosBridge.setNativeClient(new CROSSxAndroidNativeClient());
+    }
+}

package/Plugins/Android/src/main/java/com/crossx/sdk/cocos/CROSSxCocosNativeClient.java

@@ -0,0 +1,28 @@
+package com.crossx.sdk.cocos;
+
+import org.json.JSONObject;
+
+/**
+ * Native implementation boundary for the Cocos JSB bridge.
+ *
+ * The SDK package owns the bridge contract. The platform implementation can be
+ * backed by the CROSSx Android SDK, a gateway client, or a test double.
+ */
+public interface CROSSxCocosNativeClient {
+    Object initialize(JSONObject payload) throws Exception;
+    Object signIn(JSONObject payload) throws Exception;
+    Object signOut(JSONObject payload) throws Exception;
+    Object isLoggedIn(JSONObject payload) throws Exception;
+    Object setupWallet(JSONObject payload) throws Exception;
+    Object getAddress(JSONObject payload) throws Exception;
+    Object getAddresses(JSONObject payload) throws Exception;
+    Object getUserInfo(JSONObject payload) throws Exception;
+    Object signMessage(JSONObject payload) throws Exception;
+    Object signTypedData(JSONObject payload) throws Exception;
+    Object signTransaction(JSONObject payload) throws Exception;
+    Object sendTransaction(JSONObject payload) throws Exception;
+    Object getBalance(JSONObject payload) throws Exception;
+    Object getNonce(JSONObject payload) throws Exception;
+    Object walletRpc(JSONObject payload) throws Exception;
+    Object openOAuth(JSONObject payload) throws Exception;
+}

package/Plugins/Android/src/main/java/com/crossx/sdk/cocos/CROSSxOAuthBridge.kt

@@ -0,0 +1,59 @@
+package com.crossx.sdk.cocos
+
+import android.app.Activity
+import android.util.Log
+import io.crosstoken.crossxwebkit.ActivityProvider
+import io.crosstoken.crossxwebkit.CustomTabsWebAuthAdapter
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.launch
+
+object CROSSxOAuthBridge {
+    private const val TAG = "CROSSxOAuthBridge"
+    private var webAuth: CustomTabsWebAuthAdapter? = null
+    private var authJob: Job? = null
+
+    @JvmStatic
+    fun startOAuthFlow(authUrl: String, callbackScheme: String) {
+        val activity = CROSSxCocosActivityProvider.currentActivity()
+        if (activity == null) {
+            Log.e(TAG, "No current activity available")
+            return
+        }
+
+        authJob?.cancel()
+        webAuth?.cancel()
+        webAuth = CustomTabsWebAuthAdapter(
+            activityProvider = object : ActivityProvider {
+                override fun currentActivity(): Activity? = CROSSxCocosActivityProvider.currentActivity()
+            },
+            fallbackContext = activity.applicationContext,
+        )
+
+        authJob = CoroutineScope(Dispatchers.Main).launch {
+            try {
+                webAuth?.start(
+                    url = authUrl,
+                    callbackScheme = callbackScheme,
+                    prefersEphemeralSession = false,
+                )
+            } catch (e: Exception) {
+                Log.e(TAG, "OAuth flow failed: ${e.message}", e)
+            }
+        }
+    }
+
+    @JvmStatic
+    fun handleCallbackUrl(url: String): Boolean {
+        return webAuth?.handleCallbackUrl(url) ?: false
+    }
+
+    @JvmStatic
+    fun cancelFlow() {
+        authJob?.cancel()
+        webAuth?.cancel()
+        webAuth = null
+        authJob = null
+    }
+}

package/Plugins/Android/src/main/java/com/crossx/sdk/cocos/PendingCROSSxCocosNativeClient.java

@@ -0,0 +1,34 @@
+package com.crossx.sdk.cocos;
+
+import org.json.JSONObject;
+
+class PendingCROSSxCocosNativeClient implements CROSSxCocosNativeClient {
+    protected Object pending(String method) {
+        throw new UnsupportedOperationException("Android native SDK wiring is pending for method: " + method);
+    }
+
+    @Override
+    public Object initialize(JSONObject payload) throws Exception {
+        return JSONObject.NULL;
+    }
+
+    @Override
+    public Object isLoggedIn(JSONObject payload) throws Exception {
+        return false;
+    }
+
+    @Override public Object signIn(JSONObject payload) throws Exception { return pending("signIn"); }
+    @Override public Object signOut(JSONObject payload) throws Exception { return pending("signOut"); }
+    @Override public Object setupWallet(JSONObject payload) throws Exception { return pending("setupWallet"); }
+    @Override public Object getAddress(JSONObject payload) throws Exception { return pending("getAddress"); }
+    @Override public Object getAddresses(JSONObject payload) throws Exception { return pending("getAddresses"); }
+    @Override public Object getUserInfo(JSONObject payload) throws Exception { return pending("getUserInfo"); }
+    @Override public Object signMessage(JSONObject payload) throws Exception { return pending("signMessage"); }
+    @Override public Object signTypedData(JSONObject payload) throws Exception { return pending("signTypedData"); }
+    @Override public Object signTransaction(JSONObject payload) throws Exception { return pending("signTransaction"); }
+    @Override public Object sendTransaction(JSONObject payload) throws Exception { return pending("sendTransaction"); }
+    @Override public Object getBalance(JSONObject payload) throws Exception { return pending("getBalance"); }
+    @Override public Object getNonce(JSONObject payload) throws Exception { return pending("getNonce"); }
+    @Override public Object walletRpc(JSONObject payload) throws Exception { return pending("walletRpc"); }
+    @Override public Object openOAuth(JSONObject payload) throws Exception { return pending("openOAuth"); }
+}

package/Plugins/Mac/Classes/CROSSxMacDeepLinkHandler.h

@@ -0,0 +1,25 @@
+#import <Foundation/Foundation.h>
+#import <AppKit/AppKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * Auto-installed via ObjC `+load`. Forwards macOS custom-URL-scheme events
+ * (delivered by the OS through `NSAppleEventManager` with the
+ * `kAEGetURL` Apple Event) to the JS runtime as
+ * `globalThis.CROSSxCocosHandleDeepLink(url)`. Pending URLs are queued
+ * until the script engine is ready, so the cold-launch deep link that
+ * triggered app activation is delivered as soon as the JS bridge attaches
+ * its handler.
+ *
+ * dApps don't need to call anything: simply having this source file
+ * compiled into the Cocos macOS target is enough.
+ */
+@interface CROSSxMacDeepLinkHandler : NSObject
+
++ (instancetype)shared;
++ (void)install;
+
+@end
+
+NS_ASSUME_NONNULL_END