@alien_org/react 0.0.11-beta

package/dist/index.cjs

@@ -0,0 +1,546 @@
+let _alien_org_bridge = require("@alien_org/bridge");
+let _alien_org_contract = require("@alien_org/contract");
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+
+//#region src/context.tsx
+const AlienContext = (0, react.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 = (0, react.useMemo)(() => {
+		const launchParams = (0, _alien_org_bridge.getLaunchParams)();
+		return {
+			authToken: launchParams?.authToken,
+			contractVersion: launchParams?.contractVersion,
+			isBridgeAvailable: (0, _alien_org_bridge.isBridgeAvailable)()
+		};
+	}, []);
+	(0, react.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]);
+	(0, react.useEffect)(() => {
+		if (value.isBridgeAvailable) (0, _alien_org_bridge.send)("app:ready", {});
+	}, [value.isBridgeAvailable]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.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 = (0, react.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 = (0, react.useRef)(callback);
+	callbackRef.current = callback;
+	const { isBridgeAvailable: isBridgeAvailable$1 } = useAlien();
+	(0, react.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 (0, _alien_org_bridge.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 ? (0, _alien_org_contract.isMethodSupported)(method, contractVersion) : true,
+		contractVersion,
+		minVersion: (0, _alien_org_contract.getMethodMinVersion)(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 (0, react.useMemo)(() => (0, _alien_org_bridge.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] = (0, react.useState)({
+		data: void 0,
+		error: void 0,
+		isLoading: false
+	});
+	const supported = contractVersion ? (0, _alien_org_contract.isMethodSupported)(method, contractVersion) : true;
+	const execute = (0, react.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 && !(0, _alien_org_contract.isMethodSupported)(method, contractVersion)) {
+				const error = new MethodNotSupportedError(method, contractVersion, (0, _alien_org_contract.getMethodMinVersion)(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 (0, _alien_org_bridge.request)(method, params, responseEvent, requestOptions);
+			setState({
+				data: response,
+				error: void 0,
+				isLoading: false
+			});
+			return {
+				data: response,
+				error: void 0
+			};
+		} catch (err) {
+			if (err instanceof _alien_org_bridge.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 = (0, react.useCallback)(() => {
+		setState({
+			data: void 0,
+			error: void 0,
+			isLoading: false
+		});
+	}, []);
+	return (0, react.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 = (0, react.useRef)({
+		onPaid,
+		onCancelled,
+		onFailed,
+		onStatusChange
+	});
+	callbacksRef.current = {
+		onPaid,
+		onCancelled,
+		onFailed,
+		onStatusChange
+	};
+	const [state, setState] = (0, react.useState)({ status: "idle" });
+	const supported = contractVersion ? (0, _alien_org_contract.isMethodSupported)("payment:request", contractVersion) : true;
+	const updateState = (0, react.useCallback)((newState) => {
+		setState(newState);
+		callbacksRef.current.onStatusChange?.(newState.status);
+	}, []);
+	const pay = (0, react.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 && !(0, _alien_org_contract.isMethodSupported)("payment:request", contractVersion)) {
+			const error = new MethodNotSupportedError("payment:request", contractVersion, (0, _alien_org_contract.getMethodMinVersion)("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 (0, _alien_org_bridge.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 _alien_org_bridge.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 = (0, react.useCallback)(() => {
+		updateState({ status: "idle" });
+	}, [updateState]);
+	return (0, react.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
+exports.AlienProvider = AlienProvider;
+exports.BridgeError = _alien_org_bridge.BridgeError;
+exports.BridgeTimeoutError = _alien_org_bridge.BridgeTimeoutError;
+exports.BridgeUnavailableError = _alien_org_bridge.BridgeUnavailableError;
+exports.BridgeWindowUnavailableError = _alien_org_bridge.BridgeWindowUnavailableError;
+exports.MethodNotSupportedError = MethodNotSupportedError;
+exports.ReactSDKError = ReactSDKError;
+Object.defineProperty(exports, 'getMethodMinVersion', {
+  enumerable: true,
+  get: function () {
+    return _alien_org_contract.getMethodMinVersion;
+  }
+});
+Object.defineProperty(exports, 'isMethodSupported', {
+  enumerable: true,
+  get: function () {
+    return _alien_org_contract.isMethodSupported;
+  }
+});
+Object.defineProperty(exports, 'send', {
+  enumerable: true,
+  get: function () {
+    return _alien_org_bridge.send;
+  }
+});
+exports.useAlien = useAlien;
+exports.useEvent = useEvent;
+exports.useIsMethodSupported = useIsMethodSupported;
+exports.useLaunchParams = useLaunchParams;
+exports.useMethod = useMethod;
+exports.usePayment = usePayment;