@alien_org/react 0.0.11-beta

package/dist/index.d.mts

@@ -0,0 +1,721 @@
+import { ReactNode } from "react";
+
+//#region ../contract/src/utils.d.ts
+
+/**
+ * Adds a reqId field to the payload.
+ * @schema
+ */
+type WithReqId<T> = T & {
+  /**
+   * Request identifier.
+   * @schema
+   */
+  reqId: string;
+};
+/**
+ * Semantic versioning type.
+ * @example
+ * type Version = '1.0.0';
+ */
+type Version = `${number}.${number}.${number}`;
+/**
+ * Extracts keys, that are present in the type if it is an object.
+ * @example
+ * type Keys = UnionKeys<{ a: string, b: number }>;
+ * // Keys = 'a' | 'b'
+ */
+type UnionKeys<T> = T extends T ? keyof T : never;
+/**
+ * Empty object type.
+ * @example
+ * type Empty = Empty;
+ * // Empty = {}
+ */
+type Empty = Record<string, never>;
+//#endregion
+//#region ../contract/src/events/types/payload.d.ts
+/**
+ * Creates event payload types.
+ */
+interface CreateEventPayload<Payload = never> {
+  payload: Payload;
+}
+//#endregion
+//#region ../contract/src/events/definitions/events.d.ts
+/**
+ * Events interface defining all available events and their payloads.
+ * @since 0.0.1
+ * @schema
+ */
+interface Events {
+  /**
+   * Miniapp close event, fired by the host app just before the miniapp is closed.
+   * @since 0.0.14
+   * @schema
+   */
+  'miniapp:close': CreateEventPayload<Empty>;
+  /**
+   * Host app's back button clicked event.
+   * @since 0.0.14
+   * @schema
+   */
+  'host.back.button:clicked': CreateEventPayload<Empty>;
+  /**
+   * Payment response event.
+   *
+   * Statuses:
+   * - `paid`: Payment successful, `txHash` included
+   * - `cancelled`: User manually cancelled/rejected the payment
+   * - `failed`: Error occurred (see `errorCode` for details)
+   *
+   * For instant fulfillment, your backend should fulfill on webhook receipt
+   * using the `invoice` from the request.
+   *
+   * @since 0.0.14
+   * @schema
+   */
+  'payment:response': CreateEventPayload<WithReqId<{
+    /**
+     * Payment status.
+     * - `paid`: Success
+     * - `cancelled`: User rejected
+     * - `failed`: Error (check `errorCode`)
+     * @since 0.0.14
+     * @schema
+     */
+    status: 'paid' | 'cancelled' | 'failed';
+    /**
+     * Transaction hash (present when status is 'paid').
+     * @since 0.0.14
+     * @schema
+     */
+    txHash?: string;
+    /**
+     * Error code (present when status is 'failed').
+     * - `insufficient_balance`: User doesn't have enough tokens
+     * - `network_error`: Blockchain network issue
+     * - `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
+     * @schema
+     */
+    errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+  }>>;
+}
+//#endregion
+//#region ../contract/src/events/types/event-types.d.ts
+type EventName = keyof Events;
+type EventPayload<E extends EventName> = Events[E]['payload'];
+//#endregion
+//#region ../contract/src/launch-params.d.ts
+/**
+ * Supported platforms for miniapps.
+ */
+declare const PLATFORMS: readonly ["ios", "android"];
+/**
+ * Platform the miniapp is running on.
+ */
+type Platform = (typeof PLATFORMS)[number];
+/**
+ * Launch parameters injected by the host app.
+ */
+interface LaunchParams {
+  /** JWT auth token injected by host app */
+  authToken: string | undefined;
+  /** Contract version supported by host app (semver) */
+  contractVersion: Version | undefined;
+  /** Host app version (e.g., '1.2.3') */
+  hostAppVersion: string | undefined;
+  /** Platform the miniapp is running on */
+  platform: Platform | undefined;
+  /**
+   * Custom start parameter injected by host app.
+   * Used for referral codes, campaign tracking, or custom routing.
+   */
+  startParam: string | undefined;
+}
+//#endregion
+//#region ../contract/src/methods/types/payload.d.ts
+/**
+ * Creates method payload types.
+ */
+interface CreateMethodPayload<Payload = never, VersionedPayload extends UnionKeys<Payload> = never> {
+  payload: Payload;
+  versionedPayload: VersionedPayload;
+}
+//#endregion
+//#region ../contract/src/methods/definitions/methods.d.ts
+/**
+ * Methods interface defining all available methods and their payloads.
+ * @schema
+ */
+interface Methods {
+  /**
+   * Miniapp ready method.
+   * Sent by the miniapp to notify the host app that it has loaded and is ready to be displayed.
+   * @since 0.0.1
+   * @schema
+   */
+  'app:ready': CreateMethodPayload<Empty>;
+  /**
+   * Miniapp close acknowledgment method.
+   * Sent by the miniapp to notify the host app that it has completed cleanup and is ready to be closed.
+   * Note that if the miniapp takes longer than 10 seconds to close, the host app will force close the miniapp.
+   * @since 0.0.14
+   * @schema
+   */
+  'miniapp:close.ack': CreateMethodPayload<Empty>;
+  /**
+   * Toggle host app's back button visibility.
+   * @since 0.0.14
+   * @schema
+   */
+  'host.back.button:toggle': CreateMethodPayload<{
+    /**
+     * Whether to show or hide the back button.
+     * @since 0.0.14
+     * @schema
+     */
+    visible: boolean;
+  }>;
+  /**
+   * Request a payment from the user.
+   *
+   * The `invoice` field is your order/invoice ID for backend correlation.
+   * Your backend receives a webhook when user pays - fulfill the order
+   * immediately without waiting for chain confirmation.
+   *
+   * 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.
+   *
+   * @since 0.0.14
+   * @schema
+   */
+  'payment:request': CreateMethodPayload<WithReqId<{
+    /**
+     * The recipient's wallet address.
+     * @since 0.0.14
+     * @schema
+     */
+    recipient: string;
+    /**
+     * The amount to pay (in token's smallest unit, as string for precision).
+     * @since 0.0.14
+     * @schema
+     */
+    amount: string;
+    /**
+     * The token identifier (e.g., 'SOL', 'ALIEN', or contract address).
+     * @since 0.0.14
+     * @schema
+     */
+    token: string;
+    /**
+     * The network for the payment ('solana' or 'alien').
+     * @since 0.0.14
+     * @schema
+     */
+    network: string;
+    /**
+     * Your order/invoice ID for backend correlation and instant fulfillment.
+     * @since 0.0.14
+     * @schema
+     */
+    invoice: string;
+    /**
+     * Item title shown on the approval screen.
+     * @since 0.0.14
+     * @schema
+     */
+    title?: string;
+    /**
+     * Item description/caption shown on the approval screen.
+     * @since 0.0.14
+     * @schema
+     */
+    caption?: string;
+    /**
+     * Item icon URL shown on the approval screen.
+     * @since 0.0.14
+     * @schema
+     */
+    iconUrl?: string;
+    /**
+     * Quantity of items being purchased.
+     * @since 0.0.14
+     * @schema
+     */
+    quantity?: number;
+    /**
+     * 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
+     * @schema
+     */
+    test?: boolean;
+  }>>;
+}
+//#endregion
+//#region ../contract/src/methods/types/method-types.d.ts
+type MethodName = keyof Methods;
+type MethodPayload<M$1 extends MethodName> = Methods[M$1]['payload'];
+//#endregion
+//#region ../contract/src/methods/versions/index.d.ts
+/**
+ * Check if a method is supported in a given version.
+ *
+ * @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.
+ *
+ * @remarks
+ * This function only accepts valid version strings. Version existence checks should be
+ * handled at a higher level before calling this function.
+ */
+declare function isMethodSupported(method: MethodName, version: Version): boolean;
+/**
+ * Get the minimum version that supports a method.
+ * Returns undefined if method not found in any version.
+ */
+declare function getMethodMinVersion(method: MethodName): Version | undefined;
+//#endregion
+//#region ../bridge/src/errors.d.ts
+/**
+ * Base class for all bridge-related errors.
+ * Allows catching all bridge errors with a single catch block.
+ */
+declare class BridgeError extends Error {
+  constructor(message: string);
+}
+/**
+ * Thrown when the bridge interface is not available.
+ * This occurs when the miniapp is not running in Alien App.
+ */
+declare class BridgeUnavailableError extends BridgeError {
+  constructor();
+}
+/**
+ * Thrown when window is undefined (e.g., SSR scenarios).
+ */
+declare class BridgeWindowUnavailableError extends BridgeError {
+  constructor();
+}
+/**
+ * Thrown when a request times out.
+ */
+declare class BridgeTimeoutError extends BridgeError {
+  readonly method: string;
+  readonly timeout: number;
+  constructor(method: string, timeout: number);
+}
+//#endregion
+//#region ../bridge/src/launch-params.d.ts
+declare global {
+  interface Window {
+    __ALIEN_AUTH_TOKEN__?: string;
+    __ALIEN_CONTRACT_VERSION__?: string;
+    __ALIEN_HOST_VERSION__?: string;
+    __ALIEN_PLATFORM__?: string;
+    __ALIEN_START_PARAM__?: string;
+  }
+}
+/**
+ * Error thrown when launch params cannot be retrieved.
+ */
+//#endregion
+//#region ../bridge/src/request.d.ts
+interface RequestOptions {
+  reqId?: string;
+  timeout?: number;
+}
+//#endregion
+//#region ../bridge/src/send.d.ts
+/**
+ * Sends a one-way method to the host app without waiting for a response.
+ * Use this for fire-and-forget methods like 'app:ready'.
+ *
+ * @param method - The method name to send
+ * @param payload - The method payload
+ *
+ * @example
+ * ```ts
+ * import { send } from '@alien_org/bridge';
+ *
+ * send('app:ready', {});
+ * ```
+ */
+declare function send<M$1 extends MethodName>(method: M$1, payload: MethodPayload<M$1>): void;
+//#endregion
+//#region ../bridge/src/transport.d.ts
+interface MiniAppsBridge {
+  postMessage(data: string): void;
+}
+declare global {
+  interface Window {
+    __miniAppsBridge__?: MiniAppsBridge;
+  }
+}
+//#endregion
+//#region src/context.d.ts
+interface AlienContextValue {
+  /**
+   * Auth token injected by the host app.
+   * `undefined` if not available.
+   */
+  authToken: string | undefined;
+  /**
+   * Contract version supported by the host app.
+   * `undefined` if not provided (fallback: assume all methods supported).
+   */
+  contractVersion: Version | undefined;
+  /**
+   * Whether the bridge is available (running inside Alien App).
+   */
+  isBridgeAvailable: boolean;
+}
+interface AlienProviderProps {
+  children: ReactNode;
+}
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+declare function AlienProvider({
+  children
+}: AlienProviderProps): ReactNode;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Base class for all React SDK errors.
+ */
+declare class ReactSDKError extends Error {
+  constructor(message: string);
+}
+/**
+ * Error thrown when a method is not supported by the current contract version.
+ */
+declare class MethodNotSupportedError extends ReactSDKError {
+  readonly method: MethodName;
+  readonly contractVersion: Version | undefined;
+  readonly minVersion: Version | undefined;
+  constructor(method: MethodName, contractVersion: Version | undefined, minVersion: Version | undefined);
+}
+//#endregion
+//#region src/hooks/useAlien.d.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();
+ * ```
+ */
+declare function useAlien(): AlienContextValue;
+//#endregion
+//#region src/hooks/useEvent.d.ts
+type EventCallback<E extends EventName> = (payload: EventPayload<E>) => void;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useEvent<E extends EventName>(event: E, callback: EventCallback<E>): void;
+//#endregion
+//#region src/hooks/useIsMethodSupported.d.ts
+interface MethodSupportResult {
+  /**
+   * Whether the method is supported in the current contract version.
+   * Always `true` if no version is provided (fallback behavior).
+   */
+  supported: boolean;
+  /**
+   * The contract version provided by the host app.
+   */
+  contractVersion: Version | undefined;
+  /**
+   * The minimum version that supports this method.
+   */
+  minVersion: Version | undefined;
+}
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useIsMethodSupported(method: MethodName): MethodSupportResult;
+//#endregion
+//#region src/hooks/useLaunchParams.d.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>;
+ * }
+ * ```
+ */
+declare function useLaunchParams(): LaunchParams | undefined;
+//#endregion
+//#region src/hooks/useMethod.d.ts
+interface UseMethodExecuteResult<E extends EventName> {
+  data: EventPayload<E> | undefined;
+  error: Error | undefined;
+}
+interface UseMethodState<E extends EventName> extends UseMethodExecuteResult<E> {
+  isLoading: boolean;
+}
+interface UseMethodOptions {
+  /**
+   * Whether to check if the method is supported before executing.
+   * If unsupported, sets error state with `MethodNotSupportedError`.
+   * @default true
+   */
+  checkVersion?: boolean;
+}
+interface UseMethodResult<M$1 extends MethodName, E extends EventName> extends UseMethodState<E> {
+  execute: (params: Omit<MethodPayload<M$1>, 'reqId'>, options?: RequestOptions) => Promise<UseMethodExecuteResult<E>>;
+  reset: () => void;
+  /**
+   * Whether the method is supported by the current contract version.
+   */
+  supported: boolean;
+}
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useMethod<M$1 extends MethodName, E extends EventName>(method: M$1, responseEvent: E, options?: UseMethodOptions): UseMethodResult<M$1, E>;
+//#endregion
+//#region src/hooks/usePayment.d.ts
+type PaymentRequestPayload = MethodPayload<'payment:request'>;
+type PaymentResponsePayload = EventPayload<'payment:response'>;
+/** Payment parameters (without reqId, which is auto-generated). */
+type PaymentParams = Omit<PaymentRequestPayload, 'reqId'>;
+/** Payment response status from the host app. */
+type PaymentResponseStatus = PaymentResponsePayload['status'];
+/** Payment error codes from the host app. */
+type PaymentErrorCode = NonNullable<PaymentResponsePayload['errorCode']>;
+/** Payment status states for the hook. */
+type PaymentStatus = 'idle' | 'loading' | PaymentResponseStatus;
+/**
+ * Payment result returned after a payment attempt.
+ */
+interface PaymentResult {
+  status: PaymentStatus;
+  txHash?: string;
+  errorCode?: PaymentErrorCode;
+  error?: Error;
+}
+/**
+ * Callbacks for payment status changes.
+ */
+interface PaymentCallbacks {
+  /** Called when payment succeeds. */
+  onPaid?: (txHash: string) => void;
+  /** Called when user cancels the payment. */
+  onCancelled?: () => void;
+  /** Called when payment fails. */
+  onFailed?: (errorCode: PaymentErrorCode, error?: Error) => void;
+  /** Called on any status change. */
+  onStatusChange?: (status: PaymentStatus) => void;
+}
+/**
+ * Options for the usePayment hook.
+ */
+interface UsePaymentOptions extends PaymentCallbacks {
+  /**
+   * Timeout for the payment request in milliseconds.
+   * @default 120000 (2 minutes)
+   */
+  timeout?: number;
+}
+/**
+ * Return type of the usePayment hook.
+ */
+interface UsePaymentReturn {
+  /** Current payment status. */
+  status: PaymentStatus;
+  /** Whether a payment is in progress. */
+  isLoading: boolean;
+  /** Whether the payment was successful. */
+  isPaid: boolean;
+  /** Whether the payment was cancelled. */
+  isCancelled: boolean;
+  /** Whether the payment failed. */
+  isFailed: boolean;
+  /** Transaction hash (present when paid). */
+  txHash?: string;
+  /** Error code (present when failed). */
+  errorCode?: PaymentErrorCode;
+  /** Error object if an error occurred. */
+  error?: Error;
+  /** Initiate a payment. */
+  pay: (params: PaymentParams) => Promise<PaymentResult>;
+  /** Reset the payment state to idle. */
+  reset: () => void;
+  /** Whether the payment method is supported by the host app. */
+  supported: boolean;
+}
+/**
+ * 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>
+ *   );
+ * }
+ * ```
+ */
+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 };