@alien_org/react 0.1.4 → 0.2.1

package/dist/index.cjs

@@ -22,21 +22,28 @@ const AlienContext = (0, react.createContext)(null);
 * }
 * ```
 */
-function AlienProvider({ children }) {
+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 = (0, react.useMemo)(() => {
 		const launchParams = (0, _alien_org_bridge.getLaunchParams)();
 		return {
 			authToken: launchParams?.authToken,
 			contractVersion: launchParams?.contractVersion,
-			isBridgeAvailable: (0, _alien_org_bridge.isBridgeAvailable)()
+			isBridgeAvailable: (0, _alien_org_bridge.isBridgeAvailable)(),
+			ready
 		};
-	}, []);
+	}, [ready]);
 	(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]);
+		if (autoReady) ready();
+	}, [autoReady, ready]);
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(AlienContext.Provider, {
 		value,
 		children

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.
@@ -412,6 +413,11 @@ type MethodPayload<M$1 extends MethodName> = Methods[M$1]['payload'];
 /**
  * Check if a method is supported in a given version.
  *
+ * Uses the minimum version that introduced the method and returns true if
+ * the given version is >= that minimum (semver comparison). This supports
+ * versions not explicitly listed in releases (e.g. 0.1.4 when method was
+ * added in 0.1.1).
+ *
  * @param method - The method name to check.
  * @param version - The contract version (must be a valid version string, not undefined).
  * @returns `true` if the method is supported in the given version, `false` otherwise.
@@ -520,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.
@@ -542,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.
@@ -412,6 +413,11 @@ type MethodPayload<M$1 extends MethodName> = Methods[M$1]['payload'];
 /**
  * Check if a method is supported in a given version.
  *
+ * Uses the minimum version that introduced the method and returns true if
+ * the given version is >= that minimum (semver comparison). This supports
+ * versions not explicitly listed in releases (e.g. 0.1.4 when method was
+ * added in 0.1.1).
+ *
  * @param method - The method name to check.
  * @param version - The contract version (must be a valid version string, not undefined).
  * @returns `true` if the method is supported in the given version, `false` otherwise.
@@ -520,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.
@@ -542,7 +584,8 @@ interface AlienProviderProps {
  * ```
  */
 declare function AlienProvider({
-  children
+  children,
+  autoReady
 }: AlienProviderProps): ReactNode;
 //#endregion
 //#region src/errors.d.ts

package/dist/index.mjs

@@ -22,21 +22,28 @@ const AlienContext = createContext(null);
 * }
 * ```
 */
-function AlienProvider({ children }) {
+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 = useMemo(() => {
 		const launchParams = getLaunchParams();
 		return {
 			authToken: launchParams?.authToken,
 			contractVersion: launchParams?.contractVersion,
-			isBridgeAvailable: isBridgeAvailable()
+			isBridgeAvailable: isBridgeAvailable(),
+			ready
 		};
-	}, []);
+	}, [ready]);
 	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]);
+		if (autoReady) ready();
+	}, [autoReady, ready]);
 	return /* @__PURE__ */ jsx(AlienContext.Provider, {
 		value,
 		children

package/package.json

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