@alien_org/contract 0.1.0 → 0.1.2

package/dist/index.cjs

@@ -9,7 +9,12 @@ const PLATFORMS = ["ios", "android"];
 //#region src/methods/versions/releases.ts
 const releases = {
 	"0.0.9": ["app:ready"],
-	"0.0.14": ["miniapp:close.ack", "host.back.button:toggle"]
+	"0.0.14": ["miniapp:close.ack", "host.back.button:toggle"],
+	"0.1.1": [
+		"payment:request",
+		"clipboard:write",
+		"clipboard:read"
+	]
 };
 
 //#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
 /**
@@ -83,7 +126,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<{
@@ -91,14 +134,14 @@ interface Events {
      * Payment status.
      * - `paid`: Success
      * - `cancelled`: User rejected
-     * - `failed`: Error (check `errorCode`)
-     * @since 0.0.14
+     * - `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.0.14
+     * @since 0.1.1
      * @schema
      */
     txHash?: string;
@@ -109,10 +152,35 @@ 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?: PaymentErrorCode;
+  }>>;
+  /**
+   * 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
      */
-    errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+    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
@@ -204,73 +272,117 @@ 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
+     * 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.
-     * @since 0.0.14
-     * @schema
-     */
-    caption?: string;
-    /**
-     * Item icon URL shown on the approval screen.
-     * @since 0.0.14
+     * 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
      */
-    iconUrl?: string;
-    /**
-     * Quantity of items being purchased.
-     * @since 0.0.14
-     * @schema
-     */
-    quantity?: number;
+    test?: boolean | PaymentTestScenario;
+  }>>;
+  /**
+   * Write text to the system clipboard.
+   * @since 0.1.1
+   * @schema
+   */
+  'clipboard:write': CreateMethodPayload<{
     /**
-     * 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
+     * Text to copy to clipboard.
+     * @since 0.1.1
      * @schema
      */
-    test?: boolean;
-  }>>;
+    text: string;
+  }>;
+  /**
+   * Read text from the system clipboard.
+   * @since 0.1.1
+   * @schema
+   */
+  'clipboard:read': CreateMethodPayload<WithReqId<Empty>>;
 }
 //#endregion
 //#region src/methods/types/method-types.d.ts
@@ -320,4 +432,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
 /**
@@ -83,7 +126,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<{
@@ -91,14 +134,14 @@ interface Events {
      * Payment status.
      * - `paid`: Success
      * - `cancelled`: User rejected
-     * - `failed`: Error (check `errorCode`)
-     * @since 0.0.14
+     * - `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.0.14
+     * @since 0.1.1
      * @schema
      */
     txHash?: string;
@@ -109,10 +152,35 @@ 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?: PaymentErrorCode;
+  }>>;
+  /**
+   * 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
      */
-    errorCode?: 'insufficient_balance' | 'network_error' | 'pre_checkout_rejected' | 'pre_checkout_timeout' | 'unknown';
+    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
@@ -204,73 +272,117 @@ 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
+     * 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.
-     * @since 0.0.14
-     * @schema
-     */
-    caption?: string;
-    /**
-     * Item icon URL shown on the approval screen.
-     * @since 0.0.14
+     * 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
      */
-    iconUrl?: string;
-    /**
-     * Quantity of items being purchased.
-     * @since 0.0.14
-     * @schema
-     */
-    quantity?: number;
+    test?: boolean | PaymentTestScenario;
+  }>>;
+  /**
+   * Write text to the system clipboard.
+   * @since 0.1.1
+   * @schema
+   */
+  'clipboard:write': CreateMethodPayload<{
     /**
-     * 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
+     * Text to copy to clipboard.
+     * @since 0.1.1
      * @schema
      */
-    test?: boolean;
-  }>>;
+    text: string;
+  }>;
+  /**
+   * Read text from the system clipboard.
+   * @since 0.1.1
+   * @schema
+   */
+  'clipboard:read': CreateMethodPayload<WithReqId<Empty>>;
 }
 //#endregion
 //#region src/methods/types/method-types.d.ts
@@ -320,4 +432,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

@@ -8,7 +8,12 @@ const PLATFORMS = ["ios", "android"];
 //#region src/methods/versions/releases.ts
 const releases = {
 	"0.0.9": ["app:ready"],
-	"0.0.14": ["miniapp:close.ack", "host.back.button:toggle"]
+	"0.0.14": ["miniapp:close.ack", "host.back.button:toggle"],
+	"0.1.1": [
+		"payment:request",
+		"clipboard:write",
+		"clipboard:read"
+	]
 };
 
 //#endregion

package/package.json

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