@novastera-oss/nitro-metamask 0.6.2 → 0.7.0

package/src/index.ts

@@ -1,17 +1,65 @@
 import { NitroModules } from 'react-native-nitro-modules'
-import type { NitroMetamask as NitroMetamaskSpec, ConnectResult } from './specs/nitro-metamask.nitro'
+import type {
+  NitroMetamask as NitroMetamaskSpec,
+  ConnectResult,
+  ConnectSignResult,
+} from './specs/nitro-metamask.nitro'
 
 /**
  * NitroMetamask - MetaMask connector for React Native
- * 
+ *
+ * Provides native MetaMask wallet integration via Nitro modules.
+ *
  * @example
  * ```ts
  * import { NitroMetamask } from '@novastera-oss/nitro-metamask'
- * 
- * const result = await NitroMetamask.connect()
+ *
+ * // Optional: configure before use
+ * NitroMetamask.configure('https://yourdomain.com', 'yourscheme')
+ *
+ * // Connect wallet
+ * const { address, chainId } = await NitroMetamask.connect()
+ *
+ * // Sign a message
  * const signature = await NitroMetamask.signMessage('Hello')
+ *
+ * // Connect and sign in one step (SIWE)
+ * const result = await NitroMetamask.connectSign('my-nonce', BigInt(Date.now()))
  * ```
  */
 export const NitroMetamask = NitroModules.createHybridObject<NitroMetamaskSpec>('NitroMetamask')
 
-export type { ConnectResult, NitroMetamaskSpec }
+export type { ConnectResult, ConnectSignResult, NitroMetamaskSpec }
+
+/**
+ * Parses a structured Nitro error message that contains a numeric error code prefix.
+ *
+ * Nitro errors from the native layer are formatted as `"[<code>] <message>"`.
+ * This utility extracts the code and message so the JS layer can handle them
+ * programmatically (e.g., detecting `code: 2` for MetaMask not installed).
+ *
+ * @param e - The error to parse. Can be an `Error`, a string, or any value.
+ * @returns An object `{ code: number; message: string }` if the error message
+ *          matches the `[code] message` pattern, or `null` if it does not.
+ *
+ * @example
+ * ```ts
+ * import { parseNitroError } from '@novastera-oss/nitro-metamask'
+ *
+ * try {
+ *   await NitroMetamask.connect()
+ * } catch (e) {
+ *   const parsed = parseNitroError(e)
+ *   if (parsed?.code === 2) {
+ *     // MetaMask is not installed — redirect user to App Store / Play Store
+ *   }
+ * }
+ * ```
+ */
+export function parseNitroError(e: unknown): { code: number; message: string } | null {
+  const raw = e instanceof Error ? e.message : typeof e === 'string' ? e : null
+  if (raw === null) return null
+  const match = raw.match(/^\[(\d+)\]\s*(.*)/)
+  if (!match) return null
+  return { code: Number(match[1]), message: match[2] ?? '' }
+}

package/src/specs/nitro-metamask.nitro.ts

