@secretkeylabs/stacks-tools 0.6.0 → 0.7.0-3be878c

package/dist/index.js

@@ -1,20 +1,44 @@
 // src/utils/safe.ts
+import { backOff } from "exponential-backoff";
 function success(data) {
   return [null, data];
 }
-function error(error2) {
-  return [error2, null];
+function error(errorArg) {
+  return [errorArg, null];
 }
 async function safePromise(promise) {
   try {
     return success(await promise);
   } catch (e) {
+    return error({ name: "SafeError", message: "Promise rejected.", data: e });
+  }
+}
+var defaultStartingDelay = 15e3;
+var defaultNumOfAttempts = 5;
+async function safeBackOff(promise, options) {
+  const [backoffError, data] = await safePromise(
+    backOff(
+      async () => {
+        const [error2, data2] = await promise;
+        if (error2) {
+          throw error2;
+        }
+        return data2;
+      },
+      {
+        startingDelay: options?.startingDelay ?? defaultStartingDelay,
+        numOfAttempts: options?.numOfAttempts ?? defaultNumOfAttempts
+      }
+    )
+  );
+  if (backoffError) {
     return error({
-      name: "SafePromiseError",
-      message: "Safe promise rejected.",
-      data: e
+      name: "BackoffError",
+      message: "Retries exceeded.",
+      data: backoffError.data
     });
   }
+  return success(data);
 }
 function safeCall(fn) {
   try {
@@ -27,6 +51,29 @@ function safeCall(fn) {
     });
   }
 }
+function flatResults(results) {
+  const errors = results.map((r) => r[0]).filter((maybeError) => maybeError !== null);
+  if (errors.length !== 0)
+    return error({
+      name: "FlatResultsError",
+      message: `Found ${errors.length} errors in result array of length ${results.length}.`,
+      data: errors.slice(0, 10)
+      // Only show first 10 errors to avoid spamming logs
+    });
+  const values = results.map((r) => r[1]);
+  return [null, values];
+}
+async function safeExtractResponseBody(response) {
+  try {
+    return await response.json();
+  } catch {
+    try {
+      return await response.text();
+    } catch {
+      return void 0;
+    }
+  }
+}
 
 // src/stacks-api/accounts/balances.ts
 async function balances(opts) {
@@ -48,7 +95,7 @@ async function balances(opts) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -89,7 +136,7 @@ async function latestNonce(opts) {
         endpoint,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -168,7 +215,7 @@ async function getBlock(opts) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -217,7 +264,7 @@ async function stx(opts) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -270,7 +317,7 @@ async function coreApi(apiOpts) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -325,7 +372,7 @@ async function cycle(opts) {
         endpoint,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -383,7 +430,7 @@ async function cycles(args) {
         endpoint,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -500,7 +547,7 @@ async function signersInCycle(args) {
         endpoint,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -511,7 +558,7 @@ async function signersInCycle(args) {
       message: "Failed to parse response body as JSON.",
       data: {
         endpoint,
-        bodyParseResult: data
+        body: data
       }
     });
   }
@@ -527,18 +574,6 @@ async function signersInCycle(args) {
 }
 
 // src/stacks-api/proof-of-transfer/stackers-for-signer-in-cycle.ts
-import * as v9 from "valibot";
-var stackerInfoSchema = v9.object({
-  stacker_address: v9.string(),
-  stacked_amount: v9.string(),
-  pox_address: v9.string(),
-  stacker_type: v9.union([v9.literal("pooled"), v9.literal("solo")])
-});
-var resultsSchema3 = v9.array(stackerInfoSchema);
-var stackersForSignerInCycleResponseSchema = v9.object({
-  ...baseListResponseSchema.entries,
-  results: resultsSchema3
-});
 async function stackersForSignerInCycle(opts) {
   const search = new URLSearchParams();
   if (opts.limit) search.append("limit", opts.limit.toString());
@@ -560,7 +595,7 @@ async function stackersForSignerInCycle(opts) {
         endpoint,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -572,18 +607,7 @@ async function stackersForSignerInCycle(opts) {
       data: jsonError
     });
   }
-  const validationResult = v9.safeParse(
-    stackersForSignerInCycleResponseSchema,
-    data
-  );
-  if (!validationResult.success) {
-    return error({
-      name: "ValidateDataError",
-      message: "Failed to validate response data.",
-      data: validationResult
-    });
-  }
-  return success(validationResult.output);
+  return success(data);
 }
 
 // src/stacks-api/proof-of-transfer/index.ts
@@ -596,21 +620,6 @@ var proofOfTransfer = {
 };
 
 // src/stacks-api/stacking-pool/members.ts
-import * as v10 from "valibot";
-var memberSchema = v10.object({
-  stacker: v10.string(),
-  pox_addr: v10.optional(v10.string()),
-  amount_ustx: v10.string(),
-  burn_block_unlock_height: v10.optional(v10.number()),
-  block_height: v10.number(),
-  tx_id: v10.string()
-});
-var membersResponseSchema = v10.object({
-  limit: v10.number(),
-  offset: v10.number(),
-  total: v10.number(),
-  results: v10.array(memberSchema)
-});
 async function members(args) {
   const search = new URLSearchParams();
   if (args.afterBlock) search.append("after_block", args.afterBlock.toString());
@@ -632,7 +641,7 @@ async function members(args) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -644,15 +653,7 @@ async function members(args) {
       data: jsonParseError
     });
   }
-  const validationResult = v10.safeParse(membersResponseSchema, data);
-  if (!validationResult.success) {
-    return error({
-      name: "ValidateDataError",
-      message: "Failed to validate data.",
-      data: validationResult
-    });
-  }
-  return success(validationResult.output);
+  return success(data);
 }
 
 // src/stacks-api/stacking-pool/index.ts
