@ondc/automation-mock-runner 1.3.45 → 1.3.48

package/README.md

@@ -1,48 +1,23 @@
 # @ondc/automation-mock-runner
 
-A robust TypeScript library designed for testing and validating ONDC (Open Network for Digital Commerce) transaction flows. This tool helps developers build reliable ONDC integrations by providing a comprehensive framework for generating, validating, and testing API payloads across different transaction scenarios.
+A TypeScript library for driving ONDC (Open Network for Digital Commerce) transaction flows end-to-end. It turns a **base64-encoded, sandboxed function config** into an executable multi-step flow, handling payload generation, response validation, session state, and (optionally) outbound HTTP — in either Node (worker_threads) or the browser (Web Workers).
 
-## What is this?
+## What it does
 
-When building applications that integrate with the ONDC network, you need to handle complex multi-step transaction flows where each API call depends on data from previous steps. This library provides a structured way to:
-
-- **Generate realistic test payloads** for ONDC APIs (search, select, init, confirm, etc.)
-- **Validate incoming requests** against your business logic with custom validation functions
-- **Check prerequisites** before proceeding with each transaction step
-- **Maintain session state** across the entire transaction flow
-- **Execute code securely** using sandboxed Worker Threads with base64-encoded functions
-
-The core concept is simple: define your transaction flow with base64-encoded functions, then let the runner handle payload generation, validation, and state management automatically in a secure environment.
+- **Generate payloads** for every step of a flow, with `context` (domain, version, ids, timestamps, bap/bpp) produced automatically.
+- **Validate responses** against custom per-step logic.
+- **Check prerequisites** before a step runs.
+- **Carry session state** across steps via JSONPath extraction of prior payloads.
+- **Sandbox every function** so user-authored JS runs with a whitelisted set of globals and per-function timeouts, and cannot touch the host filesystem, network, or module system — except where the installing service has explicitly allowlisted outbound URLs for `generate`.
 
 ## Key Features
 
-### 🔄 Transaction Flow Management
-
-- Define multi-step ONDC transaction flows with dependencies between steps
-- Automatic context generation with proper ONDC headers and metadata
-- Session data persistence across transaction steps
-
-### 🔒 Secure Code Execution
-
-- **Base64-encoded functions** for secure storage and transmission
-- **Sandboxed Worker Threads** with isolated VM contexts
-- **Complete function declarations** required (not just function bodies)
-- Built-in timeout protection and error isolation
-- Memory limits and resource monitoring
-
-### ✅ Schema Validation
-
-- Zod-based configuration validation with base64 string validation
-- Runtime type checking for all inputs and outputs
-- Detailed error reporting with line-by-line feedback
-- JSON Schema validation for user inputs
-
-### 🎯 ONDC-Specific Features
-
-- Built-in support for BAP (Buyer App) and BPP (Seller App) roles
-- Automatic message ID correlation for request-response pairs
-- Version-aware context generation (supports ONDC v1.x and v2.x)
-- Domain-specific helper utilities
+- 🔄 Multi-step flow management with automatic `context` building and request/response correlation via `responseFor`.
+- 🔒 Worker-thread (Node) / Web Worker (browser) sandbox. Whitelisted globals, per-function timeouts, workers recycled after 100 executions or 10 min.
+- 🌐 Opt-in outbound `fetch` from `generate` with a per-installer origin+path allowlist. Redirects blocked (`redirect: "error"`).
+- 📚 Built-in **default helper library** (`uuidv4`, `currentTimestamp`, `isoDurToSec`, `setCityFromInputs`, `createFormURL`, `generate6DigitId`, `getSubscriberUrl`, `generateConsentHandler`) prepended to every `generate`.
+- ✅ Zod-based config validation, JSON Schema for user inputs.
+- 🎯 ONDC-aware: version-aware context (v1.x flat `city`, v2.x nested `location.city.code`), BAP/BPP roles, form steps (`dynamic_form`, `html_form`, `HTML_FORM_MULTI`), dynamic action IDs (`GENERATED#n#action_id`).
 
 ## Installation
 
@@ -50,125 +25,89 @@ The core concept is simple: define your transaction flow with base64-encoded fun
 npm install @ondc/automation-mock-runner
 ```
 
-## Quick Start
+**Requires Node ≥ 18** (the sandbox uses native `fetch` and `AbortController`).
 
-Here's how to set up a basic ONDC search flow with base64-encoded functions:
+## Quick Start
 
 ```typescript
-import { MockRunner } from "@ondc/automation-mock-runner";
-import { MockPlaygroundConfigType } from "@ondc/automation-mock-runner";
-
-// Helper function to encode functions as base64
-function encodeFunction(functionCode: string): string {
-	return MockRunner.encodeBase64(functionCode);
-}
+import {
+	MockRunner,
+	createInitialMockConfig,
+} from "@ondc/automation-mock-runner";
+
+// 1. Boot the shared runner once at service startup.
+//    Only needed if any `generate` function calls fetch().
+MockRunner.initSharedRunner({
+	allowedFetchBaseUrls: ["https://dev-automation.ondc.org/finvu"],
+});
 
