@softprobe/softprobe-js 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Softprobe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# Softprobe
+
+Topology-aware record & replay testing framework for Node.js via OpenTelemetry. Record real traffic (Postgres, Redis, HTTP) into NDJSON cassettes and replay it in tests without live dependencies.
+
+## Installation
+
+```bash
+npm install @softprobe/softprobe-js
+```
+
+## Global CLI (Recommended)
+
+Install once, then use `softprobe` directly:
+
+```bash
+npm install -g @softprobe/softprobe-js
+softprobe --help
+softprobe --version
+```
+
+Fallback (no global install):
+
+```bash
+npx @softprobe/softprobe-js --help
+```
+
+## Quick Start (Library + CLI)
+
+1. Install and add an instrumentation bootstrap that imports Softprobe first:
+
+```ts
+// instrumentation.ts
+import "@softprobe/softprobe-js/init";
+
+import { NodeSDK } from "@opentelemetry/sdk-node";
+import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
+```
+
+2. Start your service with that bootstrap:
+
+```bash
+node -r ./instrumentation.ts ./server.ts
+```
+
+3. Capture a real request as a cassette:
+
+```bash
+TRACE_ID=11111111111111111111111111111111
+curl -H "x-softprobe-mode: CAPTURE" \
+     -H "x-softprobe-trace-id: ${TRACE_ID}" \
+     http://localhost:3000/your-route
+```
+
+4. Replay in tests with `run({ mode, storage, traceId }, fn)`:
+
+```ts
+import { softprobe } from "@softprobe/softprobe-js";
+
+it("replays from cassette", async () => {
+  const storage = {
+    async loadTrace() {
+      // Load and return records for the trace bound to this cassette.
+      return [];
+    },
+    async saveRecord(_record) {
+      // Replay-only example: no-op for writes.
+    },
+  };
+
+  await softprobe.run(
+    { mode: "REPLAY", storage: storage, traceId: "prod-trace-345" },
+    async () => {
+      const res = await fetch("http://localhost:3000/users/1");
+      expect(res.status).toBe(200);
+    }
+  );
+});
+```
+
+5. Compare current behavior vs recorded behavior with CLI diff:
+
+```bash
+softprobe diff ./cassettes/11111111111111111111111111111111.ndjson http://localhost:3000
+```
+
+For a full walkthrough, see [examples/basic-app/README.md](examples/basic-app/README.md) and [examples/pricing-regression-demo/README.md](examples/pricing-regression-demo/README.md).
+
+## CLI — `softprobe diff`
+
+Replay the recorded inbound request against a running service and compare. The CLI sends the request with **coordination headers** so the service can run in replay mode for that request.
+
+### Usage
+
+```bash
+softprobe diff <cassette.ndjson> <targetUrl>
+```
+
+- **`cassette.ndjson`** — Path to the NDJSON cassette file (must contain an `inbound` record).
+- **`targetUrl`** — Base URL of the target service (e.g. `http://localhost:3000`).
+
+### How to generate the cassette
+
+Send requests to your app with **coordination headers** so it records that traffic into an NDJSON file. No environment variables are required.
+
+1. Run your app with Softprobe middleware (Express or Fastify) and `import "softprobe/init"` at startup. Configure **cassetteDirectory** in config so the server knows where to read/write cassette files. Per-trace files are always `{cassetteDirectory}/{traceId}.ndjson`. (Config may still contain `cassettePath` for backward compatibility; init derives the directory from it.)
+2. For each request you want to record, send these HTTP headers:
+   - **`x-softprobe-mode: CAPTURE`** — this request (and its outbound calls) will be recorded.
+   - **`x-softprobe-trace-id: <id>`** — trace id for this request; the cassette file will be `{cassetteDirectory}/{id}.ndjson`.
+3. The middleware uses these headers and writes the inbound request/response (and any outbound records for that trace) to `{cassetteDirectory}/{traceId}.ndjson`. The cassette will contain at least one `inbound` record.
+
+Example with curl (server must have cassetteDirectory configured, e.g. via config):
+
+```bash
+curl -H "x-softprobe-mode: CAPTURE" \
+     -H "x-softprobe-trace-id: my-trace-1" \
+     http://localhost:3000/your-route
+```
+
+Repeat for other routes or use the same path to append more records to the same cassette.
+
+### How to run the CLI
+
+**Global install (recommended):**
+
+```bash
+softprobe diff <cassette.ndjson> <targetUrl>
+```
+
+**No global install (fallback):**
+
+```bash
+npx @softprobe/softprobe-js diff <cassette.ndjson> <targetUrl>
+```
+
+**If you're in the repo** (no install, no build needed):
+
+```bash
+./bin/softprobe diff <cassette.ndjson> <targetUrl>
+```
+
+The `bin/softprobe` script uses the built CLI when present, otherwise runs from source.
+
+### What the CLI does
+
+1. Loads the cassette and finds the **inbound** HTTP record.
+2. Sends the same method and path to `<targetUrl>` with these headers:
+   - `x-softprobe-mode: REPLAY`
+   - `x-softprobe-trace-id: <traceId from record>`
+3. The target server must have **cassetteDirectory** set (e.g. via config) so it resolves the cassette as `{cassetteDirectory}/{traceId}.ndjson`. Compares the live response to the recording (the **diff reporter**). Writes **PASS** or **FAIL** to stderr; on failure, prints a colored diff of what differed. Writes the response body to stdout. Exit code 0 = pass, 1 = fail or error.
+
+Your service must use Softprobe middleware (Express or Fastify) so it reads these headers and runs that request in replay context. See [design.md](design.md) for the full coordination flow.
+
+### Example
+
+```bash
+# Start your app (with Softprobe middleware) on port 3000, then:
+softprobe diff ./softprobe-cassettes.ndjson http://localhost:3000
+# Fallback:
+npx @softprobe/softprobe-js diff ./softprobe-cassettes.ndjson http://localhost:3000
+# Or from repo: ./bin/softprobe diff ./softprobe-cassettes.ndjson http://localhost:3000
+```
+
+## Release
+
+This repository publishes to npm as `@softprobe/softprobe-js` via GitHub Actions workflow [`.github/workflows/release.yml`](.github/workflows/release.yml).
+
+Setup once:
+
+1. Configure npm Trusted Publishing for this package and this GitHub repository/workflow.
+2. Ensure npm package access is public for the scoped package.
+3. Keep workflow permissions with `id-token: write` (already set in release workflow).
+
+Reference:
+- npm trusted publishing docs: https://docs.npmjs.com/trusted-publishers/
+- npm classic token revocation announcement: https://github.blog/changelog/2025-12-09-npm-classic-tokens-revoked-session-based-auth-and-cli-token-management-now-available/
+
+Release flow:
+
+1. Merge changes to `main`.
+2. Create and push a version tag, for example `v2.0.1`.
+3. GitHub Action builds and publishes automatically.
+
+Manual validation flow:
+
+1. Run the `Release` workflow with `dry_run=true` to verify publish steps without publishing.
+
+No `NPM_TOKEN` repository secret is required for this workflow.
+
+## Package Layout
+
+- `src/core` contains shared framework-agnostic contracts and runtime helpers.
+- `src/instrumentations/<package>` contains package-specific hooks/patches (for example `express`, `fastify`, `redis`, `postgres`, `fetch`).
+- `src/instrumentations/common` contains shared protocol helpers used by multiple instrumentation packages.
+
+## More
+
+- **Example app:** `examples/basic-app` — capture, replay, and custom matcher.
+- **Example walkthrough:** [examples/basic-app/README.md](examples/basic-app/README.md)
+- **Design index:** [design.md](design.md) — architecture, cassette format, and coordination headers.
+- **Context design:** [design-context.md](design-context.md)
+- **Cassette design:** [design-cassette.md](design-cassette.md)
+- **Matcher design:** [design-matcher.md](design-matcher.md)

