stxer 0.6.1 → 0.7.0

package/README.md

@@ -220,6 +220,40 @@ const sessionId = await createSimulationSession(
 );
 ```
 
+#### TransactionReceipt: failure signals & events
+
+When a step lands as `{ Transaction: { Ok: receipt } }`, the engine ran the transaction to completion — but that does **not** mean the contract logic succeeded. There are four failure signals on or around a receipt; check them in this order:
+
+| Signal | Where | Meaning |
+|---|---|---|
+| Outer `Err` | `Result.Transaction = { Err: string }` | Engine refused the tx (deserialization, etc.). No receipt is produced. |
+| `post_condition_aborted: true` | on the receipt | Execution ran, a post-condition tripped, state was rolled back. |
+| `vm_error: string` (without PC abort) | on the receipt | Clarity VM raised a runtime error (overflow, unwrap on `none`, etc.) or static analysis failed. |
+| `(err uX)` inside `result` | on the receipt | Contract returned a Clarity error response. Not signalled by any flag — decode `result` to detect (response::err prefix is `08`). |
+
+**`post_condition_aborted` and `vm_error` are not independent.** When a post-condition trips, the upstream sets `post_condition_aborted: true` *and* writes the PC abort reason into `vm_error` as a side effect — so `vm_error` is also non-null in that case. The reverse is not true: `vm_error` alone (with `post_condition_aborted: false`) means a VM/runtime/analysis failure that is *not* a PC abort. A clean way to narrow:
+
+```typescript
+if (receipt.post_condition_aborted) {
+  // PC abort. receipt.vm_error holds the abort reason.
+} else if (receipt.vm_error != null) {
+  // Runtime / analysis failure (not a PC abort).
+} else if (receipt.result.startsWith('08')) {
+  // Contract returned (err uX). Decode receipt.result for the value.
+} else {
+  // Clean success.
+}
+```
+
+**Events are JSON-encoded strings, not objects.** `receipt.events` is `string[]`; each entry is a JSON-encoded event payload. Call `JSON.parse(receipt.events[i])` to inspect — iterating without parsing yields opaque strings.
+
+```typescript
+for (const ev of receipt.events) {
+  const event = JSON.parse(ev) as { type: string; contract_event?: { ... } };
+  if (event.type === 'contract_event') { /* handle print/log */ }
+}
+```
+
 ### 3. Get Chain Tip
 
 Fetch the current chain tip information:
@@ -264,10 +298,10 @@ The SDK provides two approaches for efficient batch reading from the Stacks bloc
 #### Direct Batch Reading
 
 ```typescript
-import { batchRead } from 'stxer';
+import { batchRead, type BatchReadsResult } from 'stxer';
 
 // Batch read variables and maps
