@alien_org/react 0.2.0 → 0.2.2

package/dist/index.cjs

@@ -4,6 +4,7 @@ let react = require("react");
 let react_jsx_runtime = require("react/jsx-runtime");
 
 //#region src/context.tsx
+const useIsomorphicLayoutEffect$1 = typeof window !== "undefined" ? react.useLayoutEffect : react.useEffect;
 const AlienContext = (0, react.createContext)(null);
 /**
 * Provider component that initializes the Alien miniapp context.
@@ -22,21 +23,33 @@ const AlienContext = (0, react.createContext)(null);
 * }
 * ```
 */
-function AlienProvider({ children }) {
-	const value = (0, react.useMemo)(() => {
+function AlienProvider({ children, autoReady = true }) {
+	const readySent = (0, react.useRef)(false);
+	const ready = (0, react.useCallback)(() => {
+		if (readySent.current) return;
+		readySent.current = true;
+		if ((0, _alien_org_bridge.isBridgeAvailable)()) (0, _alien_org_bridge.send)("app:ready", {});
+	}, []);
+	const [value, setValue] = (0, react.useState)(() => ({
+		authToken: void 0,
+		contractVersion: void 0,
+		isBridgeAvailable: false,
+		ready
+	}));
+	useIsomorphicLayoutEffect$1(() => {
 		const launchParams = (0, _alien_org_bridge.getLaunchParams)();
-		return {
+		const bridgeAvailable = (0, _alien_org_bridge.isBridgeAvailable)();
+		setValue({
 			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]);
+			isBridgeAvailable: bridgeAvailable,
+			ready
+		});
+		if (!bridgeAvailable) 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.");
+	}, [ready]);
 	(0, react.useEffect)(() => {
-		if (value.isBridgeAvailable) (0, _alien_org_bridge.send)("app:ready", {});
-	}, [value.isBridgeAvailable]);
+		if (autoReady) ready();
+	}, [autoReady, ready]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AlienContext.Provider, {
 		value,
 		children
@@ -252,6 +265,7 @@ function useIsMethodSupported(method) {
 
 //#endregion
 //#region src/hooks/useLaunchParams.ts
+const useIsomorphicLayoutEffect = typeof window !== "undefined" ? react.useLayoutEffect : react.useEffect;
 /**
 * Hook to get launch params.
 * Returns undefined if params unavailable (use mockLaunchParamsForDev in dev).
@@ -272,7 +286,11 @@ function useIsMethodSupported(method) {
 * ```
 */
 function useLaunchParams() {
-	return (0, react.useMemo)(() => (0, _alien_org_bridge.getLaunchParams)(), []);
+	const [params, setParams] = (0, react.useState)(void 0);
+	useIsomorphicLayoutEffect(() => {
+		setParams((0, _alien_org_bridge.getLaunchParams)());
+	}, []);
+	return params;
 }
 
 //#endregion

package/dist/index.d.cts

@@ -250,8 +250,9 @@ interface Methods {
    * Optional display fields (`title`, `caption`, `iconUrl`, `quantity`)
    * are shown on the payment approval screen.
    *
-   * Set `test: true` for test mode - no real payment is made, but webhooks
-   * are fired with `test: true` flag. Use for development and testing.
+   * Set `test` to a scenario string (e.g. `'paid'`, `'error:insufficient_balance'`)
+   * for test mode - no real payment is made, but the specified scenario is
+   * simulated. Use for development and testing.
    *
    * @since 0.1.1
    * @schema
@@ -317,7 +318,7 @@ interface Methods {
      *
      * | Scenario | Client | Webhook |
      * |----------|--------|---------|
-     * | `true` / `'paid'` | `paid` | `finalized` |
+     * | `'paid'` | `paid` | `finalized` |
      * | `'paid:failed'` | `paid` | `failed` |
      * | `'cancelled'` | `cancelled` | none |
      * | `'error:*'` | `failed` | none |
@@ -343,7 +344,7 @@ interface Methods {
      * @since 0.1.1
      * @schema
      */
-    test?: boolean | PaymentTestScenario;
+    test?: PaymentTestScenario;
   }>>;
   /**
    * Write text to the system clipboard.
@@ -525,9 +526,45 @@ interface AlienContextValue {
    * Whether the bridge is available (running inside Alien App).
    */
   isBridgeAvailable: boolean;
+  /**
+   * Manually signal to the host app that the miniapp is ready.
+   * Only needed when `autoReady` is set to `false`.
+   * Safe to call multiple times — only the first call sends the signal.
+   */
+  ready: () => void;
 }
 interface AlienProviderProps {
   children: ReactNode;
+  /**
+   * Whether to automatically send `app:ready` when the provider mounts.
+   * Defaults to `true`.
+   *
+   * Set to `false` if you need to defer the ready signal (e.g., after
+   * fetching initial data), then call `ready()` from `useAlien()` when done.
+   *
+   * @default true
+   *
+   * @example
+   * ```tsx
+   * // Auto (default) — fires immediately on mount
+   * <AlienProvider>
+   *   <App />
+   * </AlienProvider>
+   *
+   * // Manual — fire when you're ready
+   * <AlienProvider autoReady={false}>
+   *   <App />
+   * </AlienProvider>
+   *
+   * function App() {
+   *   const { ready } = useAlien();
+   *   useEffect(() => {
+   *     fetchData().then(() => ready());
+   *   }, []);
+   * }
+   * ```
+   */
+  autoReady?: boolean;
 }
 /**
  * Provider component that initializes the Alien miniapp context.
@@ -547,7 +584,8 @@ interface AlienProviderProps {
  * ```
  */
 declare function AlienProvider({
-  children
+  children,
+  autoReady
 }: AlienProviderProps): ReactNode;
 //#endregion
 //#region src/errors.d.ts

package/dist/index.d.mts

@@ -250,8 +250,9 @@ interface Methods {
    * Optional display fields (`title`, `caption`, `iconUrl`, `quantity`)
    * are shown on the payment approval screen.
    *
-   * Set `test: true` for test mode - no real payment is made, but webhooks
-   * are fired with `test: true` flag. Use for development and testing.
+   * Set `test` to a scenario string (e.g. `'paid'`, `'error:insufficient_balance'`)
+   * for test mode - no real payment is made, but the specified scenario is
+   * simulated. Use for development and testing.
    *
    * @since 0.1.1
    * @schema
@@ -317,7 +318,7 @@ interface Methods {
      *
      * | Scenario | Client | Webhook |
      * |----------|--------|---------|
-     * | `true` / `'paid'` | `paid` | `finalized` |
+     * | `'paid'` | `paid` | `finalized` |
      * | `'paid:failed'` | `paid` | `failed` |
      * | `'cancelled'` | `cancelled` | none |
      * | `'error:*'` | `failed` | none |
@@ -343,7 +344,7 @@ interface Methods {
      * @since 0.1.1
      * @schema
      */
-    test?: boolean | PaymentTestScenario;
+    test?: PaymentTestScenario;
   }>>;
   /**
    * Write text to the system clipboard.
@@ -525,9 +526,45 @@ interface AlienContextValue {
    * Whether the bridge is available (running inside Alien App).
    */
   isBridgeAvailable: boolean;
+  /**
+   * Manually signal to the host app that the miniapp is ready.
+   * Only needed when `autoReady` is set to `false`.
+   * Safe to call multiple times — only the first call sends the signal.
+   */
+  ready: () => void;
 }
 interface AlienProviderProps {
   children: ReactNode;
+  /**
+   * Whether to automatically send `app:ready` when the provider mounts.
+   * Defaults to `true`.
+   *
+   * Set to `false` if you need to defer the ready signal (e.g., after
+   * fetching initial data), then call `ready()` from `useAlien()` when done.
+   *
+   * @default true
+   *
+   * @example
+   * ```tsx
+   * // Auto (default) — fires immediately on mount
+   * <AlienProvider>
+   *   <App />
+   * </AlienProvider>
+   *
+   * // Manual — fire when you're ready
+   * <AlienProvider autoReady={false}>
+   *   <App />
+   * </AlienProvider>
+   *
+   * function App() {
+   *   const { ready } = useAlien();
+   *   useEffect(() => {
+   *     fetchData().then(() => ready());
+   *   }, []);
+   * }
+   * ```
+   */
+  autoReady?: boolean;
 }
 /**
  * Provider component that initializes the Alien miniapp context.
@@ -547,7 +584,8 @@ interface AlienProviderProps {
  * ```
  */
 declare function AlienProvider({
-  children
+  children,
+  autoReady
 }: AlienProviderProps): ReactNode;
 //#endregion
 //#region src/errors.d.ts

package/dist/index.mjs

@@ -1,9 +1,10 @@
 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 { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/context.tsx
+const useIsomorphicLayoutEffect$1 = typeof window !== "undefined" ? useLayoutEffect : useEffect;
 const AlienContext = createContext(null);
 /**
 * Provider component that initializes the Alien miniapp context.
@@ -22,21 +23,33 @@ const AlienContext = createContext(null);
 * }
 * ```
 */
-function AlienProvider({ children }) {
-	const value = useMemo(() => {
+function AlienProvider({ children, autoReady = true }) {
+	const readySent = useRef(false);
+	const ready = useCallback(() => {
+		if (readySent.current) return;
+		readySent.current = true;
+		if (isBridgeAvailable()) send$1("app:ready", {});
+	}, []);
+	const [value, setValue] = useState(() => ({
+		authToken: void 0,
+		contractVersion: void 0,
+		isBridgeAvailable: false,
+		ready
+	}));
+	useIsomorphicLayoutEffect$1(() => {
 		const launchParams = getLaunchParams();
-		return {
+		const bridgeAvailable = isBridgeAvailable();
+		setValue({
 			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]);
+			isBridgeAvailable: bridgeAvailable,
+			ready
+		});
+		if (!bridgeAvailable) 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.");
+	}, [ready]);
 	useEffect(() => {
-		if (value.isBridgeAvailable) send$1("app:ready", {});
-	}, [value.isBridgeAvailable]);
+		if (autoReady) ready();
+	}, [autoReady, ready]);
 	return /* @__PURE__ */ jsx(AlienContext.Provider, {
 		value,
 		children
@@ -252,6 +265,7 @@ function useIsMethodSupported(method) {
 
 //#endregion
 //#region src/hooks/useLaunchParams.ts
+const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
 /**
 * Hook to get launch params.
 * Returns undefined if params unavailable (use mockLaunchParamsForDev in dev).
@@ -272,7 +286,11 @@ function useIsMethodSupported(method) {
 * ```
 */
 function useLaunchParams() {
-	return useMemo(() => getLaunchParams(), []);
+	const [params, setParams] = useState(void 0);
+	useIsomorphicLayoutEffect(() => {
+		setParams(getLaunchParams());
+	}, []);
+	return params;
 }
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alien_org/react",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -34,8 +34,8 @@
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@alien_org/bridge": "0.2.0",
-    "@alien_org/contract": "0.2.0"
+    "@alien_org/bridge": "0.2.1",
+    "@alien_org/contract": "0.2.1"
   },
   "peerDependencies": {
     "react": "^18 || ^19",