package/bin/softprobe

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Run the Softprobe CLI. Works from the repo without building (uses dist if present, else ts-node).
+# Usage: softprobe diff <cassette.ndjson> <targetUrl>
+# From repo: ./bin/softprobe diff ./cassette.ndjson http://localhost:3000
+# After npm install: npx softprobe diff ./cassette.ndjson http://localhost:3000
+
+set -e
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$REPO_ROOT"
+
+if [ -f dist/cli.js ]; then
+  exec node dist/cli.js "$@"
+else
+  exec npx ts-node --transpile-only src/cli.ts "$@"
+fi

package/dist/api/baggage.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Task 15.1.1: Inject softprobe-mode into OTel Baggage for downstream propagation.
+ * Design §15.2: when mode=REPLAY, inject so internal microservice calls are also mocked.
+ */
+import { context } from '@opentelemetry/api';
+/**
+ * Returns the current OTel context with `softprobe-mode: REPLAY` in baggage when
+ * SoftprobeContext.getMode() is REPLAY. Otherwise returns the active context unchanged.
+ * Middleware (Express/Fastify) should run the request in this context so
+ * outbound calls propagate the mode to downstream services.
+ */
+export declare function getContextWithReplayBaggage(): ReturnType<typeof context.active>;
+//# sourceMappingURL=baggage.d.ts.map