-const result = await batchRead({
+const result: BatchReadsResult = await batchRead({
   variables: [{
     contract: contractPrincipalCV(...),
     variableName: 'my-var'
@@ -283,6 +317,14 @@ const result = await batchRead({
     functionArgs: [/* clarity values */]
   }]
 });
+
+// Result shape — `index_block_hash` matches the upstream wire field
+// (the SDK previously aliased this as `tip`; renamed to remove the
+// indirection).
+result.index_block_hash;       // string — the block the batch ran against
+result.vars;                   // (ClarityValue | Error)[]
+result.maps;                   // (ClarityValue | Error)[]
+result.readonly;               // (ClarityValue | Error)[]
 ```
 
 #### BatchProcessor for Queue-based Operations
@@ -416,6 +458,28 @@ const ast = await getContractAST({
 });
 ```
 
+## Samples
+
+Runnable end-to-end examples live in [`src/sample/`](https://github.com/stxer/stxer-sdk/tree/master/src/sample) on GitHub. Samples track `master` and may evolve faster than published SDK versions; if you pin a specific SDK version, browse the matching git tag.
+
+| Sample | What it demonstrates |
+|---|---|
+| [`counter.ts`](https://github.com/stxer/stxer-sdk/blob/master/src/sample/counter.ts) | Full Simulation v2 lifecycle without `SimulationBuilder` — every `SimulationStepInput` variant (Transaction / Eval / SetContractCode / Reads / TenureExtend), narrowing on `SimulationStepResult`, and `SimulationStepSummary`. |
+| [`instant.ts`](https://github.com/stxer/stxer-sdk/blob/master/src/sample/instant.ts) | `instantSimulation` with all 7 `ReadStep` variants. |
+| [`failure-modes.ts`](https://github.com/stxer/stxer-sdk/blob/master/src/sample/failure-modes.ts) | The four failure signals on a `TransactionReceipt`, with bug-zoo triggers for each. |
+| [`batch-categories.ts`](https://github.com/stxer/stxer-sdk/blob/master/src/sample/batch-categories.ts) | Every `simulationBatchReads` category and the sidecar `batchRead`. |
+| [`contract-vitest.test.ts`](https://github.com/stxer/stxer-sdk/blob/master/src/sample/contract-vitest.test.ts) | Vitest suite that drives a Clarity contract through Simulation v2 — copy-pasteable CI test template. Pinned fork point so assertions stay deterministic. |
+| [`verify-types.ts`](https://github.com/stxer/stxer-sdk/blob/master/src/sample/verify-types.ts) | Runtime type-drift detector. Hits every endpoint, dereferences every documented field, asserts each value's runtime type matches the declared SDK type. Run it before publishing your client after upstream changes. |
+| [`read.ts`](https://github.com/stxer/stxer-sdk/blob/master/src/sample/read.ts) | `batchRead`, `BatchProcessor`, and the high-level `clarity-api` helpers (`callReadonly`, `readVariable`, `readMap`). |
+
+Run any of them locally by cloning the SDK repo and:
+
+```bash
+pnpm install
+pnpm sample:counter           # or sample:instant / failure-modes / batch-categories / verify-types
+pnpm sample:vitest            # run the Vitest contract-test sample
+```
+
 ## API Reference
 
 ### Constants

package/dist/batch-api.d.ts

@@ -23,7 +23,8 @@ export interface BatchReads {
     index_block_hash?: string;
 }
 export interface BatchReadsResult {
-    tip: string;
+    /** Index block hash the batch ran against. Matches the wire field name. */
+    index_block_hash: string;
     vars: (ClarityValue | Error)[];
     maps: (ClarityValue | Error)[];
     readonly: (ClarityValue | Error)[];

package/dist/index.d.ts

@@ -3,6 +3,6 @@ export * from './batch-api';
 export * from './clarity-api';
 export * from './constants';
 export * from './simulation';
-export { type CreateSessionOptions, createSimulationSession, getSimulationResult, instantSimulation, type SimulationApiOptions, simulationBatchReads, submitSimulationSteps, } from './simulation-api';
+export * from './simulation-api';
 export * from './tip';
 export * from './types';

package/dist/stxer.cjs.development.js

@@ -299,7 +299,7 @@ function _parseContract() {
 var DEFAULT_STXER_API = 'https://api.stxer.xyz';
 function convertResults(rs) {
   var results = [];
-  for (var _iterator = _createForOfIteratorHelperLoose(rs), _step; !(_step = _iterator()).done;) {
+  for (var _iterator = _createForOfIteratorHelperLoose(rs != null ? rs : []), _step; !(_step = _iterator()).done;) {
     var v = _step.value;
     if ('Ok' in v) {
       results.push(transactions.deserializeCV(v.Ok));
@@ -372,7 +372,7 @@ function _batchRead() {
         case 3:
           rs = JSON.parse(text);
           return _context.a(2, {
-            tip: rs.tip,
+            index_block_hash: rs.index_block_hash,
             vars: convertResults(rs.vars),
             maps: convertResults(rs.maps),
             readonly: convertResults(rs.readonly)
@@ -756,7 +756,7 @@ function _instantSimulation() {
           }
           apiEndpoint = (_options$stxerApi = options.stxerApi) != null ? _options$stxerApi : DEFAULT_STXER_API$1;
           _context.n = 1;
-          return fetch(apiEndpoint + "/devtools/v2/simulation:instant", {
+          return fetch(apiEndpoint + "/devtools/v2/simulations:instant", {
             method: 'POST',
             body: JSON.stringify(request),
             headers: {
@@ -1485,6 +1485,15 @@ function _getTip() {
   return _getTip.apply(this, arguments);
 }
 
+/**
+ * Type definitions for stxer-api V2 endpoints
+ * Hand-written types based on OpenAPI spec at https://api.stxer.xyz/openapi.json
+ */
+/** Convenience parser for `TransactionReceipt.events[i]`. */
+function parseSimulationEvent(raw) {
+  return JSON.parse(raw);
+}
+
 exports.DEFAULT_STXER_API = DEFAULT_STXER_API$1;
 exports.STXER_API_MAINNET = STXER_API_MAINNET;
 exports.STXER_API_TESTNET = STXER_API_TESTNET;
@@ -1497,6 +1506,7 @@ exports.getSimulationResult = getSimulationResult;
 exports.getTip = getTip;
 exports.instantSimulation = instantSimulation;
 exports.parseContract = parseContract;
+exports.parseSimulationEvent = parseSimulationEvent;
 exports.readMap = readMap;
 exports.readVariable = readVariable;
 exports.simulationBatchReads = simulationBatchReads;