@@ -660,124 +661,7 @@ var stackingPool = {
   members
 };
 
-// src/stacks-api/transactions/schemas.ts
-import * as v11 from "valibot";
-var baseTransactionSchema = v11.object({
-  tx_id: v11.string(),
-  nonce: v11.number(),
-  fee_rate: v11.string(),
-  sender_address: v11.string(),
-  sponsored: v11.boolean(),
-  post_condition_mode: v11.string(),
-  post_conditions: v11.array(v11.unknown()),
-  anchor_mode: v11.string(),
-  is_unanchored: v11.boolean(),
-  block_hash: v11.string(),
-  parent_block_hash: v11.string(),
-  block_height: v11.number(),
-  block_time: v11.number(),
-  block_time_iso: v11.string(),
-  burn_block_height: v11.number(),
-  burn_block_time: v11.number(),
-  burn_block_time_iso: v11.string(),
-  parent_burn_block_time: v11.number(),
-  parent_burn_block_time_iso: v11.string(),
-  canonical: v11.boolean(),
-  tx_index: v11.number(),
-  tx_status: v11.union([
-    v11.literal("success"),
-    v11.literal("abort_by_response"),
-    v11.literal("abort_by_post_condition")
-  ]),
-  tx_result: v11.object({
-    hex: v11.string(),
-    repr: v11.string()
-  }),
-  microblock_hash: v11.string(),
-  microblock_sequence: v11.number(),
-  microblock_canonical: v11.boolean(),
-  event_count: v11.number(),
-  events: v11.array(v11.unknown()),
-  execution_cost_read_count: v11.number(),
-  execution_cost_read_length: v11.number(),
-  execution_cost_runtime: v11.number(),
-  execution_cost_write_count: v11.number(),
-  execution_cost_write_length: v11.number()
-});
-var contractCallTransactionSchema = v11.object({
-  tx_type: v11.literal("contract_call"),
-  contract_call: v11.object({
-    contract_id: v11.string(),
-    function_name: v11.string(),
-    function_signature: v11.string(),
-    function_args: v11.array(
-      v11.object({
-        hex: v11.string(),
-        repr: v11.string(),
-        name: v11.string(),
-        type: v11.string()
-      })
-    )
-  }),
-  ...baseTransactionSchema.entries
-});
-var smartContractTransactionSchema = v11.object({
-  tx_type: v11.literal("smart_contract"),
-  smart_contract: v11.object({
-    /**
-     * NOTE: The types may be wrong, not sure what type of value is used when
-     * the version is not `null`.
-     */
-    clarity_version: v11.union([v11.null(), v11.number()]),
-    contract_id: v11.string(),
-    source_code: v11.string()
-  }),
-  ...baseTransactionSchema.entries
-});
-var tokenTransferSchema = v11.object({
-  tx_type: v11.literal("token_transfer"),
-  token_transfer: v11.object({
-    recipient_address: v11.string(),
-    amount: v11.string(),
-    memo: v11.string()
-  }),
-  ...baseTransactionSchema.entries
-});
-var transactionSchema = v11.variant("tx_type", [
-  contractCallTransactionSchema,
-  smartContractTransactionSchema,
-  tokenTransferSchema
-]);
-
 // src/stacks-api/transactions/address-transactions.ts