package/dist/api/baggage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baggage.d.ts","sourceRoot":"","sources":["../../src/api/baggage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,OAAO,EAGR,MAAM,oBAAoB,CAAC;AAO5B;;;;;GAKG;AACH,wBAAgB,2BAA2B,IAAI,UAAU,CAAC,OAAO,OAAO,CAAC,MAAM,CAAC,CAe/E"}

package/dist/api/baggage.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getContextWithReplayBaggage = getContextWithReplayBaggage;
+/**
+ * Task 15.1.1: Inject softprobe-mode into OTel Baggage for downstream propagation.
+ * Design §15.2: when mode=REPLAY, inject so internal microservice calls are also mocked.
+ */
+const api_1 = require("@opentelemetry/api");
+const context_1 = require("../context");
+const SOFTPROBE_MODE_KEY = 'softprobe-mode';
+const REPLAY_VALUE = 'REPLAY';
+const METADATA_STR = 'softprobe';
+/**
+ * Returns the current OTel context with `softprobe-mode: REPLAY` in baggage when
+ * SoftprobeContext.getMode() is REPLAY. Otherwise returns the active context unchanged.
+ * Middleware (Express/Fastify) should run the request in this context so
+ * outbound calls propagate the mode to downstream services.
+ */
+function getContextWithReplayBaggage() {
+    const activeContext = api_1.context.active();
+    if (context_1.SoftprobeContext.getMode() !== REPLAY_VALUE) {
+        return activeContext;
+    }
+    const currentBaggage = api_1.propagation.getBaggage(activeContext);
+    const entry = {
+        value: REPLAY_VALUE,
+        metadata: (0, api_1.baggageEntryMetadataFromString)(METADATA_STR),
+    };
+    const newBaggage = (currentBaggage ?? api_1.propagation.createBaggage()).setEntry(SOFTPROBE_MODE_KEY, entry);
+    return api_1.propagation.setBaggage(activeContext, newBaggage);
+}
+//# sourceMappingURL=baggage.js.map

package/dist/api/baggage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baggage.js","sourceRoot":"","sources":["../../src/api/baggage.ts"],"names":[],"mappings":";;AAqBA,kEAeC;AApCD;;;GAGG;AACH,4CAI4B;AAC5B,wCAA8C;AAE9C,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAC5C,MAAM,YAAY,GAAG,QAAQ,CAAC;AAC9B,MAAM,YAAY,GAAG,WAAW,CAAC;AAEjC;;;;;GAKG;AACH,SAAgB,2BAA2B;IACzC,MAAM,aAAa,GAAG,aAAO,CAAC,MAAM,EAAE,CAAC;IACvC,IAAI,0BAAgB,CAAC,OAAO,EAAE,KAAK,YAAY,EAAE,CAAC;QAChD,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,MAAM,cAAc,GAAG,iBAAW,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG;QACZ,KAAK,EAAE,YAAY;QACnB,QAAQ,EAAE,IAAA,oCAA8B,EAAC,YAAY,CAAC;KACvD,CAAC;IACF,MAAM,UAAU,GAAG,CAAC,cAAc,IAAI,iBAAW,CAAC,aAAa,EAAE,CAAC,CAAC,QAAQ,CACzE,kBAAkB,EAClB,KAAK,CACN,CAAC;IACF,OAAO,iBAAW,CAAC,UAAU,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;AAC3D,CAAC"}

