@fivenorth/loop-sdk 0.7.6 → 0.9.0

package/README.md

@@ -29,7 +29,7 @@ import { loop } from '@fivenorth/loop-sdk';
 Note that, If you don't want to implement a build process, you can include the file directly with `unpkg` such as 
 
 ```javascript
-import { loop } from 'https://unpkg.com/@fivenorth/loop-sdk@0.1.1/dist';
+import { loop } from 'https://unpkg.com/@fivenorth/loop-sdk@0.8.0/dist';
 ```
 
 An example of how we use it in that manner is on our [loopsdk demo](https://codepen.io/kureikain/pen/KwVGgLX)
@@ -42,6 +42,9 @@ Before you can connect, you need to initialize the SDK. This is typically done o
 loop.init({
     appName: 'My Awesome dApp',
     network: 'local', // or 'devnet', 'mainnet'
+    onTransactionUpdate: (payload) => {
+        console.log('Transaction update:', payload);
+    },
     options: {
         openMode: 'popup', // 'popup' (default) or 'tab'
         requestSigningMode: 'popup', // 'popup' (default) or 'tab'
@@ -60,6 +63,7 @@ loop.init({
 The `init` method takes a configuration object with the following properties:
 - `appName`: The name of your application, which will be displayed to the user in the Loop wallet.
 - `network`: The network to connect to. Can be `local`, `devnet`, or `mainnet`.
+- `onTransactionUpdate`: Called when a transaction update is finalized (includes `update_id` and optional `update_data`).
 - `options`: Optional object containing:
   - `openMode`: Controls how Loop opens: `'popup'` (default) or `'tab'`.
   - `requestSigningMode`: Controls how signing/transaction requests open the wallet UI after you're connected: `'popup'` (default) or `'tab'`.
@@ -145,6 +149,24 @@ try {
 }
 ```
 
+`onTransactionUpdate` fires once per transaction with a single payload that includes `command_id` and `submission_id`. On success it also includes `update_id` and `update_data` (ledger transaction tree); on failure it includes `status: "failed"` and `error.error_message`.
+
+`submitTransaction` is the default async path. It returns the submission result first (including `command_id` and `submission_id`), then the ledger update arrives later via `onTransactionUpdate` with `update_id` and `update_data`.
+
+To wait for the transaction result directly (opt-in), use:
+
+```javascript
+await provider.submitAndWaitForTransaction(damlCommand, {
+    message: 'Transfer 10 CC to RetailStore',
+});
+```
+
+In wait mode, the final result is returned as a single `onTransactionUpdate` payload (command/submission IDs plus update data or failure status).
+
+Note: `submitAndWaitForTransaction` errors do not always mean the transaction failed. A 4xx error (e.g., 400) indicates a definite failure. A 5xx/timeout can mean the ledger is slow or backed up; the transaction may still be committed later, so clients should continue to listen for updates rather than assume failure.
+
+Deduplication: both async execute and execute-and-wait use a 1 hour deduplication window. If you retry within that window, resubmit the same `command_id` and `submission_id` so the request is idempotent.
+
 #### Sign a Message
 
 You can request the user to sign an arbitrary message:
@@ -173,6 +195,7 @@ await loop.wallet.transfer(
   {
     // Optional: show a custom message in the wallet prompt
     message: 'Send 5 CC to Alice',
+    executionMode: 'wait',                   // optional: 'async' (default) or 'wait'
     requestedAt: new Date().toISOString(),   // optional
     executeBefore: new Date(Date.now() + 24*60*60*1000).toISOString(), // optional
     requestTimeout: 5 * 60 * 1000,           // optional (ms), defaults to 5 minutes

package/dist/index.js

@@ -2321,7 +2321,7 @@ var MessageType;
   MessageType2["HANDSHAKE_ACCEPT"] = "handshake_accept";
   MessageType2["HANDSHAKE_REJECT"] = "handshake_reject";
   MessageType2["RUN_TRANSACTION"] = "run_transaction";
-  MessageType2["RUN_TRANSACTION_RESPONSE"] = "run_transaction_response";
+  MessageType2["TRANSACTION_COMPLETED"] = "transaction_completed";
   MessageType2["SIGN_RAW_MESSAGE"] = "sign_raw_message";
   MessageType2["SIGN_RAW_MESSAGE_RESPONSE"] = "sign_raw_message_response";
   MessageType2["REJECT_REQUEST"] = "reject_request";
@@ -2375,6 +2375,13 @@ class Provider {
   }
   handleResponse(message) {
     console.log("Received response:", message);
+    if (message?.type === "transaction_completed" /* TRANSACTION_COMPLETED */ && (message?.payload?.update_id || message?.payload?.update_data || message?.payload?.status)) {
+      if (message?.payload?.error_message) {
+        message.payload.error = { error_message: message.payload.error_message };
+        delete message.payload.error_message;
+      }
+      this.hooks?.onTransactionUpdate?.(message.payload, message);
+    }
     if (message.request_id) {
       this.requests.set(message.request_id, message);
     }
@@ -2391,6 +2398,9 @@ class Provider {
   async submitTransaction(payload, options) {
     return this.sendRequest("run_transaction" /* RUN_TRANSACTION */, payload, options);
   }
+  async submitAndWaitForTransaction(payload, options) {
+    return this.sendRequest("run_transaction" /* RUN_TRANSACTION */, { ...payload, execution_mode: "wait" }, options);
+  }
   async transfer(recipient, amount, instrument, options) {
     const amountStr = typeof amount === "number" ? amount.toString() : amount;
     const { requestedAt, executeBefore, requestTimeout } = options || {};
@@ -2420,7 +2430,8 @@ class Provider {
       execute_before: executeBeforeIso
     };
     const preparedPayload = await this.connection.prepareTransfer(this.auth_token, transferRequest);
-    return this.submitTransaction({
+    const submitFn = options?.executionMode === "wait" ? this.submitAndWaitForTransaction.bind(this) : this.submitTransaction.bind(this);
+    return submitFn({
       commands: preparedPayload.commands,
       disclosedContracts: preparedPayload.disclosedContracts,
       packageIdSelectionPreference: preparedPayload.packageIdSelectionPreference,
@@ -2705,6 +2716,7 @@ class LoopSDK {
   redirectUrl;
   onAccept = null;
   onReject = null;
+  onTransactionUpdate = null;
   overlay = null;
   wallet;
   constructor() {
@@ -2717,6 +2729,7 @@ class LoopSDK {
     apiUrl,
     onAccept,
     onReject,
+    onTransactionUpdate,
     options
   }) {
     if (typeof window === "undefined" || typeof document === "undefined" || typeof localStorage === "undefined") {
@@ -2725,6 +2738,7 @@ class LoopSDK {
     this.appName = appName;
     this.onAccept = onAccept || null;
     this.onReject = onReject || null;
+    this.onTransactionUpdate = onTransactionUpdate || null;
     const resolvedOptions = {
       openMode: "popup",
       requestSigningMode: "popup",
@@ -3115,7 +3129,8 @@ class LoopSDK {
             this.closePopupIfExists();
           }, 800);
         }
-      }
+      },
+      onTransactionUpdate: this.onTransactionUpdate ?? undefined
     };
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fivenorth/loop-sdk",
-	"version": "0.7.6",
+	"version": "0.9.0",
 	"author": "support@fivenorth.io",
 	"main": "dist/index.js",
 	"module": "dist/index.js",