@alien_org/react 0.1.3 → 0.2.0

package/dist/index.d.cts

@@ -33,6 +33,41 @@ type UnionKeys<T> = T extends T ? keyof T : never;
  * // Empty = {}
  */
 type Empty = Record<string, never>;
+/**
+ * Client-side payment error codes (pre-broadcast failures).
+ * Returned when `status` is `'failed'` in `payment:response`.
+ * These errors occur before transaction broadcast, so no webhook is sent.
+ * @since 0.1.1
+ * @schema
+ */
+type PaymentErrorCode$1 = 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+/**
+ * Payment test scenarios for simulating different payment outcomes.
+ *
+ * | Scenario | Client sees | Webhook |
+ * |----------|-------------|---------|
+ * | `'paid'` | `paid` | `{ status: 'finalized' }` |
+ * | `'paid:failed'` | `paid` | `{ status: 'failed' }` |
+ * | `'cancelled'` | `cancelled` | none |
+ * | `'error:*'` | `failed` | none (pre-broadcast) |
+ *
+ * @example
+ * // Happy path: client paid, tx finalized
+ * test: 'paid'
+ *
+ * // On-chain failure: client paid, tx failed
+ * test: 'paid:failed'
+ *
+ * // User cancelled before confirming
+ * test: 'cancelled'
+ *
+ * // Pre-broadcast error (no tx, no webhook)
+ * test: 'error:insufficient_balance'
+ *
+ * @since 0.1.2
+ * @schema
+ */
+type PaymentTestScenario = 'paid' | 'paid:failed' | 'cancelled' | `error:${PaymentErrorCode$1}`;
 //#endregion
 //#region ../contract/src/events/types/payload.d.ts
 /**
@@ -80,7 +115,7 @@ interface Events {
      * Payment status.
      * - `paid`: Success
      * - `cancelled`: User rejected
-     * - `failed`: Error (check `errorCode`)
+     * - `failed`: Sending transaction failed (check `errorCode`)
      * @since 0.1.1
      * @schema
      */
@@ -101,7 +136,7 @@ interface Events {
      * @since 0.1.1
      * @schema
      */
-    errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+    errorCode?: PaymentErrorCode$1;
   }>>;
   /**
    * Clipboard read response.
@@ -253,37 +288,62 @@ interface Methods {
      */
     invoice: string;
     /**
-     * Item title shown on the approval screen.
-     * @since 0.1.1
-     * @schema
-     */
-    title?: string;
-    /**
-     * Item description/caption shown on the approval screen.
-     * @since 0.1.1
-     * @schema
-     */
-    caption?: string;
-    /**
-     * Item icon URL shown on the approval screen.
+     * Optional item details shown on the approval screen.
      * @since 0.1.1
      * @schema
      */
-    iconUrl?: string;
+    item?: {
+      /**
+       * Item title shown on the approval screen.
+       * @since 0.1.1
+       * @schema
+       */
+      title: string;
+      /**
+       * Item icon URL shown on the approval screen.
+       * @since 0.1.1
+       * @schema
+       */
+      iconUrl: string;
+      /**
+       * Quantity of items being purchased.
+       * @since 0.1.1
+       * @schema
+       */
+      quantity: number;
+    };
     /**
-     * Quantity of items being purchased.
+     * Test mode. Simulates payment outcomes without real transactions.
+     *
+     * | Scenario | Client | Webhook |
+     * |----------|--------|---------|
+     * | `true` / `'paid'` | `paid` | `finalized` |
+     * | `'paid:failed'` | `paid` | `failed` |
+     * | `'cancelled'` | `cancelled` | none |
+     * | `'error:*'` | `failed` | none |
+     *
+     * **Pre-broadcast errors** (no webhook):
+     * `'error:insufficient_balance'`, `'error:network_error'`,
+     * `'error:pre_checkout_rejected'`, `'error:pre_checkout_timeout'`,
+     * `'error:unknown'`
+     *
+     * @example
+     * // Happy path
+     * test: 'paid'
+     *
+     * // Client shows success, but tx failed on-chain
+     * test: 'paid:failed'
+     *
+     * // User cancelled
+     * test: 'cancelled'
+     *
+     * // Pre-broadcast failure
+     * test: 'error:insufficient_balance'
+     *
      * @since 0.1.1
      * @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.1.1
-     * @schema
-     */
-    test?: boolean;
+    test?: boolean | PaymentTestScenario;
   }>>;
   /**
    * Write text to the system clipboard.
@@ -304,6 +364,44 @@ interface Methods {
    * @schema
    */
   'clipboard:read': CreateMethodPayload<WithReqId<Empty>>;