package/dist/api/compare.d.ts

@@ -0,0 +1,16 @@
+import type { SoftprobeCassetteRecord } from '../types/schema';
+export type CompareInboundInput = {
+    /** HTTP status code of the actual response. */
+    status: number;
+    /** Parsed response body (e.g. from res.json() or res.text()). */
+    body: unknown;
+    /** Optional response headers. Compared when SoftprobeContext.getStrictComparison() is set (Task 15.2.2). */
+    headers?: Record<string, string>;
+};
+/**
+ * Compares the actual response (status and body) to the given recorded inbound record.
+ * Deep equality is used for body. Used by softprobe.compareInbound() with getRecordedInboundResponse().
+ * @throws When recorded is missing, or when status or body does not match.
+ */
+export declare function compareInboundWithRecord(actual: CompareInboundInput, recorded: SoftprobeCassetteRecord | undefined): void;
+//# sourceMappingURL=compare.d.ts.map

package/dist/api/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../../src/api/compare.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D,MAAM,MAAM,mBAAmB,GAAG;IAChC,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,4GAA4G;IAC5G,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC,CAAC;AAiCF;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,EAAE,uBAAuB,GAAG,SAAS,GAC5C,IAAI,CA6BN"}

package/dist/api/compare.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareInboundWithRecord = compareInboundWithRecord;
+/**
+ * Task 15.2.1: Inbound comparison utility.
+ * Retrieves the recorded inbound record and performs deep equality check on status and body.
+ */
+const context_1 = require("../context");
+/**
+ * Recorded inbound may use responsePayload.status (Express) or responsePayload.statusCode (http-inbound).
+ */
+function getRecordedStatus(record) {
+    const payload = record.responsePayload;
+    return payload?.status ?? payload?.statusCode ?? record.statusCode;
+}
+function getRecordedBody(record) {
+    const payload = record.responsePayload;
+    return payload?.body;
+}
+function getRecordedHeaders(record) {
+    const payload = record.responsePayload;
+    return payload?.headers;
+}
+function isStrictComparison() {
+    return context_1.SoftprobeContext.getStrictComparison() === true;
+}
+/** Normalize header keys to lowercase for comparison. */
+function normalizeHeaders(h) {
+    const out = {};
+    for (const [k, v] of Object.entries(h)) {
+        out[k.toLowerCase()] = v;
+    }
+    return out;
+}
+/**
+ * Compares the actual response (status and body) to the given recorded inbound record.
+ * Deep equality is used for body. Used by softprobe.compareInbound() with getRecordedInboundResponse().
+ * @throws When recorded is missing, or when status or body does not match.
+ */
+function compareInboundWithRecord(actual, recorded) {
+    if (!recorded) {
+        throw new Error('compareInbound: no recorded inbound response for this trace');
+    }
+    const expectedStatus = getRecordedStatus(recorded);
+    const expectedBody = getRecordedBody(recorded);
+    if (expectedStatus !== undefined && actual.status !== expectedStatus) {
+        throw new Error(`compareInbound: status mismatch (actual ${actual.status}, expected ${expectedStatus})`);
+    }
+    if (!deepEqual(actual.body, expectedBody)) {
+        throw new Error('compareInbound: body mismatch (actual and recorded response bodies are not deep equal)');
+    }
+    if (isStrictComparison()) {
+        const expectedHeaders = getRecordedHeaders(recorded);
+        if (expectedHeaders !== undefined && Object.keys(expectedHeaders).length > 0) {
+            const actualHeaders = actual.headers ?? {};
+            const normExpected = normalizeHeaders(expectedHeaders);
+            const normActual = normalizeHeaders(actualHeaders);
+            if (!deepEqual(normActual, normExpected)) {
+                throw new Error('compareInbound: header mismatch (actual and recorded response headers are not equal in strict mode)');
+            }
+        }
+    }
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') {
+        return false;
+    }
+    const keysA = Object.keys(a).sort();
+    const keysB = Object.keys(b).sort();
+    if (keysA.length !== keysB.length || keysA.some((k, i) => k !== keysB[i])) {
+        return false;
+    }
+    return keysA.every((k) => deepEqual(a[k], b[k]));
+}
+//# sourceMappingURL=compare.js.map