@@ -1,14 +1,14 @@
-import { type HybridObject } from 'react-native-nitro-modules'
+import { type HybridObject, type Int64 } from 'react-native-nitro-modules'
 
 export interface ConnectResult {
   address: string
-  chainId: bigint
+  chainId: Int64
 }
 
 export interface ConnectSignResult {
   signature: string
   address: string
-  chainId: bigint
+  chainId: Int64
 }
 
 export interface NitroMetamask extends HybridObject<{ ios: 'swift', android: 'kotlin' }> {
@@ -23,17 +23,45 @@ export interface NitroMetamask extends HybridObject<{ ios: 'swift', android: 'ko
    *                         This is used to return to your app after MetaMask operations.
    */
   configure(dappUrl?: string, deepLinkScheme?: string): void
+  /**
+   * Connect to the user's MetaMask wallet.
+   *
+   * Opens the MetaMask app via deep link to request wallet connection.
+   * If MetaMask is not installed, the promise rejects with `code: 2`.
+   *
+   * @returns Promise resolving to a `ConnectResult` containing the wallet
+   *          `address` and `chainId`.
+   *
+   * @example
+   * ```ts
+   * const { address, chainId } = await NitroMetamask.connect()
+   * ```
+   */
   connect(): Promise<ConnectResult>
+  /**
+   * Request a `personal_sign` signature from the connected wallet.
+   *
+   * Must be called after a successful `connect()`. Opens MetaMask to prompt
+   * the user to sign the provided message.
+   *
+   * @param message - The plain-text message to sign.
+   * @returns Promise resolving to the hex-encoded signature string.
+   *
+   * @example
+   * ```ts
+   * const signature = await NitroMetamask.signMessage('Sign in to MyApp')
+   * ```
+   */
   signMessage(message: string): Promise<string>
   /**
    * Connect to MetaMask (if not already connected) and sign a message containing nonce and expiration.
    * Returns the signature along with the address and chainId that were used to sign.
    * 
    * @param nonce - A unique nonce for this signing request
-   * @param exp - Expiration timestamp (as bigint)
+   * @param exp - Expiration timestamp (as Int64)
    * @returns Promise resolving to ConnectSignResult containing signature, address, and chainId
    */
-  connectSign(nonce: string, exp: bigint): Promise<ConnectSignResult>
+  connectSign(nonce: string, exp: Int64): Promise<ConnectSignResult>
   /**
    * Get the currently connected wallet address.
    * Returns null if not connected.
@@ -43,5 +71,5 @@ export interface NitroMetamask extends HybridObject<{ ios: 'swift', android: 'ko
    * Get the current chain ID.
    * Returns null if not connected.
    */
-  getChainId(): Promise<bigint | null>
+  getChainId(): Promise<Int64 | null>
 }

package/scripts/verify-16k-page-alignment.py

@@ -1,117 +0,0 @@
-#!/usr/bin/env python3
-"""
-Verify 16 KB ELF program-header alignment for Google Play (PT_LOAD p_align).
-
-Uses NDK llvm-readobj (reliable). readelf(1) column positions vary by version;
-do not parse readelf -l by $NF.
-"""
-from __future__ import annotations
-
-import os
-import re
-import shutil
-import subprocess
-import sys
-
-MIN_ALIGN = 16 * 1024
-
-
-def find_llvm_readobj() -> str | None:
-    env = os.environ.get("ANDROID_NDK_HOME") or os.environ.get("ANDROID_NDK_ROOT")
-    if env:
-        prebuilt = os.path.join(env, "toolchains", "llvm", "prebuilt")
-        if os.path.isdir(prebuilt):
-            for host in (
-                "linux-x86_64",
-                "darwin-x86_64",
-                "darwin-arm64",
-                "windows-x86_64",
-            ):
-                cand = os.path.join(prebuilt, host, "bin", "llvm-readobj")
-                if os.path.isfile(cand):
-                    return cand
-    sdk = os.environ.get("ANDROID_SDK_ROOT") or os.environ.get("ANDROID_HOME")
-    if sdk:
-        for ver in ("28.2.13676358",):
-            for host in ("linux-x86_64", "windows-x86_64", "darwin-x86_64"):
-                cand = os.path.join(
-                    sdk, "ndk", ver, "toolchains", "llvm", "prebuilt", host, "bin", "llvm-readobj"
-                )
-                if os.path.isfile(cand):
-                    return cand
-    return shutil.which("llvm-readobj")
-
-
-def verify_so(llvm_readobj: str, path: str) -> bool:
-    try:
-        out = subprocess.check_output(
-            [llvm_readobj, "--program-headers", path],
-            text=True,
-            stderr=subprocess.DEVNULL,
-        )
-    except (subprocess.CalledProcessError, FileNotFoundError) as e:
-        print(f"ERROR: llvm-readobj failed for {path}: {e}", file=sys.stderr)
-        return False
-
-    saw_nonzero = False
-    # Each "ProgramHeader {" block: match PT_LOAD and its Alignment (not readelf columns).
-    for block in out.split("ProgramHeader {")[1:]:
-        if "Type: PT_LOAD" not in block:
-            continue
-        m = re.search(r"Alignment:\s*(\d+)", block)
-        if not m:
-            continue
-        a = int(m.group(1))
-        if a == 0:
-            # p_align 0 = default; other LOADs carry explicit alignment on 16K builds
-            continue
-        saw_nonzero = True
-        if a < MIN_ALIGN:
-            print(
-                f"FAIL {path}: PT_LOAD Alignment {a} < {MIN_ALIGN}",
-                file=sys.stderr,
-            )
-            return False
-
-    if not saw_nonzero:
-        print(
-            f"FAIL {path}: no PT_LOAD with non-zero Alignment (unexpected for .so)",
-            file=sys.stderr,
-        )
-        return False
-    return True
-
-
-def main() -> int:
-    if len(sys.argv) < 2:
-        print("Usage: verify-16k-page-alignment.py <shared-object> [...]", file=sys.stderr)
-        return 2
-
-    lr = find_llvm_readobj()
-    if not lr:
-        print(
-            "ERROR: llvm-readobj not found. Set ANDROID_NDK_HOME or install Android NDK.",
-            file=sys.stderr,
-        )
-        return 2
-
-    ok = True
-    for path in sys.argv[1:]:
-        if not os.path.isfile(path):
-            print(f"ERROR: not a file: {path}", file=sys.stderr)
-            return 1
-        print(f"Checking: {path}")
-        if not verify_so(lr, path):
-            ok = False
-        else:
-            print(f"  OK (llvm-readobj PT_LOAD Alignment >= {MIN_ALIGN} where specified)")
-
-    if not ok:
-        print("verify-16k-page-alignment: FAILED", file=sys.stderr)
-        return 1
-    print("verify-16k-page-alignment: all checks passed")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/verify-16k-page-alignment.sh

@@ -1,5 +0,0 @@
-#!/usr/bin/env bash
-# Thin wrapper; real check is scripts/verify-16k-page-alignment.py (llvm-readobj).
-set -euo pipefail
-ROOT="$(cd "$(dirname "$0")/.." && pwd)"
-exec python3 "$ROOT/scripts/verify-16k-page-alignment.py" "$@"