-// Define your transaction configuration
-const config: MockPlaygroundConfigType = {
-	meta: {
-		domain: "ONDC:RET11",
-		version: "1.2.0",
-		flowId: "search-select-init-confirm",
-	},
-	transaction_data: {
-		transaction_id: "550e8400-e29b-41d4-a716-446655440000",
-		latest_timestamp: new Date().toISOString(),
-		bap_id: "buyer-app.example.com",
-		bap_uri: "https://buyer-app.example.com",
-		bpp_id: "seller-app.example.com",
-		bpp_uri: "https://seller-app.example.com",
-	},
-	steps: [
-		{
-			api: "search",
-			action_id: "search_001",
-			owner: "BAP",
-			responseFor: null,
-			unsolicited: false,
-			description: "Search for products in electronics category",
-			mock: {
-				generate: encodeFunction(`
-          async function generate(defaultPayload, sessionData) {
-            // Add search intent to the payload
-            defaultPayload.message = {
-              intent: {
-                category: { descriptor: { name: "Electronics" } },
-                location: { country: { code: "IND" }, city: { code: "std:080" } }
-              }
-            };
-            return defaultPayload;
-          }
-        `),
-				validate: encodeFunction(`
-          function validate(targetPayload, sessionData) {
-            if (!targetPayload.message?.catalog?.providers?.length) {
-              return { valid: false, code: 400, description: "No providers found" };
-            }
-            return { valid: true, code: 200, description: "Valid catalog response" };
-          }
-        `),
-				requirements: encodeFunction(`
-          function meetsRequirements(sessionData) {
-            return { valid: true, code: 200, description: "Ready to search" };
-          }
-        `),
-				defaultPayload: { context: {}, message: {} },
-				saveData: {
-					providers: "$.message.catalog.providers",
-				},
-				inputs: {
-					id: "search_inputs",
-					jsonSchema: {
-						type: "object",
-						properties: {
-							category: { type: "string", default: "Electronics" },
-						},
+// 2. Scaffold a config (auto-fills `helperLib` with DEFAULT_HELPER_LIB).
+const config = createInitialMockConfig("ONDC:RET11", "2.0.0", "search-flow");
+
+// 3. Add a step. Every helper (uuidv4, currentTimestamp, setCityFromInputs, …)
+//    is already in scope inside `generate`.
+config.steps.push({
+	api: "search",
+	action_id: "search_0",
+	owner: "BAP",
+	responseFor: null,
+	unsolicited: false,
+	description: "Search for electronics",
+	mock: {
+		generate: MockRunner.encodeBase64(`
+			async function generate(defaultPayload, sessionData) {
+				setCityFromInputs(defaultPayload, sessionData.user_inputs);
+				defaultPayload.message = {
+					intent: {
+						category: { descriptor: { name: "Electronics" } },
 					},
-				},
+				};
+				return defaultPayload;
+			}
+		`),
+		validate: MockRunner.encodeBase64(`
+			function validate(targetPayload, sessionData) {
+				if (!targetPayload.message?.catalog?.providers?.length) {
+					return { valid: false, code: 400, description: "No providers" };
+				}
+				return { valid: true, code: 200, description: "ok" };
+			}
+		`),
+		requirements: MockRunner.encodeBase64(`
+			function meetsRequirements(sessionData) {
+				return { valid: true, code: 200, description: "ready" };
+			}
+		`),
+		defaultPayload: { context: {}, message: {} },
+		saveData: { providers: "$.message.catalog.providers" },
+		inputs: {
+			id: "search_inputs",
+			jsonSchema: {
+				type: "object",
+				properties: { city_code: { type: "string" } },
+				required: ["city_code"],
 			},
 		},
-	],
-	transaction_history: [],
-	validationLib: encodeFunction(`
-    // Shared validation utilities
-    function validateONDCContext(context) {
-      return context && context.domain && context.action && context.message_id;
-    }
-  `),
-	helperLib: encodeFunction(`
-    // Shared helper functions
-    function generateMessageId() {
-      return crypto.randomUUID();
-    }
-  `),
-};
-
-// Initialize the runner
-const runner = new MockRunner(config);
-
-// Generate a search payload
-const searchResult = await runner.runGeneratePayload("search_001", {
-	category: "Electronics",
+	},
 });
-console.log("Generated search payload:", searchResult.result);
 
-// Validate a response
-const validationResult = await runner.runValidatePayload(
-	"search_001",
-	responsePayload,
-);
-console.log("Validation passed:", validationResult.success);
+// 4. Run.
+const runner = new MockRunner(config);
+const out = await runner.runGeneratePayload("search_0", {
+	city_code: "std:080",
+});
+console.log(out.result);
 ```
 
 ## Configuration Structure
 
-### Transaction Metadata
+### Meta
 
 ```typescript
 meta: {
-  domain: string,     // ONDC domain (retail, mobility, etc.)
-  version: string,    // ONDC version (1.2.0, 2.0.0, etc.)
-  flowId: string      // Unique identifier for this flow
+	domain: string; // e.g. "ONDC:RET11"
+	version: string; // e.g. "1.2.0" or "2.0.0" — drives context shape
+	flowId: string;
 }
 ```
 
@@ -176,360 +115,296 @@ meta: {
 
 ```typescript
 transaction_data: {
-  transaction_id: string,      // UUID for this transaction
-  latest_timestamp: string,    // ISO timestamp
-  bap_id?: string,            // Buyer app ID
-  bap_uri?: string,           // Buyer app URI
-  bpp_id?: string,            // Seller app ID
-  bpp_uri?: string            // Seller app URI
+	transaction_id: string;
+	latest_timestamp: string;
+	bap_id?: string;
+	bap_uri?: string;
+	bpp_id?: string;
+	bpp_uri?: string;
 }
 ```
 
-### Action Steps
-
-Each step represents one API call in your transaction flow:
+### Action Step
 
 ```typescript
 {
-  api: "search" | "select" | "init" | "confirm" | "on_search" | "on_select" | ...,
-  action_id: string,          // Unique ID for this step
-  owner: "BAP" | "BPP",      // Who initiates this call
-  responseFor: string | null, // If this responds to another action
-  unsolicited: boolean,       // Whether this is an unsolicited call
-  description: string,        // Human-readable description
-  mock: {
-    generate: string,         // Base64-encoded complete function for payload generation
-    validate: string,         // Base64-encoded complete function for response validation
-    requirements: string,     // Base64-encoded complete function for prerequisite checks
-    defaultPayload: object,   // Base payload structure
-    saveData: object,         // JSONPath expressions to save data
-    inputs: object           // Input schema for user data
-  }
+	api: "search" | "select" | "init" | "confirm"
+		| "on_search" | "on_select" | /* … */
+		| "dynamic_form" | "html_form" | "HTML_FORM_MULTI",
+	action_id: string,          // unique within flow
+	owner: "BAP" | "BPP",
+	responseFor: string | null, // pair this step with a request action_id
+	unsolicited: boolean,
+	description: string,
+	repeatCount?: number,
+	force_proceed?: boolean,    // skip the "waiting for input" gate; see Form Steps
+	mock: {
+		generate: string,        // base64 function
+		validate: string,        // base64 function
+		requirements: string,    // base64 function
+		defaultPayload: object,
+		saveData: Record<string, string>,  // JSONPath map; supports APPEND# / EVAL# prefixes
+		inputs: object | {},
+		formHtml?: string,       // base64 HTML for form steps
+	},
 }
 ```
 
-## 🔑 Base64 Function Requirements
-
-**IMPORTANT**: All mock functions must be:
+## Base64 Function Requirements
 
-1. **Complete function declarations** with proper function names:
-   - `generate` functions: `async function generate(defaultPayload, sessionData) { ... }`
-   - `validate` functions: `function validate(targetPayload, sessionData) { ... }`
-   - `requirements` functions: `function meetsRequirements(sessionData) { ... }`
+All three user functions must be **complete declarations**:
 
-2. **Base64 encoded** using `MockRunner.encodeBase64()` utility
+```js
+async function generate(defaultPayload, sessionData) {
+	/* … */ return defaultPayload;
+}
+function validate(targetPayload, sessionData) {
+	/* … */ return { valid, code, description };
+}
+function meetsRequirements(sessionData) {
+	/* … */ return { valid, code, description };
+}
+```
 
-3. **Properly formatted** with return statements and error handling
+Encode with `MockRunner.encodeBase64(src)`. The runner decodes, prepends `DEFAULT_HELPER_LIB` (for `generate`), and executes inside the sandbox.
 
-### Function Signatures
+## API Reference
 
-Each function type has a specific signature that must be followed:
+### `MockRunner.initSharedRunner(options?)`
 
-#### Generate Functions
+Static. Configure the process-wide shared runner at boot. Replaces any existing runner (terminates the old one). Call **once before** constructing any `MockRunner`.
 
 ```typescript
-async function generate(defaultPayload: any, sessionData: any): Promise<any> {
-	// Parameters:
-	// - defaultPayload: Base payload with context already populated
-	// - sessionData: Contains user_inputs and data from previous steps
-
-	// Must return the complete payload to be sent
-	return defaultPayload;
-}
+MockRunner.initSharedRunner({
+	allowedFetchBaseUrls: [
+		"https://aa.example.com/finvu-aa",
+		"https://api.example.com/v1",
+	],
+});
 ```
 
-#### Validate Functions
+Empty / omitted `allowedFetchBaseUrls` means `fetch` is not injected into the sandbox at all.
+
+### `new MockRunner(config, skipValidation?)`
+
+Validates the config (Zod) on construction unless `skipValidation: true`.
+
+### `runGeneratePayload(actionId, inputs?, extraSessionData?)`
 
 ```typescript
-function validate(targetPayload: any, sessionData: any): ValidationResult {
-	// Parameters:
-	// - targetPayload: The incoming payload to validate
-	// - sessionData: Data from previous steps
-
-	// Must return validation result object
-	return {
-		valid: true,
-		code: 200,
-		description: "Validation passed",
-	};
-}
+await runner.runGeneratePayload(
+	"search_0",
+	{ city_code: "std:080" }, // → sessionData.user_inputs
+	{ finvuUrl: "https://aa.example.com" }, // shallow-merged into sessionData
+);
 ```
 
-#### Requirements Functions
+### `runValidatePayload(actionId, targetPayload, extraSessionData?)`
 
 ```typescript
-function meetsRequirements(sessionData: any): RequirementResult {
-	// Parameters:
-	// - sessionData: Data from previous steps
-
-	// Must return requirement check result
-	return {
-		valid: true,
-		code: 200,
-		description: "Requirements met",
-	};
-}
+await runner.runValidatePayload("on_search_0", incomingPayload, {
+	finvuUrl: "https://aa.example.com",
+});
 ```
 
-### Example Function Creation:
+### `runMeetRequirements(actionId)`
 
 ```typescript
-// Create a complete function
-const generateFunction = `
-  async function generate(defaultPayload, sessionData) {
-    // Your logic here
-    defaultPayload.message = { 
-      intent: { category: { descriptor: { name: "Electronics" } } }
-    };
-    return defaultPayload;
-  }
-`;
+await runner.runMeetRequirements("select_0");
+```
 
-// Encode it as base64
-const encodedFunction = MockRunner.encodeBase64(generateFunction);
+### With-session variants
 
-// Use in configuration
-const step = {
-	// ...other properties...
-	mock: {
-		generate: encodedFunction,
-		// ...other mock properties...
-	},
-};
-```
+Skip the history-based session build and use a caller-supplied object:
 
-## Advanced Usage
+- `runGeneratePayloadWithSession(actionId, sessionData)`
+- `runValidatePayloadWithSession(actionId, targetPayload, sessionData)`
+- `runMeetRequirementsWithSession(actionId, sessionData)`
 
-### Chaining Transaction Steps
+### `getDefaultStep(api, actionId, formType?)`
 
-```typescript
-const steps = [
-	{
-		api: "search",
-		action_id: "search_001",
-		// ... search configuration
-		mock: {
-			saveData: {
-				selectedProvider: "$.message.catalog.providers[0]",
-			},
-			// ...
-		},
-	},
-	{
-		api: "select",
-		action_id: "select_001",
-		// ... select configuration
-		mock: {
-			generate: `
-        // Use data from previous search step
-        const provider = sessionData.selectedProvider;
-        defaultPayload.message = {
-          order: {
-            provider: { id: provider.id },
-            items: [{ id: provider.items[0].id, quantity: { count: 1 } }]
-          }
-        };
-        return defaultPayload;
-      `,
-			// ...
-		},
-	},
-];
-```
+Returns a scaffolded step with template functions already base64-encoded. Pass `formType: "dynamic_form" | "html_form"` for form scaffolds.
 
-### Custom Validation Logic
+### `validateConfig()`
 
-```typescript
-// Create complete validation function
-const validateFunction = `
-  function validate(targetPayload, sessionData) {
-    // Check if order total matches expected amount
-    const expectedTotal = sessionData.calculatedTotal;
-    const actualTotal = targetPayload.message.order.quote.total;
-    
-    if (Math.abs(expectedTotal - actualTotal) > 0.01) {
-      return {
-        valid: false,
-        code: 400, 
-        description: \`Total mismatch: expected \${expectedTotal}, got \${actualTotal}\`
-      };
-    }
-    
-    return { valid: true, code: 200, description: "Order total validated" };
-  }
-`;
+Re-validates the stored config; returns `{ success, errors? }`.
 
-// Encode for use in configuration
-const encodedValidateFunction = MockRunner.encodeBase64(validateFunction);
-```
+### Static utilities
+
+- `MockRunner.encodeBase64(src)` / `decodeBase64(b64)` — work in both Node and browser (use `TextEncoder`/`TextDecoder`, not `Buffer`).
+
+## Default Helpers
+
+Every `generate` call is prefixed with `DEFAULT_HELPER_LIB` — these are always in scope:
+
+| Helper                                                 | Purpose                                                                         |
+| ------------------------------------------------------ | ------------------------------------------------------------------------------- |
+| `uuidv4()`                                             | RFC 4122 v4 UUID.                                                               |
+| `generate6DigitId()`                                   | 6-digit numeric string in `[100000, 999999]`.                                   |
+| `currentTimestamp()`                                   | ISO-8601 UTC timestamp.                                                         |
+| `isoDurToSec(duration)`                                | ISO 8601 duration → seconds (0 on unparseable input).                           |
+| `setCityFromInputs(payload, inputs)`                   | Writes `inputs.city_code` into `payload.context` (v1 flat / v2 nested).         |
+| `createFormURL(domain, formId, sessionData)`           | Build a `/forms/<domain>/<formId>/?...` submission URL from session data.       |
+| `getSubscriberUrl(sessionData, type)`                  | `"bpp"` → `sessionData.bppUri`; anything else → `bapUri`.                       |
+| `generateConsentHandler(sessionData, { custId, ... })` | POSTs to Finvu AA; 10s `AbortController` timeout. Needs `finvuUrl` + allowlist. |
+
+Source: `src/lib/helpers/default-helpers.js`. Edit that file and run `npm run helpers:gen` to refresh the shipped bundle (also regenerated automatically by `npm run build` and `npm test`).
+
+Helpers that need request-scope data (`getSubscriberUrl`, `createFormURL`, `generateConsentHandler`) take `sessionData` as an **explicit first parameter**. Free-variable references do not resolve inside the sandbox — helpers run at script scope, `sessionData` is only a parameter of `generate()`.
 
-### User Input Handling
+## 3rd-party HTTP from `generate`
+
+Outbound HTTP is **opt-in and scoped**:
+
+1. Only `generate` gets `fetch` (validate / meetsRequirements / getSave stay pure).
+2. The installing service provides the allowlist at boot:
+   ```typescript
+   MockRunner.initSharedRunner({
+   	allowedFetchBaseUrls: ["https://finvu.example.com/aa"],
+   });
+   ```
+3. Matching rule: request `origin` must equal an entry's origin **and** the request path must be a strict segment-prefix of the entry's path. `/v1` matches `/v1` and `/v1/foo` but **not** `/v10/foo`.
+4. Redirects are blocked (`redirect: "error"`) — call final URLs, don't rely on 3xx hops.
+5. `AbortController` + `AbortSignal` are in the sandbox; use them for per-request timeouts.
+
+### Worked example — Finvu consent via `generateConsentHandler`
 
 ```typescript
-// Create function that uses user inputs
-const generateWithInputs = `
-  async function generate(defaultPayload, sessionData) {
-    // Access user inputs
-    const { email, deliveryAddress } = sessionData.user_inputs;
-    
-    defaultPayload.message.order.billing = {
-      email: email,
-      address: deliveryAddress
-    };
-    
-    return defaultPayload;
-  }
+// boot
+MockRunner.initSharedRunner({
+	allowedFetchBaseUrls: ["https://dev-automation.ondc.org/finvu"],
+});
+
+// step's generate (base64-encoded)
+const src = `
+	async function generate(defaultPayload, sessionData) {
+		const handle = await generateConsentHandler(sessionData, { custId: "1234" });
+		defaultPayload.message.consentHandle = handle;
+		return defaultPayload;
+	}
 `;
 
-const stepWithInputs = {
-	// ... other config
-	mock: {
-		generate: MockRunner.encodeBase64(generateWithInputs),
-		inputs: {
-			id: "user_details",
-			jsonSchema: {
-				type: "object",
-				properties: {
-					email: { type: "string", format: "email" },
-					deliveryAddress: { type: "string", minLength: 10 },
-				},
-				required: ["email", "deliveryAddress"],
-			},
-		},
-	},
-};
+// caller passes finvuUrl through extraSessionData
+await runner.runGeneratePayload("consent_0", inputs, {
+	finvuUrl: "https://dev-automation.ondc.org/finvu",
+});
 ```
 
-## API Reference
+## Sandbox globals & limits
 
-### MockRunner
+**Always available:** `Array, Boolean, Date, Error, JSON, Math, Number, Object, Promise, RegExp, String, Symbol, Map, Set, WeakMap, WeakSet, parseInt, parseFloat, isNaN, isFinite, encodeURI(Component), decodeURI(Component), setTimeout, clearTimeout, AbortController, AbortSignal, console.{log,error,warn,info}`.
 
-#### Constructor
+**Added for `generate` only** (and only when an allowlist is configured): `fetch, URL, URLSearchParams, Headers, Request, Response`.
 
-```typescript
-new MockRunner(config: MockPlaygroundConfigType)
-```
+**Explicitly denied:** `require, process, global, globalThis, Buffer, __dirname, __filename, module, exports, eval, Function`.
+
+**Timeouts** (from `src/lib/constants/function-registry.ts`):
+
+| Function kind       | Timeout |
+| ------------------- | ------- |
+| `generate`          | 45 s    |
+| `validate`          | 5 s     |
+| `meetsRequirements` | 3 s     |
+| `getSave`           | 3 s     |
+
+`setTimeout` inside the sandbox is clamped to 1–45000 ms.
+
+## Dynamic action IDs
 
-#### Methods
+Any `actionId` containing `#` is resolved by taking the last `#`-separated segment. So `"GENERATED#1#search_0"` and `"GENERATED#42#search_0"` both resolve to the step with `action_id: "search_0"`. Applies to all `run*` methods — useful when the same step repeats inside a flow.
 
-**`validateConfig()`**
-Validates the entire configuration against the schema.
+## Session data extraction
+
+Each step declares a `saveData` map of JSONPath expressions applied to the prior response payload. The compiled values land on `sessionData` for subsequent steps.
 
 ```typescript
-const validation = runner.validateConfig();
-if (!validation.success) {
-	console.log("Config errors:", validation.errors);
+saveData: {
+	providerId:          "$.message.catalog.providers[0].id",
+	"APPEND#providerIds": "$.message.catalog.providers[*].id",  // concat into array
+	customValue:         "EVAL#<base64 of extractor>",           // custom extractor
 }
 ```
 
-**`runGeneratePayload(actionId: string, inputs: any)`**
-Generates a payload for the specified action step.
+- `APPEND#key` — concatenates the JSONPath result into an existing array under `key` instead of overwriting.
+- `EVAL#<base64>` — runs a sandboxed `getSave(payload)` function and stores its return value.
+- Form steps (`dynamic_form`, `html_form`) auto-save under `sessionData.formData[action_id]` and also set `sessionData[action_id]` to the submission ID.
 
-```typescript
-const result = await runner.runGeneratePayload("search_001", {
-	category: "books",
-});
-```
+## Form steps
 
-**`runValidatePayload(actionId: string, targetPayload: any)`**
-Validates an incoming payload against the specified action step.
+Supported `api` values for forms: `dynamic_form`, `html_form`, `HTML_FORM_MULTI`, `FORM`.
 
-```typescript
-const result = await runner.runValidatePayload(
-	"on_search_001",
-	responsePayload,
-);
-```
+`force_proceed: true` on a step means "don't wait for user input". `convertToFlowConfig` sets this automatically when the previous step is a form step and the current step has no inputs.
 
-**`runMeetRequirements(actionId: string, targetPayload: any)`**
-Checks if prerequisites are met before proceeding with an action.
+## Config builders
 
-```typescript
-const result = await runner.runMeetRequirements("select_001", {});
-```
+From `@ondc/automation-mock-runner` (via `configHelper.ts`):
 
-**`getDefaultStep(api: string, actionId: string)`**
-Creates a new step configuration with sensible defaults and base64-encoded template functions.
+- `createInitialMockConfig(domain, version, flowId)` — scaffold with `DEFAULT_HELPER_LIB` pre-installed as `helperLib`.
+- `generatePlaygroundConfigFromFlowConfig(payloads, flowConfig)` — reverse: seed a playground config from real ONDC traffic.
+- `generatePlaygroundConfigFromFlowConfigWithMeta(payloads, flowConfig, domain, version)` — same, with explicit meta (useful when payloads are empty).
+- `convertToFlowConfig(config)` — export a playground config to a Flow sequence.
+- `createOptimizedMockConfig(config)` — Terser-minify each step's `generate` / `validate` / `requirements`.
+- `validateConfigForDeployment(config)` — stricter pre-publish check (throws on problems).
 
-```typescript
-const newStep = runner.getDefaultStep("search", "search_002");
-// Returns a step with properly encoded template functions
-```
+## Error handling
 
-**`MockRunner.encodeBase64(functionString: string)`**
-Static utility to encode functions as base64.
+Every `run*` method returns an `ExecutionResult`:
 
 ```typescript
-const encodedFunction = MockRunner.encodeBase64(`
-  async function generate(defaultPayload, sessionData) {
-    // Your function logic here
-    return defaultPayload;
-  }
-`);
+const res = await runner.runGeneratePayload("search_0");
+if (!res.success) {
+	console.log(res.error.name, res.error.message);
+	console.log(res.logs); // captured console output
+	console.log(res.executionTime, "ms");
+}
 ```
 
-**`MockRunner.decodeBase64(encodedString: string)`**
-Static utility to decode base64-encoded functions (used internally).
+Common error names: `ActionNotFoundError`, `SessionDataError`, `ConfigurationError`, `PayloadGenerationError`, `PayloadValidationError`, `MeetRequirementsError`.
 
-```typescript
-const decodedFunction = MockRunner.decodeBase64(encodedFunction);
-```
+## FAQ / common gotchas
 
-## Error Handling
+**`DataCloneError: #<Promise> could not be cloned`** — your `generate` returned a payload containing an un-awaited Promise. Make `generate` `async` and `await` any async helper (including `generateConsentHandler`) before returning. Nested Promises inside the payload are not auto-flattened.
 
-The library provides detailed error information for debugging:
+**`fetch blocked: <url> is not in the configured allowlist`** — add the origin+path to `MockRunner.initSharedRunner({ allowedFetchBaseUrls: [...] })`.
 
-```typescript
-const result = await runner.runGeneratePayload("invalid_step", {});
+**`fetch is not defined`** — you're calling it from `validate`, `meetsRequirements`, or `getSave`. Only `generate` gets `fetch`.
 
-if (!result.success) {
-	console.log("Error:", result.error.message);
-	console.log("Logs:", result.logs);
-	console.log("Execution time:", result.executionTime);
-}
-```
+**Helper references `sessionData` but throws `ReferenceError`** — take `sessionData` as an explicit first parameter. Helpers don't share scope with `generate`.
 
-Common error types:
+**Edited `default-helpers.js` but the bundle didn't change** — run `npm run helpers:gen` (or `npm test` / `npm run build` — both regen automatically).
 
-- **ValidationError**: Configuration or input validation failed
-- **PayloadGenerationError**: Error in payload generation code
-- **PayloadValidationError**: Error in validation code
-- **MeetRequirementsError**: Error in requirements check code
-- **TimeoutError**: Code execution exceeded timeout limit
+**`validationLib` is not injected** — the field exists in the schema but is not currently prepended to any function at execution time. Treat as reserved.
 
-## Testing
+**Execution timed out** — see the timeout table above. `generate` has the largest window (45 s) specifically for delayed-response mocking.
 
-The library includes comprehensive tests. Run them with:
+## Testing
 
 ```bash
-npm test           # Run all tests
-npm run test:watch # Run tests in watch mode
-npm run test:coverage # Generate coverage report
+npm test              # full suite (regens helpers via pretest)
+npm run test:watch
+npm run test:coverage
+npm run test:browser-mock   # BrowserRunner / CrossEnvironment tests only
 ```
 
-## Security Considerations
+## Security notes
 
-- **Base64 encoding** prevents code injection through configuration
-- **Complete function declarations** required - no arbitrary code execution
-- **Sandboxed Worker Threads** with isolated VM contexts
-- **Restricted global access** - dangerous functions like `eval`, `require`, and file system access are blocked
-- **Execution timeouts** prevent infinite loops and hanging processes
-- **Memory limits** prevent resource exhaustion
-- **Input validation** using Zod schemas for all configuration data
+- Base64 encoding prevents casual injection via config files.
+- The sandbox blocks `eval`, `Function`, `require`, `process`, `Buffer`, filesystem, and (by default) network.
+- Network access is per-installer opt-in and path-scoped.
+- Redirects are refused to prevent allowlist bypass.
+- Workers are recycled after 100 executions / 10 min to limit memory creep in the V8 isolate.
 
 ## Contributing
 
-This library is built for the ONDC ecosystem. When contributing:
-
-1. Ensure all tests pass: `npm test`
-2. Follow the existing code style: `npm run lint`
-3. Add tests for new features
-4. Update documentation for API changes
+1. `npm test` — all tests green.
+2. `npm run lint` / `npm run format` — code style.
+3. `npm run type-check` — no TypeScript errors.
+4. Add tests for new features; update README when public API changes.
 
 ## License
 
-ISC License - see LICENSE file for details.
+ISC — see LICENSE.
 
 ## Support
 
-For ONDC-specific questions, refer to the [ONDC documentation](https://ondc.org/). For issues with this library, please file an issue on the repository.
+ONDC-specific questions: [ondc.org](https://ondc.org/). Library issues: file on the repository.

package/dist/lib/MockRunner.d.ts

@@ -35,6 +35,7 @@ export declare class MockRunner {
             bap_uri?: string | undefined;
             bpp_id?: string | undefined;
             bpp_uri?: string | undefined;
+            external_session_data?: Record<string, any> | undefined;
         };
         steps: {
             api: string;

package/dist/lib/configHelper.js

@@ -29,6 +29,10 @@ function createInitialMockConfig(domain, version, flowId) {
             bap_uri: "https://bap.example.com",
             bpp_id: "bpp.example.com",
             bpp_uri: "https://bpp.example.com",
+            external_session_data: {
+                finvuUrl: "https://dev-automation.ondc.org/finvu",
+                mockBaseUrl: "https://dev-automation.ondc.org/mock",
+            },
         },
         steps: [],
         transaction_history: [],

package/dist/lib/types/mock-config.d.ts

@@ -19,6 +19,7 @@ export declare const TransactionDataSchema: z.ZodObject<{
     bap_uri: z.ZodOptional<z.ZodString>;
     bpp_id: z.ZodOptional<z.ZodString>;
     bpp_uri: z.ZodOptional<z.ZodString>;
+    external_session_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, z.core.$strip>;
 export declare const MockConfigSchema: z.ZodObject<{
     generate: z.ZodBase64;
@@ -92,6 +93,7 @@ export declare const MockPlaygroundConfigSchema: z.ZodObject<{
         bap_uri: z.ZodOptional<z.ZodString>;
         bpp_id: z.ZodOptional<z.ZodString>;
         bpp_uri: z.ZodOptional<z.ZodString>;
+        external_session_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
     }, z.core.$strip>;
     steps: z.ZodArray<z.ZodObject<{
         api: z.ZodString;

package/dist/lib/types/mock-config.js

@@ -20,6 +20,7 @@ exports.TransactionDataSchema = zod_1.z.object({
     bap_uri: zod_1.z.string().min(1, "BAP URI is required").optional(),
     bpp_id: zod_1.z.string().min(1, "BPP ID is required").optional(),
     bpp_uri: zod_1.z.string().min(1, "BPP URI is required").optional(),
+    external_session_data: zod_1.z.record(zod_1.z.string(), zod_1.z.any()).optional(),
 });
 exports.MockConfigSchema = zod_1.z.object({
     generate: zod_1.z.base64(),

package/dist/lib/validators/code-validator.d.ts

@@ -14,6 +14,12 @@ export declare class CodeValidator {
     /**
      * Validate that return statements match expected structure
      */
+    /**
+     * Collect ReturnStatement arguments belonging only to the outer (top-level)
+     * function. Nested function/arrow bodies are skipped — their returns are
+     * not the function's contract and would otherwise produce false positives.
+     */
+    private static collectTopLevelReturns;
     private static validateReturnStructure;
     /**
      * Security analysis - checks for forbidden functions and properties

package/dist/lib/validators/code-validator.js

@@ -171,16 +171,35 @@ class CodeValidator {
     /**
      * Validate that return statements match expected structure
      */
-    static validateReturnStructure(ast, expectedProperties) {
-        const warnings = [];
-        const foundReturns = [];
-        walk.simple(ast, {
+    /**
+     * Collect ReturnStatement arguments belonging only to the outer (top-level)
+     * function. Nested function/arrow bodies are skipped — their returns are
+     * not the function's contract and would otherwise produce false positives.
+     */
+    static collectTopLevelReturns(ast) {
+        const returns = [];
+        let depth = 0;
+        const enterFn = (node, _st, c) => {
+            if (depth === 0) {
+                depth++;
+                c(node.body, null);
+                depth--;
+            }
+        };
+        walk.recursive(ast, null, {
+            FunctionDeclaration: enterFn,
+            FunctionExpression: enterFn,
+            ArrowFunctionExpression: enterFn,
             ReturnStatement(node) {
-                if (node.argument) {
-                    foundReturns.push(node.argument);
-                }
+                if (node.argument)
+                    returns.push(node.argument);
             },
         });
+        return returns;
+    }
+    static validateReturnStructure(ast, expectedProperties) {
+        const warnings = [];
+        const foundReturns = this.collectTopLevelReturns(ast);
         // Check if we have return statements
         if (foundReturns.length === 0) {
             warnings.push(`Function should return an object with properties: ${Object.keys(expectedProperties).join(", ")}`);
@@ -295,12 +314,7 @@ class CodeValidator {
      */
     static checkBestPractices(ast, schema) {
         const warnings = [];
-        let hasReturn = false;
-        walk.simple(ast, {
-            ReturnStatement() {
-                hasReturn = true;
-            },
-        });
+        const hasReturn = this.collectTopLevelReturns(ast).length > 0;
         if (!hasReturn) {
             warnings.push(`Function should return a value (expected: ${schema.returnType.description})`);
         }

package/dist/test/CodeValidator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/CodeValidator.test.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const code_validator_1 = require("../lib/validators/code-validator");
+const function_registry_1 = require("../lib/constants/function-registry");
+const validateSchema = (0, function_registry_1.getFunctionSchema)("validate");
+describe("CodeValidator.validate — return structure", () => {
+    it("accepts an outer return with the full expected shape", () => {
+        const code = `
+			function validate(targetPayload, sessionData) {
+				return { valid: false, code: 200, description: "Valid request" };
+			}
+		`;
+        const result = code_validator_1.CodeValidator.validate(code, validateSchema);
+        expect(result.isValid).toBe(true);
+        expect(result.errors).toEqual([]);
+    });
+    it("ignores nested arrow helper returns (regression: false positive on nested non-object returns)", () => {
+        const code = `
+			function validate(targetPayload, sessionData) {
+				const ok = (x) => { return x.length > 0; };
+				const items = (targetPayload.items || []).filter(i => { return i.id; });
+				return { valid: ok("hi"), code: 200, description: "Valid request" };
+			}
+		`;
+        const result = code_validator_1.CodeValidator.validate(code, validateSchema);
+        expect(result.isValid).toBe(true);
+        expect(result.errors).toEqual([]);
+    });
+    it("ignores nested function declaration returns", () => {
+        const code = `
+			function validate(targetPayload, sessionData) {
+				function getMsg(x) { return "msg: " + x; }
+				return { valid: false, code: 200, description: getMsg("ok") };
+			}
+		`;
+        const result = code_validator_1.CodeValidator.validate(code, validateSchema);
+        expect(result.isValid).toBe(true);
+        expect(result.errors).toEqual([]);
+    });
+    it("flags missing properties on the outer return", () => {
+        const code = `
+			function validate(targetPayload, sessionData) {
+				return { valid: true, code: 200 };
+			}
+		`;
+        const result = code_validator_1.CodeValidator.validate(code, validateSchema);
+        expect(result.isValid).toBe(false);
+        expect(result.errors.some((e) => e.includes("description"))).toBe(true);
+    });
+    it("flags an outer return that is not an object literal", () => {
+        const code = `
+			function validate(targetPayload, sessionData) {
+				return true;
+			}
+		`;
+        const result = code_validator_1.CodeValidator.validate(code, validateSchema);
+        expect(result.isValid).toBe(false);
+        expect(result.errors.some((e) => e.includes("Function should return an object literal"))).toBe(true);
+    });
+    it("warns when only a nested helper returns and the outer function has no return", () => {
+        const code = `
+			function validate(targetPayload, sessionData) {
+				function helper() { return 42; }
+				helper();
+			}
+		`;
+        const result = code_validator_1.CodeValidator.validate(code, validateSchema);
+        expect(result.warnings.some((w) => w.includes("should return a value"))).toBe(true);
+    });
+});

package/dist/test/helper-config.test.js

@@ -456,6 +456,10 @@ describe("configHelper", () => {
                 bap_uri: "https://bap.example.com",
                 bpp_id: "bpp.example.com",
                 bpp_uri: "https://bpp.example.com",
+                external_session_data: {
+                    finvuUrl: "https://dev-automation.ondc.org/finvu",
+                    mockBaseUrl: "https://dev-automation.ondc.org/mock",
+                },
             });
         });
         it("should initialize empty arrays and strings", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ondc/automation-mock-runner",
-	"version": "1.3.45",
+	"version": "1.3.48",
 	"description": "A TypeScript library for ONDC automation mock runner",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",