package/dist/api/compare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.js","sourceRoot":"","sources":["../../src/api/compare.ts"],"names":[],"mappings":"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"}

package/dist/api.d.ts

@@ -0,0 +1,63 @@
+import type { SoftprobeCassetteRecord, SoftprobeRunOptions } from './types/schema';
+import type { SemanticMatcher } from './core/matcher/matcher';
+import { SoftprobeMatcher } from './core/matcher/softprobe-matcher';
+import { getContextWithReplayBaggage } from './api/baggage';
+import { type CompareInboundInput } from './api/compare';
+import { SoftprobeContext } from './context';
+/**
+ * Returns the current replay context for the active async scope from OTel context.
+ * Stored in OTel context by SoftprobeContext.withData/run.
+ */
+export declare function getContext(): ReturnType<typeof SoftprobeContext.active> | undefined;
+/**
+ * Returns the active matcher for the current replay context, if any.
+ * In REPLAY mode, returns global matcher when context has no matcher; includes baggage fallback.
+ */
+export declare function getActiveMatcher(): SemanticMatcher | SoftprobeMatcher | undefined;
+/**
+ * Returns the recorded inbound response for the current trace, if any.
+ * Set by runWithContext when loading a cassette that contains a record with type "inbound".
+ */
+export declare function getRecordedInboundResponse(): SoftprobeCassetteRecord | undefined;
+/**
+ * Task 15.2.1: Compares the actual response (status and body) to the recorded inbound for the current trace.
+ * Task 15.2.2: When SOFTPROBE_STRICT_COMPARISON is set, also compares headers.
+ * @throws When no recorded inbound exists, or when status, body, or (if strict) headers do not match.
+ */
+export declare function compareInbound(actual: CompareInboundInput): void;
+/**
+ * Returns recorded cassette records for the given traceId from the active context only.
+ * Records are context-scoped (matcher is created by SoftprobeContext.run(REPLAY)). Task 15.3.1.
+ */
+export declare function getRecordsForTrace(traceId: string): SoftprobeCassetteRecord[];
+/**
+ * Sets the global replay matcher. For test/cleanup only; the framework creates matchers in SoftprobeContext.run(REPLAY).
+ * getMatcher() returns only the context matcher, not this global.
+ */
+export declare function setGlobalReplayMatcher(matcher: SoftprobeMatcher | undefined): void;
+/**
+ * Primes the active matcher with records for the given traceId.
+ * Called by server middleware (Express/Fastify) after run(); the matcher was already seeded in run(), so this is a no-op when records are present.
+ */
+export declare function activateReplayForContext(traceId: string): void;
+/**
+ * No-op. Replay is context-scoped; only SoftprobeContext.run(REPLAY) creates and seeds the matcher.
+ * Use cassetteDirectory + traceId and middleware so each request gets its own context and matcher.
+ */
+export declare function ensureReplayLoadedForRequest(): Promise<void>;
+/** Runs callback inside a scoped Softprobe context using SoftprobeRunOptions. */
+export declare function run<T>(options: SoftprobeRunOptions, fn: () => T | Promise<T>): T | Promise<T>;
+export { getContextWithReplayBaggage } from './api/baggage';
+export declare const softprobe: {
+    getContext: typeof getContext;
+    getActiveMatcher: typeof getActiveMatcher;
+    getRecordedInboundResponse: typeof getRecordedInboundResponse;
+    compareInbound: typeof compareInbound;
+    getRecordsForTrace: typeof getRecordsForTrace;
+    setGlobalReplayMatcher: typeof setGlobalReplayMatcher;
+    activateReplayForContext: typeof activateReplayForContext;
+    ensureReplayLoadedForRequest: typeof ensureReplayLoadedForRequest;
+    run: typeof run;
+    getContextWithReplayBaggage: typeof getContextWithReplayBaggage;
+};
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAC5D,OAAO,EAA4B,KAAK,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEnF,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C;;;GAGG;AACH,wBAAgB,UAAU,IACtB,UAAU,CAAC,OAAO,gBAAgB,CAAC,MAAM,CAAC,GAC1C,SAAS,CAUZ;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,eAAe,GAAG,gBAAgB,GAAG,SAAS,CAEjF;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,uBAAuB,GAAG,SAAS,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAEhE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,uBAAuB,EAAE,CAE7E;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,GAAG,IAAI,CAElF;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAQ9D;AAED;;;GAGG;AACH,wBAAsB,4BAA4B,IAAI,OAAO,CAAC,IAAI,CAAC,CAAG;AAEtE,iFAAiF;AACjF,wBAAgB,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,mBAAmB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE7F;AAED,OAAO,EAAE,2BAA2B,EAAE,MAAM,eAAe,CAAC;AAE5D,eAAO,MAAM,SAAS;;;;;;;;;;;CAWrB,CAAC"}