-import * as v12 from "valibot";
-var resultSchema = v12.object({
-  tx: transactionSchema,
-  stx_sent: v12.string(),
-  stx_received: v12.string(),
-  events: v12.object({
-    stx: v12.object({
-      transfer: v12.number(),
-      mint: v12.number(),
-      burn: v12.number()
-    }),
-    ft: v12.object({
-      transfer: v12.number(),
-      mint: v12.number(),
-      burn: v12.number()
-    }),
-    nft: v12.object({
-      transfer: v12.number(),
-      mint: v12.number(),
-      burn: v12.number()
-    })
-  })
-});
-var resultsSchema4 = v12.array(resultSchema);
-var addressTransactionsResponseSchema = v12.object({
-  ...baseListResponseSchema.entries,
-  results: resultsSchema4
-});
 async function addressTransactions(args) {
   const search = new URLSearchParams();
   if (args.limit) search.append("limit", args.limit.toString());
@@ -799,7 +683,7 @@ async function addressTransactions(args) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -811,19 +695,47 @@ async function addressTransactions(args) {
       data: jsonParseError
     });
   }
-  const validationResult = v12.safeParse(addressTransactionsResponseSchema, data);
-  if (!validationResult.success) {
+  return success(data);
+}
+
+// src/stacks-api/transactions/events-for-an-address-transaction.ts
+async function eventsForAnAddressTransaction(args) {
+  const search = new URLSearchParams();
+  if (args.limit) search.append("limit", args.limit.toString());
+  if (args.offset) search.append("offset", args.offset.toString());
+  const init = {};
+  if (args.apiKeyConfig) {
+    init.headers = {
+      [args.apiKeyConfig.header]: args.apiKeyConfig.key
+    };
+  }
+  const endpoint = `${args.baseUrl}/extended/v2/addresses/${args.address}/transactions/${args.transactionId}/events?${search}`;
+  const res = await fetch(endpoint, init);
+  if (!res.ok) {
     return error({
-      name: "ValidateDataError",
-      message: "Failed to validate data.",
-      data: validationResult
+      name: "FetchEventsForAnAddressTransactionError",
+      message: `Failed to fetch address transaction events.`,
+      data: {
+        address: args.address,
+        transactionId: args.transactionId,
+        status: res.status,
+        statusText: res.statusText,
+        body: await safeExtractResponseBody(res)
+      }
     });
   }
-  return success(validationResult.output);
+  const [jsonParseError, data] = await safePromise(res.json());
+  if (jsonParseError) {
+    return error({
+      name: "ParseBodyError",
+      message: "Failed to parse response body as JSON.",
+      error: jsonParseError
+    });
+  }
+  return success(data);
 }
 
 // src/stacks-api/transactions/get-transaction.ts
