@fivenorth/loop-sdk 0.8.0 → 0.9.0

package/README.md

@@ -149,7 +149,23 @@ try {
 }
 ```
 
-Transaction responses include `command_id`, `submission_id`, `transaction_data`, and `update_id` when available. For token transfers, `update_id` may arrive later (once indexed), in which case `onTransactionUpdate` fires with the finalized `update_id`. Non-transfer transactions do not receive an `update_id` via this mechanism.
+`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
 
@@ -179,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

@@ -2375,7 +2375,11 @@ class Provider {
   }
   handleResponse(message) {
     console.log("Received response:", message);
-    if (message?.type === "transaction_completed" /* TRANSACTION_COMPLETED */ && message?.payload?.update_id) {
+    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) {
@@ -2394,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 || {};
@@ -2423,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,

package/package.json

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