package/dist/api.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.softprobe = exports.getContextWithReplayBaggage = void 0;
+exports.getContext = getContext;
+exports.getActiveMatcher = getActiveMatcher;
+exports.getRecordedInboundResponse = getRecordedInboundResponse;
+exports.compareInbound = compareInbound;
+exports.getRecordsForTrace = getRecordsForTrace;
+exports.setGlobalReplayMatcher = setGlobalReplayMatcher;
+exports.activateReplayForContext = activateReplayForContext;
+exports.ensureReplayLoadedForRequest = ensureReplayLoadedForRequest;
+exports.run = run;
+const baggage_1 = require("./api/baggage");
+const compare_1 = require("./api/compare");
+const store_accessor_1 = require("./core/matcher/store-accessor");
+const context_1 = require("./context");
+/**
+ * Returns the current replay context for the active async scope from OTel context.
+ * Stored in OTel context by SoftprobeContext.withData/run.
+ */
+function getContext() {
+    return {
+        mode: context_1.SoftprobeContext.getMode(),
+        storage: context_1.SoftprobeContext.getCassette(),
+        traceId: context_1.SoftprobeContext.getTraceId(),
+        strictReplay: context_1.SoftprobeContext.getStrictReplay(),
+        strictComparison: context_1.SoftprobeContext.getStrictComparison(),
+        matcher: context_1.SoftprobeContext.getMatcher(),
+        inboundRecord: context_1.SoftprobeContext.getInboundRecord(),
+    };
+}
+/**
+ * Returns the active matcher for the current replay context, if any.
+ * In REPLAY mode, returns global matcher when context has no matcher; includes baggage fallback.
+ */
+function getActiveMatcher() {
+    return context_1.SoftprobeContext.getMatcher();
+}
+/**
+ * Returns the recorded inbound response for the current trace, if any.
+ * Set by runWithContext when loading a cassette that contains a record with type "inbound".
+ */
+function getRecordedInboundResponse() {
+    return context_1.SoftprobeContext.getInboundRecord();
+}
+/**
+ * Task 15.2.1: Compares the actual response (status and body) to the recorded inbound for the current trace.
+ * Task 15.2.2: When SOFTPROBE_STRICT_COMPARISON is set, also compares headers.
+ * @throws When no recorded inbound exists, or when status, body, or (if strict) headers do not match.
+ */
+function compareInbound(actual) {
+    (0, compare_1.compareInboundWithRecord)(actual, getRecordedInboundResponse());
+}
+/**
+ * Returns recorded cassette records for the given traceId from the active context only.
+ * Records are context-scoped (matcher is created by SoftprobeContext.run(REPLAY)). Task 15.3.1.
+ */
+function getRecordsForTrace(traceId) {
+    return (0, store_accessor_1.getRecordsForTrace)(traceId);
+}
+/**
+ * Sets the global replay matcher. For test/cleanup only; the framework creates matchers in SoftprobeContext.run(REPLAY).
+ * getMatcher() returns only the context matcher, not this global.
+ */
+function setGlobalReplayMatcher(matcher) {
+    context_1.SoftprobeContext.setGlobalReplayMatcher(matcher);
+}
+/**
+ * Primes the active matcher with records for the given traceId.
+ * Called by server middleware (Express/Fastify) after run(); the matcher was already seeded in run(), so this is a no-op when records are present.
+ */
+function activateReplayForContext(traceId) {
+    const matcher = getActiveMatcher();
+    if (matcher && '_setRecords' in matcher) {
+        const records = getRecordsForTrace(traceId);
+        if (records.length > 0) {
+            matcher._setRecords(records);
+        }
+    }
+}
+/**
+ * No-op. Replay is context-scoped; only SoftprobeContext.run(REPLAY) creates and seeds the matcher.
+ * Use cassetteDirectory + traceId and middleware so each request gets its own context and matcher.
+ */
+async function ensureReplayLoadedForRequest() { }
+/** Runs callback inside a scoped Softprobe context using SoftprobeRunOptions. */
+function run(options, fn) {
+    return context_1.SoftprobeContext.run(options, fn);
+}
+var baggage_2 = require("./api/baggage");
+Object.defineProperty(exports, "getContextWithReplayBaggage", { enumerable: true, get: function () { return baggage_2.getContextWithReplayBaggage; } });
+exports.softprobe = {
+    getContext,
+    getActiveMatcher,
+    getRecordedInboundResponse,
+    compareInbound,
+    getRecordsForTrace,
+    setGlobalReplayMatcher,
+    activateReplayForContext,
+    ensureReplayLoadedForRequest,
+    run,
+    getContextWithReplayBaggage: baggage_1.getContextWithReplayBaggage,
+};
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":";;;AAYA,gCAYC;AAMD,4CAEC;AAMD,gEAEC;AAOD,wCAEC;AAMD,gDAEC;AAMD,wDAEC;AAMD,4DAQC;AAMD,oEAAsE;AAGtE,kBAEC;AAvFD,2CAA4D;AAC5D,2CAAmF;AACnF,kEAAkG;AAClG,uCAA6C;AAE7C;;;GAGG;AACH,SAAgB,UAAU;IAGxB,OAAO;QACL,IAAI,EAAE,0BAAgB,CAAC,OAAO,EAAE;QAChC,OAAO,EAAE,0BAAgB,CAAC,WAAW,EAAE;QACvC,OAAO,EAAE,0BAAgB,CAAC,UAAU,EAAE;QACtC,YAAY,EAAE,0BAAgB,CAAC,eAAe,EAAE;QAChD,gBAAgB,EAAE,0BAAgB,CAAC,mBAAmB,EAAE;QACxD,OAAO,EAAE,0BAAgB,CAAC,UAAU,EAAE;QACtC,aAAa,EAAE,0BAAgB,CAAC,gBAAgB,EAAE;KACnD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,gBAAgB;IAC9B,OAAO,0BAAgB,CAAC,UAAU,EAAE,CAAC;AACvC,CAAC;AAED;;;GAGG;AACH,SAAgB,0BAA0B;IACxC,OAAO,0BAAgB,CAAC,gBAAgB,EAAE,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,SAAgB,cAAc,CAAC,MAA2B;IACxD,IAAA,kCAAwB,EAAC,MAAM,EAAE,0BAA0B,EAAE,CAAC,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,SAAgB,kBAAkB,CAAC,OAAe;IAChD,OAAO,IAAA,mCAA2B,EAAC,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED;;;GAGG;AACH,SAAgB,sBAAsB,CAAC,OAAqC;IAC1E,0BAAgB,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;AACnD,CAAC;AAED;;;GAGG;AACH,SAAgB,wBAAwB,CAAC,OAAe;IACtD,MAAM,OAAO,GAAG,gBAAgB,EAAE,CAAC;IACnC,IAAI,OAAO,IAAI,aAAa,IAAI,OAAO,EAAE,CAAC;QACxC,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;QAC5C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtB,OAA4B,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,4BAA4B,KAAmB,CAAC;AAEtE,iFAAiF;AACjF,SAAgB,GAAG,CAAI,OAA4B,EAAE,EAAwB;IAC3E,OAAO,0BAAgB,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC3C,CAAC;AAED,yCAA4D;AAAnD,sHAAA,2BAA2B,OAAA;AAEvB,QAAA,SAAS,GAAG;IACvB,UAAU;IACV,gBAAgB;IAChB,0BAA0B;IAC1B,cAAc;IACd,kBAAkB;IAClB,sBAAsB;IACtB,wBAAwB;IACxB,4BAA4B;IAC5B,GAAG;IACH,2BAA2B,EAA3B,qCAA2B;CAC5B,CAAC"}

