@alien_org/contract 0.1.1 → 0.1.3

package/dist/index.cjs

@@ -14,7 +14,8 @@ const releases = {
 		"payment:request",
 		"clipboard:write",
 		"clipboard:read"
-	]
+	],
+	"0.1.3": ["link:open"]
 };
 
 //#endregion

package/dist/index.d.cts

@@ -44,6 +44,49 @@ type If<Cond extends boolean, True, False> = Cond extends true ? True : False;
  * // 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 = 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+/**
+ * Webhook status for payment results (on-chain truth).
+ * - `'finalized'`: Transaction confirmed on-chain
+ * - `'failed'`: Transaction failed on-chain
+ * @since 0.1.2
+ * @schema
+ */
+type PaymentWebhookStatus = 'finalized' | 'failed';
+/**
+ * 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}`;
 //#endregion
 //#region src/events/types/payload.d.ts
 /**
@@ -91,11 +134,11 @@ interface Events {
      * Payment status.
      * - `paid`: Success
      * - `cancelled`: User rejected
-     * - `failed`: Error (check `errorCode`)
+     * - `error`: Error (check `errorCode`)
      * @since 0.1.1
      * @schema
      */
-    status: 'paid' | 'cancelled' | 'failed';
+    status: 'paid' | 'cancelled' | 'error';
     /**
      * Transaction hash (present when status is 'paid').
      * @since 0.1.1
@@ -112,7 +155,7 @@ interface Events {
      * @since 0.1.1
      * @schema
      */
-    errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+    errorCode?: PaymentErrorCode;
   }>>;
   /**
    * Clipboard read response.
@@ -264,37 +307,62 @@ interface Methods {
      */
     invoice: string;
     /**
-     * Item title shown on the approval screen.
+     * Optional item details shown on the approval screen.
      * @since 0.1.1
      * @schema
      */
-    title?: 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;
+    };
     /**
-     * Item description/caption shown on the approval screen.
+     * 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
      */
-    caption?: 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;
-    /**
-     * 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.
@@ -315,6 +383,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 src/methods/types/method-types.d.ts
@@ -364,4 +470,4 @@ declare function isMethodSupported(method: MethodName, version: Version): boolea
  */
 declare function getMethodMinVersion(method: MethodName): Version | undefined;
 //#endregion
-export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type Platform, type Version, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };
+export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type PaymentErrorCode, type PaymentTestScenario, type PaymentWebhookStatus, type Platform, type Version, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };

package/dist/index.d.mts

@@ -44,6 +44,49 @@ type If<Cond extends boolean, True, False> = Cond extends true ? True : False;
  * // 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 = 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+/**
+ * Webhook status for payment results (on-chain truth).
+ * - `'finalized'`: Transaction confirmed on-chain
+ * - `'failed'`: Transaction failed on-chain
+ * @since 0.1.2
+ * @schema
+ */
+type PaymentWebhookStatus = 'finalized' | 'failed';
+/**
+ * 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}`;
 //#endregion
 //#region src/events/types/payload.d.ts
 /**
@@ -91,11 +134,11 @@ interface Events {
      * Payment status.
      * - `paid`: Success
      * - `cancelled`: User rejected
-     * - `failed`: Error (check `errorCode`)
+     * - `error`: Error (check `errorCode`)
      * @since 0.1.1
      * @schema
      */
-    status: 'paid' | 'cancelled' | 'failed';
+    status: 'paid' | 'cancelled' | 'error';
     /**
      * Transaction hash (present when status is 'paid').
      * @since 0.1.1
@@ -112,7 +155,7 @@ interface Events {
      * @since 0.1.1
      * @schema
      */
-    errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+    errorCode?: PaymentErrorCode;
   }>>;
   /**
    * Clipboard read response.
@@ -264,37 +307,62 @@ interface Methods {
      */
     invoice: string;
     /**
-     * Item title shown on the approval screen.
+     * Optional item details shown on the approval screen.
      * @since 0.1.1
      * @schema
      */
-    title?: 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;
+    };
     /**
-     * Item description/caption shown on the approval screen.
+     * 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
      */
-    caption?: 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;
-    /**
-     * 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.
@@ -315,6 +383,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 src/methods/types/method-types.d.ts
@@ -364,4 +470,4 @@ declare function isMethodSupported(method: MethodName, version: Version): boolea
  */
 declare function getMethodMinVersion(method: MethodName): Version | undefined;
 //#endregion
-export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type Platform, type Version, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };
+export { type CreateEventPayload, type CreateMethodPayload, type EventName, type EventPayload, type Events, type LaunchParams, type MethodName, type MethodNameWithVersionedPayload, type MethodPayload, type MethodVersionedPayload, type Methods, PLATFORMS, type PaymentErrorCode, type PaymentTestScenario, type PaymentWebhookStatus, type Platform, type Version, getMethodMinVersion, getReleaseVersion, isMethodSupported, releases };

package/dist/index.mjs

@@ -13,7 +13,8 @@ const releases = {
 		"payment:request",
 		"clipboard:write",
 		"clipboard:read"
-	]
+	],
+	"0.1.3": ["link:open"]
 };
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alien_org/contract",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",