@alien_org/react 0.1.1 → 0.1.3

package/dist/index.cjs

@@ -91,6 +91,84 @@ function useAlien() {
 	return context;
 }
 
+//#endregion
+//#region src/hooks/useClipboard.ts
+/**
+* Hook for clipboard operations.
+*
+* @example
+* ```tsx
+* function ClipboardDemo() {
+*   const { writeText, readText, isReading, errorCode, supported } = useClipboard();
+*
+*   if (!supported) return null;
+*
+*   return (
+*     <>
+*       <button onClick={() => writeText('Hello!')}>Copy</button>
+*       <button
+*         onClick={async () => {
+*           const text = await readText();
+*           if (text !== null) console.log('Pasted:', text);
+*         }}
+*         disabled={isReading}
+*       >
+*         Paste
+*       </button>
+*       {errorCode && <span>Error: {errorCode}</span>}
+*     </>
+*   );
+* }
+* ```
+*/
+function useClipboard(options = {}) {
+	const { timeout = 5e3 } = options;
+	const { contractVersion, isBridgeAvailable: isBridgeAvailable$1 } = useAlien();
+	const [isReading, setIsReading] = (0, react.useState)(false);
+	const [errorCode, setErrorCode] = (0, react.useState)(null);
+	const supported = contractVersion ? (0, _alien_org_contract.isMethodSupported)("clipboard:write", contractVersion) && (0, _alien_org_contract.isMethodSupported)("clipboard:read", contractVersion) : true;
+	const writeText = (0, react.useCallback)((text) => {
+		if (!isBridgeAvailable$1) return;
+		if (contractVersion && !(0, _alien_org_contract.isMethodSupported)("clipboard:write", contractVersion)) return;
+		(0, _alien_org_bridge.send)("clipboard:write", { text });
+	}, [isBridgeAvailable$1, contractVersion]);
+	const readText = (0, react.useCallback)(async () => {
+		if (!isBridgeAvailable$1) return null;
+		if (contractVersion && !(0, _alien_org_contract.isMethodSupported)("clipboard:read", contractVersion)) return null;
+		setIsReading(true);
+		setErrorCode(null);
+		try {
+			const response = await (0, _alien_org_bridge.request)("clipboard:read", {}, "clipboard:response", { timeout });
+			if (response.errorCode) {
+				setErrorCode(response.errorCode);
+				return null;
+			}
+			return response.text;
+		} catch {
+			return null;
+		} finally {
+			setIsReading(false);
+		}
+	}, [
+		isBridgeAvailable$1,
+		contractVersion,
+		timeout
+	]);
+	return (0, react.useMemo)(() => ({
+		writeText,
+		readText,
+		isReading,
+		errorCode,
+		supported
+	}), [
+		writeText,
+		readText,
+		isReading,
+		errorCode,
+		supported
+	]);
+}
+
 //#endregion
 //#region src/hooks/useEvent.ts
 /**
@@ -539,6 +617,7 @@ Object.defineProperty(exports, 'send', {
   }
 });
 exports.useAlien = useAlien;
+exports.useClipboard = useClipboard;
 exports.useEvent = useEvent;
 exports.useIsMethodSupported = useIsMethodSupported;
 exports.useLaunchParams = useLaunchParams;

package/dist/index.d.cts

@@ -72,7 +72,7 @@ interface Events {
    * For instant fulfillment, your backend should fulfill on webhook receipt
    * using the `invoice` from the request.
    *
-   * @since 0.0.14
+   * @since 0.1.1
    * @schema
    */
   'payment:response': CreateEventPayload<WithReqId<{
@@ -81,13 +81,13 @@ interface Events {
      * - `paid`: Success
      * - `cancelled`: User rejected
      * - `failed`: Error (check `errorCode`)
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     status: 'paid' | 'cancelled' | 'failed';
     /**
      * Transaction hash (present when status is 'paid').
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     txHash?: string;
@@ -98,11 +98,36 @@ interface Events {
      * - `pre_checkout_rejected`: Backend rejected the payment in pre-checkout
      * - `pre_checkout_timeout`: Backend didn't respond to pre-checkout in time
      * - `unknown`: Unexpected error
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
   }>>;
+  /**
+   * Clipboard read response.
+   *
+   * On success: `text` contains the clipboard content (may be empty string).
+   * On failure: `text` is null and `errorCode` indicates the reason.
+   *
+   * @since 0.1.1
+   * @schema
+   */
+  'clipboard:response': CreateEventPayload<WithReqId<{
+    /**
+     * Text from clipboard. Null if read failed.
+     * @since 0.1.1
+     * @schema
+     */
+    text: string | null;
+    /**
+     * Error code if clipboard read failed.
+     * - `permission_denied`: User denied clipboard access
+     * - `unavailable`: Clipboard is not available
+     * @since 0.1.1
+     * @schema
+     */
+    errorCode?: 'permission_denied' | 'unavailable';
+  }>>;
 }
 //#endregion
 //#region ../contract/src/events/types/event-types.d.ts
@@ -193,61 +218,61 @@ interface Methods {
    * Set `test: true` for test mode - no real payment is made, but webhooks
    * are fired with `test: true` flag. Use for development and testing.
    *
-   * @since 0.0.14
+   * @since 0.1.1
    * @schema
    */
   'payment:request': CreateMethodPayload<WithReqId<{
     /**
      * The recipient's wallet address.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     recipient: string;
     /**
      * The amount to pay (in token's smallest unit, as string for precision).
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     amount: string;
     /**
      * The token identifier (e.g., 'SOL', 'ALIEN', or contract address).
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     token: string;
     /**
      * The network for the payment ('solana' or 'alien').
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     network: string;
     /**
      * Your order/invoice ID for backend correlation and instant fulfillment.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     invoice: string;
     /**
      * Item title shown on the approval screen.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     title?: string;
     /**
      * Item description/caption shown on the approval screen.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     caption?: string;
     /**
      * Item icon URL shown on the approval screen.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     iconUrl?: string;
     /**
      * Quantity of items being purchased.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     quantity?: number;
@@ -255,11 +280,30 @@ interface Methods {
      * Test mode flag. When true, no real payment is processed.
      * The approval screen shows a test indicator, and webhooks
      * include `test: true`. Use for development and testing.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     test?: boolean;
   }>>;
+  /**
+   * Write text to the system clipboard.
+   * @since 0.1.1
+   * @schema
+   */
+  'clipboard:write': CreateMethodPayload<{
+    /**
+     * Text to copy to clipboard.
+     * @since 0.1.1
+     * @schema
+     */
+    text: string;
+  }>;
+  /**
+   * Read text from the system clipboard.
+   * @since 0.1.1
+   * @schema
+   */
+  'clipboard:read': CreateMethodPayload<WithReqId<Empty>>;
 }
 //#endregion
 //#region ../contract/src/methods/types/method-types.d.ts
@@ -435,6 +479,58 @@ declare class MethodNotSupportedError extends ReactSDKError {
  */
 declare function useAlien(): AlienContextValue;
 //#endregion
+//#region src/hooks/useClipboard.d.ts
+/** Clipboard error codes from the host app. */
+type ClipboardErrorCode = 'permission_denied' | 'unavailable';
+interface UseClipboardOptions {
+  /**
+   * Timeout for clipboard read in milliseconds.
+   * @default 5000
+   */
+  timeout?: number;
+}
+interface UseClipboardReturn {
+  /** Write text to clipboard. Fire-and-forget. */
+  writeText: (text: string) => void;
+  /** Read text from clipboard. Returns text or null on failure. */
+  readText: () => Promise<string | null>;
+  /** Whether a read operation is in progress. */
+  isReading: boolean;
+  /** Error code from the last failed read operation. */
+  errorCode: ClipboardErrorCode | null;
+  /** Whether clipboard methods are supported by the host app. */
+  supported: boolean;
+}
+/**
+ * Hook for clipboard operations.
+ *
+ * @example
+ * ```tsx
+ * function ClipboardDemo() {
+ *   const { writeText, readText, isReading, errorCode, supported } = useClipboard();
+ *
+ *   if (!supported) return null;
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => writeText('Hello!')}>Copy</button>
+ *       <button
+ *         onClick={async () => {
+ *           const text = await readText();
+ *           if (text !== null) console.log('Pasted:', text);
+ *         }}
+ *         disabled={isReading}
+ *       >
+ *         Paste
+ *       </button>
+ *       {errorCode && <span>Error: {errorCode}</span>}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;
+//#endregion
 //#region src/hooks/useEvent.d.ts
 type EventCallback<E extends EventName> = (payload: EventPayload<E>) => void;
 /**
@@ -718,4 +814,4 @@ interface UsePaymentReturn {
  */
 declare function usePayment(options?: UsePaymentOptions): UsePaymentReturn;
 //#endregion
-export { AlienProvider, type AlienProviderProps, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, type EventName, type EventPayload, type MethodName, MethodNotSupportedError, type MethodPayload, type MethodSupportResult, type PaymentCallbacks, type PaymentErrorCode, type PaymentParams, type PaymentResponseStatus, type PaymentResult, type PaymentStatus, ReactSDKError, type RequestOptions, type UseMethodExecuteResult, type UseMethodOptions, type UsePaymentOptions, type UsePaymentReturn, type Version, getMethodMinVersion, isMethodSupported, send, useAlien, useEvent, useIsMethodSupported, useLaunchParams, useMethod, usePayment };
+export { AlienProvider, type AlienProviderProps, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, type ClipboardErrorCode, type EventName, type EventPayload, type MethodName, MethodNotSupportedError, type MethodPayload, type MethodSupportResult, type PaymentCallbacks, type PaymentErrorCode, type PaymentParams, type PaymentResponseStatus, type PaymentResult, type PaymentStatus, ReactSDKError, type RequestOptions, type UseClipboardOptions, type UseClipboardReturn, type UseMethodExecuteResult, type UseMethodOptions, type UsePaymentOptions, type UsePaymentReturn, type Version, getMethodMinVersion, isMethodSupported, send, useAlien, useClipboard, useEvent, useIsMethodSupported, useLaunchParams, useMethod, usePayment };

package/dist/index.d.mts

@@ -72,7 +72,7 @@ interface Events {
    * For instant fulfillment, your backend should fulfill on webhook receipt
    * using the `invoice` from the request.
    *
-   * @since 0.0.14
+   * @since 0.1.1
    * @schema
    */
   'payment:response': CreateEventPayload<WithReqId<{
@@ -81,13 +81,13 @@ interface Events {
      * - `paid`: Success
      * - `cancelled`: User rejected
      * - `failed`: Error (check `errorCode`)
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     status: 'paid' | 'cancelled' | 'failed';
     /**
      * Transaction hash (present when status is 'paid').
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     txHash?: string;
@@ -98,11 +98,36 @@ interface Events {
      * - `pre_checkout_rejected`: Backend rejected the payment in pre-checkout
      * - `pre_checkout_timeout`: Backend didn't respond to pre-checkout in time
      * - `unknown`: Unexpected error
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
   }>>;
+  /**
+   * Clipboard read response.
+   *
+   * On success: `text` contains the clipboard content (may be empty string).
+   * On failure: `text` is null and `errorCode` indicates the reason.
+   *
+   * @since 0.1.1
+   * @schema
+   */
+  'clipboard:response': CreateEventPayload<WithReqId<{
+    /**
+     * Text from clipboard. Null if read failed.
+     * @since 0.1.1
+     * @schema
+     */
+    text: string | null;
+    /**
+     * Error code if clipboard read failed.
+     * - `permission_denied`: User denied clipboard access
+     * - `unavailable`: Clipboard is not available
+     * @since 0.1.1
+     * @schema
+     */
+    errorCode?: 'permission_denied' | 'unavailable';
+  }>>;
 }
 //#endregion
 //#region ../contract/src/events/types/event-types.d.ts
@@ -193,61 +218,61 @@ interface Methods {
    * Set `test: true` for test mode - no real payment is made, but webhooks
    * are fired with `test: true` flag. Use for development and testing.
    *
-   * @since 0.0.14
+   * @since 0.1.1
    * @schema
    */
   'payment:request': CreateMethodPayload<WithReqId<{
     /**
      * The recipient's wallet address.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     recipient: string;
     /**
      * The amount to pay (in token's smallest unit, as string for precision).
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     amount: string;
     /**
      * The token identifier (e.g., 'SOL', 'ALIEN', or contract address).
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     token: string;
     /**
      * The network for the payment ('solana' or 'alien').
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     network: string;
     /**
      * Your order/invoice ID for backend correlation and instant fulfillment.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     invoice: string;
     /**
      * Item title shown on the approval screen.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     title?: string;
     /**
      * Item description/caption shown on the approval screen.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     caption?: string;
     /**
      * Item icon URL shown on the approval screen.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     iconUrl?: string;
     /**
      * Quantity of items being purchased.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     quantity?: number;
@@ -255,11 +280,30 @@ interface Methods {
      * Test mode flag. When true, no real payment is processed.
      * The approval screen shows a test indicator, and webhooks
      * include `test: true`. Use for development and testing.
-     * @since 0.0.14
+     * @since 0.1.1
      * @schema
      */
     test?: boolean;
   }>>;
+  /**
+   * Write text to the system clipboard.
+   * @since 0.1.1
+   * @schema
+   */
+  'clipboard:write': CreateMethodPayload<{
+    /**
+     * Text to copy to clipboard.
+     * @since 0.1.1
+     * @schema
+     */
+    text: string;
+  }>;
+  /**
+   * Read text from the system clipboard.
+   * @since 0.1.1
+   * @schema
+   */
+  'clipboard:read': CreateMethodPayload<WithReqId<Empty>>;
 }
 //#endregion
 //#region ../contract/src/methods/types/method-types.d.ts
@@ -435,6 +479,58 @@ declare class MethodNotSupportedError extends ReactSDKError {
  */
 declare function useAlien(): AlienContextValue;
 //#endregion
+//#region src/hooks/useClipboard.d.ts
+/** Clipboard error codes from the host app. */
+type ClipboardErrorCode = 'permission_denied' | 'unavailable';
+interface UseClipboardOptions {
+  /**
+   * Timeout for clipboard read in milliseconds.
+   * @default 5000
+   */
+  timeout?: number;
+}
+interface UseClipboardReturn {
+  /** Write text to clipboard. Fire-and-forget. */
+  writeText: (text: string) => void;
+  /** Read text from clipboard. Returns text or null on failure. */
+  readText: () => Promise<string | null>;
+  /** Whether a read operation is in progress. */
+  isReading: boolean;
+  /** Error code from the last failed read operation. */
+  errorCode: ClipboardErrorCode | null;
+  /** Whether clipboard methods are supported by the host app. */
+  supported: boolean;
+}
+/**
+ * Hook for clipboard operations.
+ *
+ * @example
+ * ```tsx
+ * function ClipboardDemo() {
+ *   const { writeText, readText, isReading, errorCode, supported } = useClipboard();
+ *
+ *   if (!supported) return null;
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => writeText('Hello!')}>Copy</button>
+ *       <button
+ *         onClick={async () => {
+ *           const text = await readText();
+ *           if (text !== null) console.log('Pasted:', text);
+ *         }}
+ *         disabled={isReading}
+ *       >
+ *         Paste
+ *       </button>
+ *       {errorCode && <span>Error: {errorCode}</span>}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+declare function useClipboard(options?: UseClipboardOptions): UseClipboardReturn;
+//#endregion
 //#region src/hooks/useEvent.d.ts
 type EventCallback<E extends EventName> = (payload: EventPayload<E>) => void;
 /**
@@ -718,4 +814,4 @@ interface UsePaymentReturn {
  */
 declare function usePayment(options?: UsePaymentOptions): UsePaymentReturn;
 //#endregion
-export { AlienProvider, type AlienProviderProps, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, type EventName, type EventPayload, type MethodName, MethodNotSupportedError, type MethodPayload, type MethodSupportResult, type PaymentCallbacks, type PaymentErrorCode, type PaymentParams, type PaymentResponseStatus, type PaymentResult, type PaymentStatus, ReactSDKError, type RequestOptions, type UseMethodExecuteResult, type UseMethodOptions, type UsePaymentOptions, type UsePaymentReturn, type Version, getMethodMinVersion, isMethodSupported, send, useAlien, useEvent, useIsMethodSupported, useLaunchParams, useMethod, usePayment };
+export { AlienProvider, type AlienProviderProps, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, type ClipboardErrorCode, type EventName, type EventPayload, type MethodName, MethodNotSupportedError, type MethodPayload, type MethodSupportResult, type PaymentCallbacks, type PaymentErrorCode, type PaymentParams, type PaymentResponseStatus, type PaymentResult, type PaymentStatus, ReactSDKError, type RequestOptions, type UseClipboardOptions, type UseClipboardReturn, type UseMethodExecuteResult, type UseMethodOptions, type UsePaymentOptions, type UsePaymentReturn, type Version, getMethodMinVersion, isMethodSupported, send, useAlien, useClipboard, useEvent, useIsMethodSupported, useLaunchParams, useMethod, usePayment };

package/dist/index.mjs

@@ -91,6 +91,84 @@ function useAlien() {
 	return context;
 }
 
+//#endregion
+//#region src/hooks/useClipboard.ts
+/**
+* Hook for clipboard operations.
+*
+* @example
+* ```tsx
+* function ClipboardDemo() {
+*   const { writeText, readText, isReading, errorCode, supported } = useClipboard();
+*
+*   if (!supported) return null;
+*
+*   return (
+*     <>
+*       <button onClick={() => writeText('Hello!')}>Copy</button>
+*       <button
+*         onClick={async () => {
+*           const text = await readText();
+*           if (text !== null) console.log('Pasted:', text);
+*         }}
+*         disabled={isReading}
+*       >
+*         Paste
+*       </button>
+*       {errorCode && <span>Error: {errorCode}</span>}
+*     </>
+*   );
+* }
+* ```
+*/
+function useClipboard(options = {}) {
+	const { timeout = 5e3 } = options;
+	const { contractVersion, isBridgeAvailable: isBridgeAvailable$1 } = useAlien();
+	const [isReading, setIsReading] = useState(false);
+	const [errorCode, setErrorCode] = useState(null);
+	const supported = contractVersion ? isMethodSupported$1("clipboard:write", contractVersion) && isMethodSupported$1("clipboard:read", contractVersion) : true;
+	const writeText = useCallback((text) => {
+		if (!isBridgeAvailable$1) return;
+		if (contractVersion && !isMethodSupported$1("clipboard:write", contractVersion)) return;
+		send$1("clipboard:write", { text });
+	}, [isBridgeAvailable$1, contractVersion]);
+	const readText = useCallback(async () => {
+		if (!isBridgeAvailable$1) return null;
+		if (contractVersion && !isMethodSupported$1("clipboard:read", contractVersion)) return null;
+		setIsReading(true);
+		setErrorCode(null);
+		try {
+			const response = await request("clipboard:read", {}, "clipboard:response", { timeout });
+			if (response.errorCode) {
+				setErrorCode(response.errorCode);
+				return null;
+			}
+			return response.text;
+		} catch {
+			return null;
+		} finally {
+			setIsReading(false);
+		}
+	}, [
+		isBridgeAvailable$1,
+		contractVersion,
+		timeout
+	]);
+	return useMemo(() => ({
+		writeText,
+		readText,
+		isReading,
+		errorCode,
+		supported
+	}), [
+		writeText,
+		readText,
+		isReading,
+		errorCode,
+		supported
+	]);
+}
+
 //#endregion
 //#region src/hooks/useEvent.ts
 /**
@@ -513,4 +591,4 @@ function usePayment(options = {}) {
 }
 
 //#endregion
-export { AlienProvider, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, MethodNotSupportedError, ReactSDKError, getMethodMinVersion, isMethodSupported, send, useAlien, useEvent, useIsMethodSupported, useLaunchParams, useMethod, usePayment };
+export { AlienProvider, BridgeError, BridgeTimeoutError, BridgeUnavailableError, BridgeWindowUnavailableError, MethodNotSupportedError, ReactSDKError, getMethodMinVersion, isMethodSupported, send, useAlien, useClipboard, useEvent, useIsMethodSupported, useLaunchParams, useMethod, usePayment };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alien_org/react",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@alien_org/bridge": "0.1.1",
-    "@alien_org/contract": "0.1.0"
+    "@alien_org/contract": "0.1.1"
   },
   "peerDependencies": {
     "react": "^18 || ^19",