package/dist/bindings/http-span.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Legacy compatibility re-export for HTTP span helpers.
+ */
+export { HttpSpan, fromSpan, tagRequest } from '../core/bindings/http-span';
+export type { HttpSpanData } from '../core/bindings/http-span';
+//# sourceMappingURL=http-span.d.ts.map

package/dist/bindings/http-span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-span.d.ts","sourceRoot":"","sources":["../../src/bindings/http-span.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/bindings/http-span.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tagRequest = exports.fromSpan = exports.HttpSpan = void 0;
+/**
+ * Legacy compatibility re-export for HTTP span helpers.
+ */
+var http_span_1 = require("../core/bindings/http-span");
+Object.defineProperty(exports, "HttpSpan", { enumerable: true, get: function () { return http_span_1.HttpSpan; } });
+Object.defineProperty(exports, "fromSpan", { enumerable: true, get: function () { return http_span_1.fromSpan; } });
+Object.defineProperty(exports, "tagRequest", { enumerable: true, get: function () { return http_span_1.tagRequest; } });
+//# sourceMappingURL=http-span.js.map

package/dist/bindings/http-span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-span.js","sourceRoot":"","sources":["../../src/bindings/http-span.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,wDAA4E;AAAnE,qGAAA,QAAQ,OAAA;AAAE,qGAAA,QAAQ,OAAA;AAAE,uGAAA,UAAU,OAAA"}