+  /**
+   * Open a URL.
+   *
+   * The host app acts as middleware: parses the URL, checks permissions/auth,
+   * and routes to the appropriate handler based on URL and `openMode`.
+   *
+   * **`external`** (default) - Open outside the host app:
+   * - Custom schemes (`solana:`, `mailto:`) → system handler
+   * - HTTPS → system browser
+   *
+   * **`internal`** - Open within the host app:
+   * - Miniapp links → open miniapp (handles auth if required)
+   * - Other links → in-app webview
+   *
+   * @example
+   * emit('link:open', { url: 'solana:...' });
+   * emit('link:open', { url: 'mailto:hi@example.com' });
+   * emit('link:open', { url: 'https://example.com', openMode: 'internal' });
+   *
+   * @since 0.1.3
+   * @schema
+   */
+  'link:open': CreateMethodPayload<{
+    /**
+     * The URL to open.
+     * @since 0.1.3
+     * @schema
+     */
+    url: string;
+    /**
+     * Where to open the URL.
+     * - `external` (default): System browser or app handler
+     * - `internal`: Within the host app (miniapps, webviews)
+     * @since 0.1.3
+     * @schema
+     */
+    openMode?: 'external' | 'internal';
+  }>;
 }
 //#endregion
 //#region ../contract/src/methods/types/method-types.d.ts
@@ -314,6 +412,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.

package/dist/index.d.mts

@@ -33,6 +33,41 @@ type UnionKeys<T> = T extends T ? keyof T : never;
  * // Empty = {}
  */
 type Empty = Record<string, never>;
+/**
+ * Client-side payment error codes (pre-broadcast failures).
+ * Returned when `status` is `'failed'` in `payment:response`.
+ * These errors occur before transaction broadcast, so no webhook is sent.
+ * @since 0.1.1
+ * @schema
+ */
+type PaymentErrorCode$1 = 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+/**
+ * Payment test scenarios for simulating different payment outcomes.
+ *
+ * | Scenario | Client sees | Webhook |
+ * |----------|-------------|---------|
+ * | `'paid'` | `paid` | `{ status: 'finalized' }` |
+ * | `'paid:failed'` | `paid` | `{ status: 'failed' }` |
+ * | `'cancelled'` | `cancelled` | none |
+ * | `'error:*'` | `failed` | none (pre-broadcast) |
+ *
+ * @example
+ * // Happy path: client paid, tx finalized
+ * test: 'paid'
+ *
+ * // On-chain failure: client paid, tx failed
+ * test: 'paid:failed'
+ *
+ * // User cancelled before confirming
+ * test: 'cancelled'
+ *
+ * // Pre-broadcast error (no tx, no webhook)
+ * test: 'error:insufficient_balance'
+ *
+ * @since 0.1.2
+ * @schema
+ */
+type PaymentTestScenario = 'paid' | 'paid:failed' | 'cancelled' | `error:${PaymentErrorCode$1}`;
 //#endregion
 //#region ../contract/src/events/types/payload.d.ts
 /**
@@ -80,7 +115,7 @@ interface Events {
      * Payment status.
      * - `paid`: Success
      * - `cancelled`: User rejected
-     * - `failed`: Error (check `errorCode`)
+     * - `failed`: Sending transaction failed (check `errorCode`)
      * @since 0.1.1
      * @schema
      */
