@alien_org/react 0.0.11-beta

package/dist/index.mjs

@@ -0,0 +1,516 @@
+import { BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, getLaunchParams, isBridgeAvailable, on, request, send, send as send$1 } from "@alien_org/bridge";
+import { getMethodMinVersion, getMethodMinVersion as getMethodMinVersion$1, isMethodSupported, isMethodSupported as isMethodSupported$1 } from "@alien_org/contract";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+
+//#region src/context.tsx
+const AlienContext = createContext(null);
+/**
+* Provider component that initializes the Alien miniapp context.
+* Must wrap your app to use Alien hooks.
+*
+* @example
+* ```tsx
+* import { AlienProvider } from '@alien_org/react';
+*
+* function App() {
+*   return (
+*     <AlienProvider>
+*       <MyMiniapp />
+*     </AlienProvider>
+*   );
+* }
+* ```
+*/
+function AlienProvider({ children }) {
+	const value = useMemo(() => {
+		const launchParams = getLaunchParams();
+		return {
+			authToken: launchParams?.authToken,
+			contractVersion: launchParams?.contractVersion,
+			isBridgeAvailable: isBridgeAvailable()
+		};
+	}, []);
+	useEffect(() => {
+		if (!value.isBridgeAvailable) console.warn("[@alien_org/react] Bridge is not available. Running in dev mode? The SDK will handle errors gracefully, but bridge communication will not work.");
+	}, [value.isBridgeAvailable]);
+	useEffect(() => {
+		if (value.isBridgeAvailable) send$1("app:ready", {});
+	}, [value.isBridgeAvailable]);
+	return /* @__PURE__ */ jsx(AlienContext.Provider, {
+		value,
+		children
+	});
+}
+
+//#endregion
+//#region src/errors.ts
+/**
+* Base class for all React SDK errors.
+*/
+var ReactSDKError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ReactSDKError";
+	}
+};
+/**
+* Error thrown when a method is not supported by the current contract version.
+*/
+var MethodNotSupportedError = class extends ReactSDKError {
+	method;
+	contractVersion;
+	minVersion;
+	constructor(method, contractVersion, minVersion) {
+		const message = minVersion ? `Method "${method}" requires version ${minVersion}, but host provides ${contractVersion ?? "unknown"}` : `Method "${method}" is not supported`;
+		super(message);
+		this.name = "MethodNotSupportedError";
+		this.method = method;
+		this.contractVersion = contractVersion;
+		this.minVersion = minVersion;
+	}
+};
+
+//#endregion
+//#region src/hooks/useAlien.ts
+/**
+* Hook to access the Alien context.
+* Must be used within an AlienProvider.
+*
+* For additional launch params (platform, startParam, hostAppVersion),
+* use the `useLaunchParams` hook.
+*
+* @example
+* ```tsx
+* const { authToken, contractVersion, isBridgeAvailable } = useAlien();
+* ```
+*/
+function useAlien() {
+	const context = useContext(AlienContext);
+	if (!context) throw new Error("useAlien must be used within an AlienProvider");
+	return context;
+}
+
+//#endregion
+//#region src/hooks/useEvent.ts
+/**
+* Hook to subscribe to bridge events.
+* Automatically handles subscription cleanup on unmount.
+*
+* @param event - The event name to subscribe to.
+* @param callback - The callback to invoke when the event is received.
+*
+* @example
+* ```tsx
+* import { useEvent } from '@alien_org/react';
+*
+* function MyComponent() {
+*   useEvent('miniapp:close', () => {
+*     // Cleanup before miniapp closes
+*     saveState();
+*   });
+*
+*   useEvent('host.back.button:clicked', () => {
+*     // Handle back button press
+*     navigateBack();
+*   });
+*
+*   return <div>Listening for events...</div>;
+* }
+* ```
+*/
+function useEvent(event, callback) {
+	const callbackRef = useRef(callback);
+	callbackRef.current = callback;
+	const { isBridgeAvailable: isBridgeAvailable$1 } = useAlien();
+	useEffect(() => {
+		if (!isBridgeAvailable$1) {
+			console.warn("[@alien_org/react] Bridge is not available. Event listener will not be set up. Running in dev mode?");
+			return;
+		}
+		const handler = (payload) => {
+			callbackRef.current(payload);
+		};
+		try {
+			return on(event, handler);
+		} catch (error) {
+			console.warn("[@alien_org/react] Failed to set up event listener:", error instanceof Error ? error.message : String(error));
+			return;
+		}
+	}, [event, isBridgeAvailable$1]);
+}
+
+//#endregion
+//#region src/hooks/useIsMethodSupported.ts
+/**
+* Hook to check if a method is supported by the host app's contract version.
+*
+* @param method - The method name to check.
+* @returns Object with `supported`, `contractVersion`, and `minVersion`.
+*
+* @example
+* ```tsx
+* import { useMethodSupported } from '@alien_org/react';
+*
+* function MyComponent() {
+*   const { supported, minVersion } = useMethodSupported('payment:request');
+*
+*   if (!supported) {
+*     return <div>This feature requires version {minVersion}</div>;
+*   }
+*
+*   return <div>Feature available!</div>;
+* }
+* ```
+*/
+function useIsMethodSupported(method) {
+	const { contractVersion } = useAlien();
+	return {
+		supported: contractVersion ? isMethodSupported$1(method, contractVersion) : true,
+		contractVersion,
+		minVersion: getMethodMinVersion$1(method)
+	};
+}
+
+//#endregion
+//#region src/hooks/useLaunchParams.ts
+/**
+* Hook to get launch params.
+* Returns undefined if params unavailable (use mockLaunchParamsForDev in dev).
+*
+* @example
+* ```tsx
+* import { useLaunchParams } from '@alien_org/react';
+*
+* function MyComponent() {
+*   const launchParams = useLaunchParams();
+*
+*   if (!launchParams) {
+*     return <div>Running outside Alien App</div>;
+*   }
+*
+*   return <div>Platform: {launchParams.platform}</div>;
+* }
+* ```
+*/
+function useLaunchParams() {
+	return useMemo(() => getLaunchParams(), []);
+}
+
+//#endregion
+//#region src/hooks/useMethod.ts
+/**
+* Hook for making bridge requests with loading/error state management.
+*
+* @param method - The method name to call.
+* @param responseEvent - The event name to listen for the response.
+* @param options - Hook options including version checking.
+* @returns Object with `execute`, `reset`, `data`, `error`, `isLoading`, and `supported`.
+*
+* @example
+* ```tsx
+* import { useMethod } from '@alien_org/react';
+*
+* function PayButton() {
+*   const { execute, data, error, isLoading, supported } = useMethod(
+*     'payment:request',
+*     'payment:response',
+*   );
+*
+*   if (!supported) {
+*     return <div>This feature is not available</div>;
+*   }
+*
+*   const handlePay = async () => {
+*     // Errors are automatically set in the `error` state - no try/catch needed!
+*     const { error, data } = await execute({
+*       recipient: 'wallet-123',
+*       amount: '100',
+*       token: 'SOL',
+*       network: 'solana',
+*       invoice: 'inv-123',
+*     });
+*     if (error) {
+*         console.error(error);
+*         return;
+*     }
+*     if (data) {
+*       console.log('Success:', data);
+*     }
+*   };
+*
+*   if (isLoading) return <button disabled>Loading...</button>;
+*   if (error) return <div>Error: {error.message}</div>;
+*   if (data) return <div>Payment complete!</div>;
+*
+*   return <button onClick={handlePay}>Pay</button>;
+* }
+* ```
+*/
+function useMethod(method, responseEvent, options = {}) {
+	const { checkVersion = true } = options;
+	const { contractVersion, isBridgeAvailable: isBridgeAvailable$1 } = useAlien();
+	const [state, setState] = useState({
+		data: void 0,
+		error: void 0,
+		isLoading: false
+	});
+	const supported = contractVersion ? isMethodSupported$1(method, contractVersion) : true;
+	const execute = useCallback(async (params, requestOptions) => {
+		if (!isBridgeAvailable$1) {
+			const error = /* @__PURE__ */ new Error("Bridge is not available. Running in dev mode? Bridge communication will not work.");
+			console.warn("[@alien_org/react]", error.message);
+			setState({
+				data: void 0,
+				error,
+				isLoading: false
+			});
+			return {
+				data: void 0,
+				error
+			};
+		}
+		if (checkVersion) {
+			if (contractVersion && !isMethodSupported$1(method, contractVersion)) {
+				const error = new MethodNotSupportedError(method, contractVersion, getMethodMinVersion$1(method));
+				setState({
+					data: void 0,
+					error,
+					isLoading: false
+				});
+				return {
+					data: void 0,
+					error
+				};
+			}
+		}
+		setState({
+			data: void 0,
+			error: void 0,
+			isLoading: true
+		});
+		try {
+			const response = await request(method, params, responseEvent, requestOptions);
+			setState({
+				data: response,
+				error: void 0,
+				isLoading: false
+			});
+			return {
+				data: response,
+				error: void 0
+			};
+		} catch (err) {
+			if (err instanceof BridgeError) {
+				console.warn("[@alien_org/react] Bridge error:", err.message);
+				setState({
+					data: void 0,
+					error: err,
+					isLoading: false
+				});
+				return {
+					data: void 0,
+					error: err
+				};
+			}
+			const error = err instanceof Error ? err : new Error(String(err));
+			setState({
+				data: void 0,
+				error,
+				isLoading: false
+			});
+			return {
+				data: void 0,
+				error
+			};
+		}
+	}, [
+		method,
+		responseEvent,
+		checkVersion,
+		contractVersion,
+		isBridgeAvailable$1
+	]);
+	const reset = useCallback(() => {
+		setState({
+			data: void 0,
+			error: void 0,
+			isLoading: false
+		});
+	}, []);
+	return useMemo(() => ({
+		...state,
+		execute,
+		reset,
+		supported
+	}), [
+		state,
+		execute,
+		reset,
+		supported
+	]);
+}
+
+//#endregion
+//#region src/hooks/usePayment.ts
+/**
+* Hook for handling payments with full state management.
+*
+* Provides an easy-to-use interface for initiating payments and reacting
+* to status changes. Automatically handles loading states, errors, and
+* version checking.
+*
+* @param options - Optional configuration and callbacks.
+* @returns Payment state and methods.
+*
+* @example
+* ```tsx
+* import { usePayment } from '@alien_org/react';
+*
+* function BuyButton({ orderId }: { orderId: string }) {
+*   const {
+*     pay,
+*     isLoading,
+*     isPaid,
+*     txHash,
+*     error,
+*   } = usePayment({
+*     onPaid: (txHash) => console.log('Paid!', txHash),
+*     onCancelled: () => console.log('Cancelled'),
+*     onFailed: (code) => console.log('Failed:', code),
+*   });
+*
+*   const handleBuy = () => pay({
+*     recipient: 'wallet-address',
+*     amount: '1000000',
+*     token: 'SOL',
+*     network: 'solana',
+*     invoice: orderId,
+*     title: 'Premium Plan',
+*   });
+*
+*   if (isPaid) return <div>Thank you! TX: {txHash}</div>;
+*
+*   return (
+*     <button onClick={handleBuy} disabled={isLoading}>
+*       {isLoading ? 'Processing...' : 'Buy Now'}
+*     </button>
+*   );
+* }
+* ```
+*/
+function usePayment(options = {}) {
+	const { timeout = 12e4, onPaid, onCancelled, onFailed, onStatusChange } = options;
+	const { contractVersion, isBridgeAvailable: isBridgeAvailable$1 } = useAlien();
+	const callbacksRef = useRef({
+		onPaid,
+		onCancelled,
+		onFailed,
+		onStatusChange
+	});
+	callbacksRef.current = {
+		onPaid,
+		onCancelled,
+		onFailed,
+		onStatusChange
+	};
+	const [state, setState] = useState({ status: "idle" });
+	const supported = contractVersion ? isMethodSupported$1("payment:request", contractVersion) : true;
+	const updateState = useCallback((newState) => {
+		setState(newState);
+		callbacksRef.current.onStatusChange?.(newState.status);
+	}, []);
+	const pay = useCallback(async (params) => {
+		if (!isBridgeAvailable$1) {
+			const error = /* @__PURE__ */ new Error("Bridge is not available. Running in dev mode?");
+			console.warn("[@alien_org/react]", error.message);
+			const result = {
+				status: "failed",
+				errorCode: "unknown",
+				error
+			};
+			updateState(result);
+			callbacksRef.current.onFailed?.("unknown", error);
+			return result;
+		}
+		if (contractVersion && !isMethodSupported$1("payment:request", contractVersion)) {
+			const error = new MethodNotSupportedError("payment:request", contractVersion, getMethodMinVersion$1("payment:request"));
+			const result = {
+				status: "failed",
+				errorCode: "unknown",
+				error
+			};
+			updateState(result);
+			callbacksRef.current.onFailed?.("unknown", error);
+			return result;
+		}
+		updateState({ status: "loading" });
+		try {
+			const response = await request("payment:request", params, "payment:response", { timeout });
+			if (response.status === "paid") {
+				const txHash = response.txHash ?? "";
+				const result$1 = {
+					status: "paid",
+					txHash
+				};
+				updateState(result$1);
+				callbacksRef.current.onPaid?.(txHash);
+				return result$1;
+			}
+			if (response.status === "cancelled") {
+				const result$1 = { status: "cancelled" };
+				updateState(result$1);
+				callbacksRef.current.onCancelled?.();
+				return result$1;
+			}
+			const errorCode = response.errorCode ?? "unknown";
+			const result = {
+				status: "failed",
+				errorCode
+			};
+			updateState(result);
+			callbacksRef.current.onFailed?.(errorCode);
+			return result;
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			if (err instanceof BridgeError) console.warn("[@alien_org/react] Bridge error:", err.message);
+			const result = {
+				status: "failed",
+				errorCode: "unknown",
+				error
+			};
+			updateState(result);
+			callbacksRef.current.onFailed?.("unknown", error);
+			return result;
+		}
+	}, [
+		isBridgeAvailable$1,
+		contractVersion,
+		timeout,
+		updateState
+	]);
+	const reset = useCallback(() => {
+		updateState({ status: "idle" });
+	}, [updateState]);
+	return useMemo(() => ({
+		status: state.status,
+		isLoading: state.status === "loading",
+		isPaid: state.status === "paid",
+		isCancelled: state.status === "cancelled",
+		isFailed: state.status === "failed",
+		txHash: state.txHash,
+		errorCode: state.errorCode,
+		error: state.error,
+		pay,
+		reset,
+		supported
+	}), [
+		state,
+		pay,
+		reset,
+		supported
+	]);
+}
+
+//#endregion
+export { AlienProvider, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, MethodNotSupportedError, ReactSDKError, getMethodMinVersion, isMethodSupported, send, useAlien, useEvent, useIsMethodSupported, useLaunchParams, useMethod, usePayment };

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@alien_org/react",
+  "version": "0.0.11-beta",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alien-id/miniapp-sdk.git",
+    "directory": "packages/react"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@alien_org/bridge": "workspace:*",
+    "@alien_org/contract": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": "^18 || ^19",
+    "typescript": "^5"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.8",
+    "react": "^19.1.0",
+    "tsdown": "^0.18.1"
+  }
+}