package/dist/bindings/postgres-span.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Legacy compatibility re-export for Postgres span helpers.
+ */
+export { PostgresSpan, fromSpan, tagQuery } from '../core/bindings/postgres-span';
+export type { PostgresSpanData } from '../core/bindings/postgres-span';
+//# sourceMappingURL=postgres-span.d.ts.map

package/dist/bindings/postgres-span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-span.d.ts","sourceRoot":"","sources":["../../src/bindings/postgres-span.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAClF,YAAY,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/bindings/postgres-span.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tagQuery = exports.fromSpan = exports.PostgresSpan = void 0;
+/**
+ * Legacy compatibility re-export for Postgres span helpers.
+ */
+var postgres_span_1 = require("../core/bindings/postgres-span");
+Object.defineProperty(exports, "PostgresSpan", { enumerable: true, get: function () { return postgres_span_1.PostgresSpan; } });
+Object.defineProperty(exports, "fromSpan", { enumerable: true, get: function () { return postgres_span_1.fromSpan; } });
+Object.defineProperty(exports, "tagQuery", { enumerable: true, get: function () { return postgres_span_1.tagQuery; } });
+//# sourceMappingURL=postgres-span.js.map

package/dist/bindings/postgres-span.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-span.js","sourceRoot":"","sources":["../../src/bindings/postgres-span.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,gEAAkF;AAAzE,6GAAA,YAAY,OAAA;AAAE,yGAAA,QAAQ,OAAA;AAAE,yGAAA,QAAQ,OAAA"}

package/dist/bindings/redis-span.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Legacy compatibility re-export for Redis span helpers.
+ */
+export { RedisSpan, fromSpan, tagCommand } from '../core/bindings/redis-span';
+export type { RedisSpanData } from '../core/bindings/redis-span';
+//# sourceMappingURL=redis-span.d.ts.map

package/dist/bindings/redis-span.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-span.d.ts","sourceRoot":"","sources":["../../src/bindings/redis-span.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC9E,YAAY,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC"}