@@ -101,7 +136,7 @@ interface Events {
      * @since 0.1.1
      * @schema
      */
-    errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+    errorCode?: PaymentErrorCode$1;
   }>>;
   /**
    * Clipboard read response.
@@ -253,37 +288,62 @@ interface Methods {
      */
     invoice: string;
     /**
-     * Item title shown on the approval screen.
-     * @since 0.1.1
-     * @schema
-     */
-    title?: string;
-    /**
-     * Item description/caption shown on the approval screen.
-     * @since 0.1.1
-     * @schema
-     */
-    caption?: string;
-    /**
-     * Item icon URL shown on the approval screen.
+     * Optional item details shown on the approval screen.
      * @since 0.1.1
      * @schema
      */
-    iconUrl?: string;
+    item?: {
+      /**
+       * Item title shown on the approval screen.
+       * @since 0.1.1
+       * @schema
+       */
+      title: string;
+      /**
+       * Item icon URL shown on the approval screen.
+       * @since 0.1.1
+       * @schema
+       */
+      iconUrl: string;
+      /**
+       * Quantity of items being purchased.
+       * @since 0.1.1
+       * @schema
+       */
+      quantity: number;
+    };
     /**
-     * Quantity of items being purchased.
+     * Test mode. Simulates payment outcomes without real transactions.
+     *
+     * | Scenario | Client | Webhook |
+     * |----------|--------|---------|
+     * | `true` / `'paid'` | `paid` | `finalized` |
+     * | `'paid:failed'` | `paid` | `failed` |
+     * | `'cancelled'` | `cancelled` | none |
+     * | `'error:*'` | `failed` | none |
+     *
+     * **Pre-broadcast errors** (no webhook):
+     * `'error:insufficient_balance'`, `'error:network_error'`,
+     * `'error:pre_checkout_rejected'`, `'error:pre_checkout_timeout'`,
+     * `'error:unknown'`
+     *
+     * @example
+     * // Happy path
+     * test: 'paid'
+     *
+     * // Client shows success, but tx failed on-chain
+     * test: 'paid:failed'
+     *
+     * // User cancelled
+     * test: 'cancelled'
+     *
+     * // Pre-broadcast failure
+     * test: 'error:insufficient_balance'
+     *
      * @since 0.1.1
      * @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.1.1
-     * @schema
-     */
-    test?: boolean;
+    test?: boolean | PaymentTestScenario;
   }>>;
   /**
    * Write text to the system clipboard.
@@ -304,6 +364,44 @@ interface Methods {
    * @schema
    */
   'clipboard:read': CreateMethodPayload<WithReqId<Empty>>;
+  /**
+   * Open a URL.
+   *
+   * The host app acts as middleware: parses the URL, checks permissions/auth,
+   * and routes to the appropriate handler based on URL and `openMode`.
+   *
+   * **`external`** (default) - Open outside the host app:
+   * - Custom schemes (`solana:`, `mailto:`) → system handler
+   * - HTTPS → system browser
+   *
+   * **`internal`** - Open within the host app:
+   * - Miniapp links → open miniapp (handles auth if required)
+   * - Other links → in-app webview
+   *
+   * @example
+   * emit('link:open', { url: 'solana:...' });
+   * emit('link:open', { url: 'mailto:hi@example.com' });
+   * emit('link:open', { url: 'https://example.com', openMode: 'internal' });
+   *
+   * @since 0.1.3
+   * @schema
+   */
+  'link:open': CreateMethodPayload<{
+    /**
+     * The URL to open.
+     * @since 0.1.3
+     * @schema
+     */
+    url: string;
+    /**
+     * Where to open the URL.
+     * - `external` (default): System browser or app handler
+     * - `internal`: Within the host app (miniapps, webviews)
+     * @since 0.1.3
+     * @schema
+     */
+    openMode?: 'external' | 'internal';
+  }>;
 }
 //#endregion
 //#region ../contract/src/methods/types/method-types.d.ts
@@ -314,6 +412,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.

package/package.json

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