-import * as v13 from "valibot";
 async function getTransaction(args) {
   const init = {};
   if (args.apiKeyConfig) {
@@ -836,11 +748,12 @@ async function getTransaction(args) {
   if (!res.ok) {
     return error({
       name: "FetchTransactionError",
-      message: `Failed to fetch transaction ${args.transactionId}`,
-      response: {
+      message: `Failed to fetch transaction.`,
+      data: {
+        transactionId: args.transactionId,
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -852,15 +765,7 @@ async function getTransaction(args) {
       error: jsonParseError
     });
   }
-  const validationResult = v13.safeParse(transactionSchema, data);
-  if (!validationResult.success) {
-    return error({
-      name: "ValidateDataError",
-      message: "Failed to validate data.",
-      error: validationResult
-    });
-  }
-  return success(validationResult.output);
+  return success(data);
 }
 
 // src/stacks-api/transactions/mempool-transactions.ts
@@ -891,7 +796,7 @@ async function mempoolTransactions(args) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -906,11 +811,46 @@ async function mempoolTransactions(args) {
   return success(data);
 }
 
+// src/stacks-api/transactions/get-raw-transaction.ts
+async function getRawTransaction(args) {
+  const init = {};
+  if (args.apiKeyConfig) {
+    init.headers = {
+      [args.apiKeyConfig.header]: args.apiKeyConfig.key
+    };
+  }
+  const endpoint = `${args.baseUrl}/extended/v1/tx/${args.transactionId}/raw`;
+  const res = await fetch(endpoint, init);
+  if (!res.ok) {
+    return error({
+      name: "RawTransactionFetchError",
+      message: `Failed to fetch raw transaction.`,
+      data: {
+        transactionId: args.transactionId,
+        status: res.status,
+        statusText: res.statusText,
+        body: await safeExtractResponseBody(res)
+      }
+    });
+  }
+  const [jsonParseError, data] = await safePromise(res.json());
+  if (jsonParseError) {
+    return error({
+      name: "ParseBodyError",
+      message: "Failed to parse response body as JSON.",
+      error: jsonParseError
+    });
+  }
+  return success(data);
+}
+
 // src/stacks-api/transactions/index.ts
 var transactions = {
   addressTransactions,
+  eventsForAnAddressTransaction,
   getTransaction,
-  mempoolTransactions
+  mempoolTransactions,
+  getRawTransaction
 };
 
 // src/stacks-api/mempool/transaction-fee-priorities.ts
@@ -930,7 +870,7 @@ async function transactionFeePriorities(opts) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyParseResult: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -963,16 +903,16 @@ var stacksApi = {
 };
 
 // src/stacks-rpc-api/smart-contracts/map-entry.ts
-import * as v14 from "valibot";
-var mapEntryResponseSchema = v14.object({
+import * as v9 from "valibot";
+var mapEntryResponseSchema = v9.object({
   /**
    * Hex-encoded string of clarity value. It is always an optional tuple.
    */
-  data: v14.string(),
+  data: v9.string(),
   /**
    * Hex-encoded string of the MARF proof for the data
    */
-  proof: v14.optional(v14.string())
+  proof: v9.optional(v9.string())
 });
 async function mapEntry(args) {
   const search = new URLSearchParams();
@@ -1000,7 +940,7 @@ async function mapEntry(args) {
         status: res.status,
         statusText: res.statusText,
         endpoint,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -1012,7 +952,7 @@ async function mapEntry(args) {
       data: jsonError
     });
   }
-  const validationResult = v14.safeParse(mapEntryResponseSchema, data);
+  const validationResult = v9.safeParse(mapEntryResponseSchema, data);
   if (!validationResult.success) {
     return error({
       name: "ValidateDataError",
@@ -1048,7 +988,7 @@ async function readOnly(args) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -1085,7 +1025,7 @@ async function contractInterface(args) {
         status: res.status,
         statusText: res.statusText,
         endpoint,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -1123,7 +1063,7 @@ async function poxDetails(args) {
       data: {
         status: res.status,
         statusText: res.statusText,
-        bodyText: await safePromise(res.text())
+        body: await safeExtractResponseBody(res)
       }
     });
   }
@@ -1150,18 +1090,18 @@ var stacksRpcApi = {
 };
 
 // src/utils/call-rate-limited-api.ts
-import { backOff } from "exponential-backoff";
-var defaultStartingDelay = 15e3;
-var defaultNumOfAttempts = 5;
+import { backOff as backOff2 } from "exponential-backoff";
+var defaultStartingDelay2 = 15e3;
+var defaultNumOfAttempts2 = 5;
 function callRateLimitedApi(fn, options) {
-  return backOff(fn, {
-    startingDelay: options?.startingDelay ?? defaultStartingDelay,
-    numOfAttempts: options?.numOfAttempts ?? defaultNumOfAttempts
+  return backOff2(fn, {
+    startingDelay: options?.startingDelay ?? defaultStartingDelay2,
+    numOfAttempts: options?.numOfAttempts ?? defaultNumOfAttempts2
   });
 }
 async function safeCallRateLimitedApi(fn, options) {
   try {
-    return await backOff(
+    return await backOff2(
       async () => {
         const [error2, data] = await fn();
         if (error2) {
@@ -1387,10 +1327,13 @@ var pox4Api = { maps, readOnly: readOnly2 };
 export {
   callRateLimitedApi,
   error,
+  flatResults,
   pox4Api,
   queries,
+  safeBackOff,
   safeCall,
   safeCallRateLimitedApi,
+  safeExtractResponseBody,
   safePromise,
   stacksApi,
   stacksRpcApi,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@secretkeylabs/stacks-tools",
-  "version": "0.6.0",
+  "version": "0.7.0-3be878c",
   "type": "module",
   "files": [
     "dist"
@@ -24,14 +24,14 @@
   "devDependencies": {
     "@arethetypeswrong/cli": "0.15.4",
     "@types/bun": "latest",
-    "prettier": "^3.3.3",
-    "tsup": "^8.3.5",
-    "typescript": "^5.0.0"
+    "prettier": "3.5.3",
+    "tsup": "8.5.0",
+    "typescript": "5.8.3"
   },
   "peerDependencies": {
-    "@stacks/blockchain-api-client": "^8.2.1",
+    "@stacks/blockchain-api-client": "8.11.1",
     "@stacks/transactions": "^7.0.0",
-    "valibot": "^0.42.1"
+    "valibot": "^1.1.0"
   },
   "dependencies": {
     "exponential-backoff": "3.1.1"