@gnosispay/pse-react-native 1.0.1

package/README.md

@@ -0,0 +1,262 @@
+# PSE React Native
+
+A React Native library that provides a secure WebView component for integrating Gnosis Pay card functionality into your mobile applications.
+
+## Features
+
+- 🔒 **Secure WebView Integration** - Safely embed Gnosis Pay card interfaces
+- 📱 **Cross-Platform** - Works on both iOS and Android
+- ⚡ **Easy Integration** - Simple component with minimal setup
+- 🎛️ **Configurable** - Flexible configuration options for different environments
+- 📨 **Message Handling** - Built-in communication between WebView and React Native
+- 🔄 **WebView Controls** - Programmatic navigation and reload capabilities
+
+## Installation
+
+```bash
+npm install pse-react-native
+```
+
+### Peer Dependencies
+
+Make sure you have the required peer dependencies installed:
+
+```bash
+npm install react-native-webview
+```
+
+For Expo projects:
+
+```bash
+npx expo install react-native-webview
+```
+
+## Basic Usage
+
+```tsx
+import React, { useRef } from "react";
+import { View, Button, Alert } from "react-native";
+import { PSEWebView, PSEWebViewRef } from "pse-react-native";
+
+export default function PaymentScreen() {
+  const webViewRef = useRef<PSEWebViewRef>(null);
+
+  const config = {
+    appId: "your-app-id",
+    authToken: "your-auth-token",
+    cardToken: "your-card-token",
+    baseUrl: "https://pse-backend.v2.gnosispay.com", // Optional
+  };
+
+  const handleError = (error: string) => {
+    Alert.alert("Payment Error", error);
+  };
+
+  const handleMessage = (message: any) => {
+    console.log("Received message from WebView:", message);
+    // Handle different message types from the WebView
+  };
+
+  const handleLoad = () => {
+    console.log("WebView loaded successfully");
+  };
+
+  return (
+    <View style={{ flex: 1 }}>
+      <PSEWebView
+        ref={webViewRef}
+        config={config}
+        onError={handleError}
+        onMessage={handleMessage}
+        onLoad={handleLoad}
+        style={{ flex: 1 }}
+        testID="pse-webview"
+      />
+
+      <View style={{ padding: 16 }}>
+        <Button title="Reload" onPress={() => webViewRef.current?.reload()} />
+        <Button title="Go Back" onPress={() => webViewRef.current?.goBack()} />
+      </View>
+    </View>
+  );
+}
+```
+
+## API Reference
+
+### PSEWebView Props
+
+| Prop        | Type                      | Required | Description                                      |
+| ----------- | ------------------------- | -------- | ------------------------------------------------ |
+| `config`    | `PSEConfig`               | ✅       | Configuration object with authentication details |
+| `onError`   | `(error: string) => void` | ❌       | Callback fired when an error occurs              |
+| `onMessage` | `(message: any) => void`  | ❌       | Callback fired when WebView sends a message      |
+| `onLoad`    | `() => void`              | ❌       | Callback fired when WebView finishes loading     |
+| `style`     | `ViewStyle`               | ❌       | Style object for the WebView container           |
+| `testID`    | `string`                  | ❌       | Test identifier for testing frameworks           |
+
+### PSEConfig
+
+```tsx
+interface PSEConfig {
+  appId: string; // Your application identifier
+  authToken: string; // Authentication token
+  cardToken: string; // Card-specific token
+  baseUrl?: string; // Optional: Custom backend URL
+}
+```
+
+### PSEWebViewRef Methods
+
+The component exposes these methods via ref:
+
+```tsx
+interface PSEWebViewRef {
+  goBack: () => void; // Navigate back in WebView history
+  reload: () => void; // Reload the current page
+  postMessage: (message: string) => void; // Send message to WebView
+}
+```
+
+## Message Handling
+
+The WebView can send various message types. Handle them in your `onMessage` callback:
+
+```tsx
+const handleMessage = (message: any) => {
+  switch (message.type) {
+    case "error":
+      console.error("WebView error:", message.message);
+      break;
+    case "success":
+      console.log("Operation successful:", message.data);
+      break;
+    case "navigation":
+      console.log("Navigation event:", message.url);
+      break;
+    default:
+      console.log("Unknown message type:", message);
+  }
+};
+```
+
+## Error Handling
+
+The component provides comprehensive error handling:
+
+```tsx
+const handleError = (error: string) => {
+  // Common error scenarios:
+  // - Network connectivity issues
+  // - Invalid authentication tokens
+  // - WebView loading failures
+  // - Backend service unavailable
+
+  console.error("PSE WebView Error:", error);
+
+  // Show user-friendly error message
+  Alert.alert(
+    "Payment Error",
+    "Unable to load payment interface. Please try again.",
+    [{ text: "OK", onPress: () => webViewRef.current?.reload() }]
+  );
+};
+```
+
+## Configuration Environments
+
+### Production
+
+```tsx
+const config = {
+  appId: "your-prod-app-id",
+  authToken: "your-prod-auth-token",
+  cardToken: "your-prod-card-token",
+  baseUrl: "https://pse-backend.v2.gnosispay.com",
+};
+```
+
+### Staging/Testing
+
+```tsx
+const config = {
+  appId: "your-staging-app-id",
+  authToken: "your-staging-auth-token",
+  cardToken: "your-staging-card-token",
+  baseUrl: "https://pse-backend-staging.v2.gnosispay.com",
+};
+```
+
+## Requirements
+
+- React Native >= 0.70.0
+- React >= 18.0.0
+- react-native-webview >= 13.0.0
+
+## Development
+
+This repository includes an example app to test the library:
+
+### Running the Example App
+
+1. Clone the repository:
+
+   ```bash
+   git clone <repository-url>
+   cd pse-react-native
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Start the example app:
+
+   ```bash
+   npx expo start
+   ```
+
+4. Open the app in your preferred development environment:
+   - iOS Simulator
+   - Android Emulator
+   - Physical device with Expo Go
+
+### Building the Library
+
+```bash
+npm run build
+```
+
+This compiles the TypeScript source files and generates the distribution files in the `lib/` directory.
+
+## Troubleshooting
+
+### Common Issues
+
+**WebView not loading:**
+
+- Verify your authentication tokens are valid
+- Check network connectivity
+- Ensure the baseUrl is accessible
+
+**Authentication errors:**
+
+- Double-check your appId, authToken, and cardToken
+- Verify tokens haven't expired
+- Contact your PSE provider for token validation
+
+**Build errors:**
+
+- Ensure react-native-webview is properly installed
+- Check that peer dependencies match the required versions
+- Clear your Metro cache: `npx expo start --clear`
+
+## License
+
+[Add your license information here]
+
+## Support
+
+For technical support or questions about integration, please contact your PSE provider or create an issue in this repository.

package/lib/PSEWebView.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+import type { PSEWebViewProps, PSEWebViewRef } from "./types";
+declare const PSEWebView: React.ForwardRefExoticComponent<PSEWebViewProps & React.RefAttributes<PSEWebViewRef>>;
+export default PSEWebView;

package/lib/PSEWebView.js

@@ -0,0 +1,64 @@
+import React, { forwardRef, useImperativeHandle, useRef } from "react";
+import { Alert, StyleSheet } from "react-native";
+import { WebView } from "react-native-webview";
+const PSEWebView = forwardRef(({ config, onError, onMessage, onLoad, style, testID }, ref) => {
+    const webViewRef = useRef(null);
+    useImperativeHandle(ref, () => ({
+        goBack: () => {
+            webViewRef.current?.goBack();
+        },
+        reload: () => {
+            webViewRef.current?.reload();
+        },
+        postMessage: (message) => {
+            webViewRef.current?.postMessage(message);
+        },
+    }));
+    const handleWebViewLoad = () => {
+        // Send parameters to webview after it loads
+        const params = {
+            appId: config.appId.trim(),
+            authToken: config.authToken.trim(),
+            cardToken: config.cardToken.trim(),
+        };
+        const message = JSON.stringify(params);
+        webViewRef.current?.postMessage(message);
+        console.log("PSE: Message sent to WebView:", message);
+        onLoad?.();
+    };
+    const handleWebViewMessage = (event) => {
+        try {
+            const data = JSON.parse(event.nativeEvent.data);
+            console.log("PSE: Message from WebView:", data);
+            // Handle error messages from the webview
+            if (data.type === "error") {
+                const errorMessage = data.message || "Unknown WebView error";
+                onError?.(errorMessage);
+                Alert.alert("PSE WebView Error", errorMessage);
+            }
+            // Pass all messages to the parent component
+            onMessage?.(data);
+        }
+        catch (error) {
+            console.log("PSE: Failed to parse WebView message:", error);
+            onError?.("Failed to parse WebView message");
+        }
+    };
+    const handleWebViewError = (syntheticEvent) => {
+        const { nativeEvent } = syntheticEvent;
+        const errorMessage = `Failed to load PSE WebView: ${nativeEvent.description}`;
+        console.error("PSE: WebView Error:", errorMessage);
+        onError?.(errorMessage);
+        Alert.alert("PSE WebView Error", errorMessage);
+    };
+    const baseUrl = config.baseUrl || "https://pse-backend.v2.gnosispay.com";
+    const webViewUrl = `${baseUrl}/native-webview`;
+    return (<WebView ref={webViewRef} source={{ uri: webViewUrl }} style={[styles.webview, style]} startInLoadingState={true} scalesPageToFit={true} onLoad={handleWebViewLoad} onMessage={handleWebViewMessage} onError={handleWebViewError} javaScriptEnabled={true} testID={testID}/>);
+});
+PSEWebView.displayName = "PSEWebView";
+const styles = StyleSheet.create({
+    webview: {
+        flex: 1,
+    },
+});
+export default PSEWebView;

package/lib/PSEWebView.tsx

@@ -0,0 +1,93 @@
+import React, { forwardRef, useImperativeHandle, useRef } from "react";
+import { Alert, StyleSheet } from "react-native";
+import { WebView } from "react-native-webview";
+import type { PSEWebViewProps, PSEWebViewRef } from "./types";
+
+const PSEWebView = forwardRef<PSEWebViewRef, PSEWebViewProps>(
+  ({ config, onError, onMessage, onLoad, style, testID }, ref) => {
+    const webViewRef = useRef<WebView>(null);
+
+    useImperativeHandle(ref, () => ({
+      goBack: () => {
+        webViewRef.current?.goBack();
+      },
+      reload: () => {
+        webViewRef.current?.reload();
+      },
+      postMessage: (message: string) => {
+        webViewRef.current?.postMessage(message);
+      },
+    }));
+
+    const handleWebViewLoad = () => {
+      // Send parameters to webview after it loads
+      const params = {
+        appId: config.appId.trim(),
+        authToken: config.authToken.trim(),
+        cardToken: config.cardToken.trim(),
+      };
+
+      const message = JSON.stringify(params);
+      webViewRef.current?.postMessage(message);
+
+      console.log("PSE: Message sent to WebView:", message);
+      onLoad?.();
+    };
+
+    const handleWebViewMessage = (event: any) => {
+      try {
+        const data = JSON.parse(event.nativeEvent.data);
+        console.log("PSE: Message from WebView:", data);
+
+        // Handle error messages from the webview
+        if (data.type === "error") {
+          const errorMessage = data.message || "Unknown WebView error";
+          onError?.(errorMessage);
+          Alert.alert("PSE WebView Error", errorMessage);
+        }
+
+        // Pass all messages to the parent component
+        onMessage?.(data);
+      } catch (error) {
+        console.log("PSE: Failed to parse WebView message:", error);
+        onError?.("Failed to parse WebView message");
+      }
+    };
+
+    const handleWebViewError = (syntheticEvent: any) => {
+      const { nativeEvent } = syntheticEvent;
+      const errorMessage = `Failed to load PSE WebView: ${nativeEvent.description}`;
+      console.error("PSE: WebView Error:", errorMessage);
+      onError?.(errorMessage);
+      Alert.alert("PSE WebView Error", errorMessage);
+    };
+
+    const baseUrl = config.baseUrl || "https://pse-backend.v2.gnosispay.com";
+    const webViewUrl = `${baseUrl}/native-webview`;
+
+    return (
+      <WebView
+        ref={webViewRef}
+        source={{ uri: webViewUrl }}
+        style={[styles.webview, style]}
+        startInLoadingState={true}
+        scalesPageToFit={true}
+        onLoad={handleWebViewLoad}
+        onMessage={handleWebViewMessage}
+        onError={handleWebViewError}
+        javaScriptEnabled={true}
+        testID={testID}
+      />
+    );
+  }
+);
+
+PSEWebView.displayName = "PSEWebView";
+
+const styles = StyleSheet.create({
+  webview: {
+    flex: 1,
+  },
+});
+
+export default PSEWebView;

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export { default as PSEWebView } from "./PSEWebView";
+export type { PSEConfig, PSEWebViewProps, PSEWebViewRef } from "./types";

package/lib/index.js

@@ -0,0 +1 @@
+export { default as PSEWebView } from "./PSEWebView";

package/lib/index.ts

@@ -0,0 +1,2 @@
+export { default as PSEWebView } from "./PSEWebView";
+export type { PSEConfig, PSEWebViewProps, PSEWebViewRef } from "./types";

package/lib/types.d.ts

@@ -0,0 +1,19 @@
+export interface PSEConfig {
+    appId: string;
+    authToken: string;
+    cardToken: string;
+    baseUrl?: string;
+}
+export interface PSEWebViewProps {
+    config: PSEConfig;
+    onError?: (error: string) => void;
+    onMessage?: (message: any) => void;
+    onLoad?: () => void;
+    style?: any;
+    testID?: string;
+}
+export interface PSEWebViewRef {
+    goBack: () => void;
+    reload: () => void;
+    postMessage: (message: string) => void;
+}

package/lib/types.ts

@@ -0,0 +1,21 @@
+export interface PSEConfig {
+  appId: string;
+  authToken: string;
+  cardToken: string;
+  baseUrl?: string;
+}
+
+export interface PSEWebViewProps {
+  config: PSEConfig;
+  onError?: (error: string) => void;
+  onMessage?: (message: any) => void;
+  onLoad?: () => void;
+  style?: any;
+  testID?: string;
+}
+
+export interface PSEWebViewRef {
+  goBack: () => void;
+  reload: () => void;
+  postMessage: (message: string) => void;
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@gnosispay/pse-react-native",
+  "main": "lib/index.js",
+  "version": "1.0.1",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "expo start",
+    "android": "expo start --android",
+    "ios": "expo start --ios",
+    "web": "expo start --web",
+    "lint": "expo lint",
+    "build": "tsc --project tsconfig.lib.json",
+    "prepublishOnly": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gnosispay/pse-react-native"
+  },
+  "keywords": [
+    "react-native",
+    "pse",
+    "gnosis-pay",
+    "webview",
+    "payment",
+    "card",
+    "iframe"
+  ],
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.70.0",
+    "react-native-webview": ">=13.0.0"
+  },
+  "dependencies": {
+    "@expo/vector-icons": "^14.1.0",
+    "@react-navigation/bottom-tabs": "^7.3.10",
+    "@react-navigation/elements": "^2.3.8",
+    "@react-navigation/native": "^7.1.6",
+    "expo": "~53.0.20",
+    "expo-blur": "~14.1.5",
+    "expo-constants": "~17.1.7",
+    "expo-font": "~13.3.2",
+    "expo-haptics": "~14.1.4",
+    "expo-image": "~2.4.0",
+    "expo-linking": "~7.1.7",
+    "expo-router": "~5.1.4",
+    "expo-splash-screen": "~0.30.10",
+    "expo-status-bar": "~2.2.3",
+    "expo-symbols": "~0.4.5",
+    "expo-system-ui": "~5.0.10",
+    "expo-web-browser": "~14.2.0",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "react-native": "0.79.5",
+    "react-native-gesture-handler": "~2.24.0",
+    "react-native-reanimated": "~3.17.4",
+    "react-native-safe-area-context": "5.4.0",
+    "react-native-screens": "~4.11.1",
+    "react-native-web": "~0.20.0",
+    "react-native-webview": "13.13.5"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.25.2",
+    "@types/react": "~19.0.10",
+    "typescript": "~5.8.3",
+    "eslint": "^9.25.0",
+    "eslint-config-expo": "~9.2.0"
+  }
+}