@agent-cards/wallet-react-native 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @agent-cards/wallet-react-native
+
+The Agentcard wallet as a React Native component: your users add cards and
+approve agent payments without leaving your app. Card numbers never touch your
+code — capture runs on Agentcard's hosted surface inside the WebView.
+
+Same integration shape as the web SDK: your server creates a wallet link
+(`POST /api/v2/wallet_links`), your app renders the component.
+
+```tsx
+import { AgentcardWallet } from "@agent-cards/wallet-react-native";
+
+<AgentcardWallet
+  link={link.url}
+  pay={{ merchant: "DoorDash", amountCents: 2350 }}
+  onSuccess={(d) => d.type === "payment_completed" && markOrderPaid()}
+  onTokenExpired={() => refreshLink()}
+  onEvent={(name, data) => analytics.capture(name, data)}
+/>
+```
+
+Requires `react-native-webview`. Bank approvals open in the system browser
+(`open_url`); everything else stays in the sheet.
+
+**Note on adding cards inside React Native:** the add-card ceremony ends in a
+card-network passkey. WKWebView-based WebViews handle it on iOS 17+, but if
+your target matrix is broader, run the add-card step through a texted wallet
+link (the hosted page or App Clip) and use this component for the wallet and
+pay flows.
+For fully native iOS, use `AgentcardWalletKit` instead.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@agent-cards/wallet-react-native",
+  "version": "0.1.0",
+  "description": "Drop the Agentcard wallet into a React Native app: add cards, show the wallet, approve agent payments.",
+  "main": "src/index.tsx",
+  "types": "src/index.tsx",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "license": "MIT",
+  "homepage": "https://docs.agentcard.sh/platforms/react-native",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tiny-agent-company/tiny-agent-company.git",
+    "directory": "apps/agent-cards/packages/wallet-react-native"
+  },
+  "keywords": [
+    "agentcard",
+    "wallet",
+    "react-native",
+    "payments",
+    "virtual-cards",
+    "ai-agents"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.73",
+    "react-native-webview": ">=13"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "react": "18.2.0",
+    "react-native": "0.74.0",
+    "react-native-webview": "14.0.1",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/index.tsx

@@ -0,0 +1,151 @@
+// @agent-cards/wallet-react-native — the Agentcard wallet as a React Native
+// component. The RN twin of the web SDK (public/js/v1/agentcard.js) and the
+// native iOS kit (AgentcardWalletKit): same wallet-link token in, same event
+// vocabulary out.
+//
+// It renders the hosted wallet sheet in a WebView and speaks the SDK bridge
+// over react-native-webview's message channel (the page detects
+// window.ReactNativeWebView and posts the same envelopes it posts to an
+// iframe host). Bank-approval pages open in the system browser via open_url —
+// they refuse to render inside webviews we don't control.
+
+import { useCallback, useMemo, useRef } from "react";
+import { Linking, StyleSheet, type StyleProp, type ViewStyle } from "react-native";
+import { WebView, type WebViewMessageEvent } from "react-native-webview";
+
+const DEFAULT_BASE = "https://app.agentcard.sh";
+
+export type AgentcardPayIntent = {
+  merchant?: string;
+  amountCents: number;
+};
+
+export type AgentcardSuccess =
+  | { type: "card_attached"; cards: Array<{ id: string; last4: string; network: string | null }> }
+  | { type: "payment_completed"; merchant: string | null; amount_cents: number | null };
+
+export type AgentcardWalletProps = {
+  /** The wallet link from POST /api/v2/wallet_links — its url or raw token. */
+  link: string;
+  /** Open the pay sheet for a specific payment instead of the wallet. */
+  pay?: AgentcardPayIntent;
+  /** Override for staging/previews. Defaults to https://app.agentcard.sh. */
+  baseUrl?: string;
+  onSuccess?: (data: AgentcardSuccess) => void;
+  /** The link or its 1h session died — create a fresh link and swap `link`. */
+  onTokenExpired?: () => void;
+  /** Every bridge event, for analytics (ready, step_changed, success, …). */
+  onEvent?: (name: string, data: Record<string, unknown>) => void;
+  /** Override how bank-approval URLs open. Default: Linking.openURL. */
+  onOpenUrl?: (url: string) => void;
+  style?: StyleProp<ViewStyle>;
+};
+
+/** Accept a raw wallet-link token or the full texted URL (…/w/<token>). */
+function extractToken(value: string): string | null {
+  if (!value) return null;
+  if (!value.includes("://")) return value;
+  try {
+    const segments = new URL(value).pathname.split("/").filter(Boolean);
+    return segments.length ? decodeURIComponent(segments[segments.length - 1]) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function AgentcardWallet({
+  link,
+  pay,
+  baseUrl = DEFAULT_BASE,
+  onSuccess,
+  onTokenExpired,
+  onEvent,
+  onOpenUrl,
+  style,
+}: AgentcardWalletProps) {
+  const uri = useMemo(() => {
+    const params = new URLSearchParams();
+    params.set("sdk", "1");
+    const token = extractToken(link);
+    if (token) params.set("link_token", token);
+    if (pay) {
+      if (pay.merchant) params.set("merchant", pay.merchant);
+      params.set("amount", String(pay.amountCents));
+    }
+    return `${baseUrl.replace(/\/+$/, "")}/embed/wallet?${params.toString()}`;
+  }, [link, pay, baseUrl]);
+
+  // Late messages from a dying WebView (e.g. right after the host swapped the
+  // link) must not fire stale callbacks against the new state.
+  const currentUri = useRef(uri);
+  currentUri.current = uri;
+
+  const handleMessage = useCallback(
+    (event: WebViewMessageEvent) => {
+      // Stale-closure session gate, independent of nativeEvent.url: this
+      // closure captures the session URI it was created for (uri is a dep),
+      // and a swapped link both remounts the keyed WebView and moves
+      // currentUri forward. A dying WebView delivers its queued messages to
+      // the OLD closure — whose captured uri no longer matches — so stale
+      // success / token_expired / open_url die here even when the platform
+      // drops nativeEvent.url (which would bypass a URL-only check). The
+      // parent component itself never unmounts on a swap, so an instance
+      // liveness flag cannot provide this guarantee; the closure identity is
+      // the session identity.
+      if (uri !== currentUri.current) return;
+      // Exact-match the emitting document against the CURRENT session URI: a
+      // dying WebView from a swapped link would otherwise deliver its last
+      // events against the new session's state (a prefix check on baseUrl
+      // passes for every session equally).
+      if (event.nativeEvent.url && event.nativeEvent.url !== currentUri.current) return;
+      let msg: { source?: string; type?: string; data?: Record<string, unknown> };
+      try {
+        msg = JSON.parse(event.nativeEvent.data);
+      } catch {
+        return;
+      }
+      if (msg?.source !== "agentcard-wallet" || typeof msg.type !== "string") return;
+      const data = msg.data ?? {};
+      onEvent?.(msg.type, data);
+      if (msg.type === "success") {
+        onSuccess?.(data as AgentcardSuccess);
+      } else if (msg.type === "token_expired") {
+        onTokenExpired?.();
+      } else if (msg.type === "open_url" && typeof data.url === "string") {
+        if (onOpenUrl) onOpenUrl(data.url);
+        else void Linking.openURL(data.url);
+      }
+    },
+    [uri, baseUrl, onEvent, onSuccess, onTokenExpired, onOpenUrl],
+  );
+
+  return (
+    <WebView
+      // A changed link is a NEW session: remount instead of navigating, so
+      // the old document is torn down rather than left emitting.
+      key={uri}
+      source={{ uri }}
+      onMessage={handleMessage}
+      style={[styles.webview, style]}
+      // The sheet is a fixed-height card flow — page scrolling inside the
+      // WebView just fights the host screen's own scroll.
+      scrollEnabled={false}
+      incognito
+      setSupportMultipleWindows={false}
+      originWhitelist={["https://*", "http://localhost:*"]}
+      // Basis Theory's capture elements are same-page iframes.
+      javaScriptEnabled
+      domStorageEnabled
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  webview: {
+    backgroundColor: "transparent",
+    height: 684,
+    width: "100%",
+  },
+});
+
+export default AgentcardWallet;