@alwaysmeticulous/sdk-bundles-api 2.324.0 → 2.325.0

package/dist/backend-recorder/bundle-to-sdk/init-backend-recorder.d.ts

@@ -28,6 +28,24 @@ export type MeticulousIORedisWrapper = <T>(client: T) => T;
  * across the bundle boundary.
  */
 export type MeticulousPostgresJsWrapper = <T>(sql: T) => T;
+/**
+ * The kinds of Cloudflare binding the recorder captures. Normally inferred from the binding
+ * itself; name one explicitly when inference gets it wrong. `"skip"` leaves it untouched.
+ */
+export type MeticulousCloudflareBindingKind = "kv" | "r2" | "queue" | "durable-object-namespace" | "fetcher" | "skip";
+export interface MeticulousCloudflareEnvOptions {
+    /** Binding names to leave unrecorded, on top of the defaults (`ASSETS`, `__STATIC_CONTENT`). */
+    skipBindings?: readonly string[];
+    /** Overrides for the inferred binding kind, keyed by `env` key. */
+    bindings?: Readonly<Record<string, MeticulousCloudflareBindingKind>>;
+}
+/**
+ * Wraps a Cloudflare `env` so calls through its bindings are recorded (record mode) or served from
+ * recordings (replay mode), returning a shallow copy with each recognised binding replaced. Apply it
+ * at the request edge: `const env = handle.withMeticulousCloudflareEnv(context.cloudflare.env)`.
+ * Safe to call across the bundle boundary.
+ */
+export type MeticulousCloudflareEnvWrapper = <TEnv extends object>(env: TEnv, options?: MeticulousCloudflareEnvOptions) => TEnv;
 /** Identifies one wrapped operation to the recorder. See {@link MeticulousOperationWrapper}. */
 export interface MeticulousOperationSpec {
     /**
@@ -196,6 +214,36 @@ export interface BackendRecorderHandle {
      * guard with `handle?.withMeticulousOperation`.
      */
     withMeticulousOperation?: MeticulousOperationWrapper;
+    /**
+     * The Meticulous Cloudflare `env` wrapper. Apply it at your request edge
+     * (`const env = handle.withMeticulousCloudflareEnv(context.cloudflare.env)`) so calls through
+     * your KV, R2, queue, Durable Object and service bindings are recorded (record mode) or served
+     * from recordings (replay mode).
+     *
+     * Required for an app that runs on **Node** with Cloudflare bindings — a React Router or
+     * TanStack Start dev server or container using `cloudflareDevProxy`, or anything else built on
+     * wrangler's `getPlatformProxy`. There each binding is a proxy object created per process: there
+     * is no module for a require hook to intercept and no prototype to patch, so handing us `env` is
+     * the only seam. (A deployed Worker records through `@alwaysmeticulous/backend-recorder-workerd`
+     * instead.)
+     *
+     * Returns a shallow copy of `env` with each recognised binding replaced by a wrapper; plain
+     * variables are passed through untouched. It dispatches per call, so it is safe to apply while
+     * building your request handler, and with the recorder disabled or uninitialised it returns `env`
+     * unchanged.
+     *
+     * Apply it **before any `env` wrapper of your own**. Outermost, a replayed call is served without
+     * your wrapper running at all; innermost, your wrapper still runs — emitting spans, retrying,
+     * mutating — around a call that never happens.
+     *
+     * Arguments and results are stored as JSON, so both must be JSON-serializable. R2 is a partial
+     * exception: its calls are recorded but still run for real during a replay, because what its
+     * operations return is a metadata handle that cannot be captured cheaply.
+     *
+     * Optional so older recorder bundles (which predate this field) still satisfy the type;
+     * guard with `handle?.withMeticulousCloudflareEnv`.
+     */
+    withMeticulousCloudflareEnv?: MeticulousCloudflareEnvWrapper;
     /**
      * Records a value into the session without stubbing anything — app state a replay should be
      * able to account for (resolved feature flags, a chosen experiment arm) that no call

package/dist/backend-recorder/bundle-to-sdk/init-backend-recorder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-backend-recorder.d.ts","sourceRoot":"","sources":["../../../src/backend-recorder/bundle-to-sdk/init-backend-recorder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE;QACL,cAAc,EAAE,CAAC,MAAM,EAAE;YACvB,KAAK,CAAC,EAAE,MAAM,CAAC;YACf,SAAS,EAAE,MAAM,CAAC;YAClB,IAAI,EAAE,OAAO,CAAC;YACd,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;SAC5C,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;KACxB,CAAC;CACH;AAED;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,2BAA2B,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;AAE3D,gGAAgG;AAChG,MAAM,WAAW,uBAAuB;IACtC;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;;;;;;OASG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,EACzC,IAAI,EAAE,uBAAuB,EAC7B,EAAE,EAAE,MAAM,CAAC,KACR,CAAC,CAAC;AAEP;;;GAGG;AACH,MAAM,MAAM,6BAA6B,GAAG,CAC1C,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,KACX,IAAI,CAAC;AAEV;;;;;;;;;GASG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,OAAO,CAAC;AAElD;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,uBAAuB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;AAE7E,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,yBAAyB,CAAC,EAAE,yBAAyB,CAAC;IAEtD;;;;;;;;;;;;;;;;OAgBG;IACH,qBAAqB,CAAC,EAAE,wBAAwB,CAAC;IAEjD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,sBAAsB,CAAC,EAAE,2BAA2B,CAAC;IAErD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,uBAAuB,CAAC,EAAE,0BAA0B,CAAC;IAErD;;;;;;;;;;OAUG;IACH,2BAA2B,CAAC,EAAE,6BAA6B,CAAC;IAE5D;;;;;;;;;;;OAWG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;IAC9C,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,oBAAoB,CAAC;IAC1C,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,uBAAuB,CAAC;CAChD"}
+{"version":3,"file":"init-backend-recorder.d.ts","sourceRoot":"","sources":["../../../src/backend-recorder/bundle-to-sdk/init-backend-recorder.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -14,5 +14,5 @@ export { MeticulousPublicApi, MeticulousPressureObserver, MeticulousPressureObse
 export { MeticulousPrivateApi } from "./window-api/private-window-api";
 export { RunCrawlOptions, RunCrawlResult, } from "./crawler/sdk-to-bundle/run-crawl";
 export { BackendRecorderConfig } from "./backend-recorder/sdk-to-bundle/init-backend-recorder";
-export { BackendRecorderHandle, MeticulousPrismaExtension, MeticulousIORedisWrapper, MeticulousPostgresJsWrapper, MeticulousOperationSpec, MeticulousOperationWrapper, MeticulousObservationRecorder, } from "./backend-recorder/bundle-to-sdk/init-backend-recorder";
+export { BackendRecorderHandle, MeticulousCloudflareBindingKind, MeticulousCloudflareEnvOptions, MeticulousCloudflareEnvWrapper, MeticulousPrismaExtension, MeticulousIORedisWrapper, MeticulousPostgresJsWrapper, MeticulousOperationSpec, MeticulousOperationWrapper, MeticulousObservationRecorder, } from "./backend-recorder/bundle-to-sdk/init-backend-recorder";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EACL,4BAA4B,EAC5B,YAAY,EACZ,6BAA6B,EAC7B,eAAe,EACf,+BAA+B,EAC/B,sBAAsB,EACtB,uCAAuC,EACvC,WAAW,EACX,sBAAsB,EACtB,kBAAkB,EAClB,wBAAwB,EACxB,2BAA2B,EAC3B,kCAAkC,EAClC,oBAAoB,EACpB,kCAAkC,EAClC,2BAA2B,EAC3B,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAC7F,OAAO,EAAE,8BAA8B,EAAE,MAAM,gEAAgE,CAAC;AAChH,OAAO,EAAE,mCAAmC,EAAE,MAAM,sEAAsE,CAAC;AAC3H,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,eAAe,EACf,sBAAsB,GACvB,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gEAAgE,CAAC;AACnG,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,sEAAsE,CAAC;AAC9E,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,oDAAoD,CAAC;AACxF,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,qCAAqC,EACrC,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,2BAA2B,EAC3B,0BAA0B,EAC1B,iCAAiC,EACjC,0BAA0B,EAC1B,iCAAiC,GAClC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EACL,eAAe,EACf,cAAc,GACf,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,wDAAwD,CAAC;AAC/F,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,EAC3B,uBAAuB,EACvB,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,wDAAwD,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EACL,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,0BAA0B,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,OAAO,EACL,4BAA4B,EAC5B,YAAY,EACZ,6BAA6B,EAC7B,eAAe,EACf,+BAA+B,EAC/B,sBAAsB,EACtB,uCAAuC,EACvC,WAAW,EACX,sBAAsB,EACtB,kBAAkB,EAClB,wBAAwB,EACxB,2BAA2B,EAC3B,kCAAkC,EAClC,oBAAoB,EACpB,kCAAkC,EAClC,2BAA2B,EAC3B,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAC7F,OAAO,EAAE,8BAA8B,EAAE,MAAM,gEAAgE,CAAC;AAChH,OAAO,EAAE,mCAAmC,EAAE,MAAM,sEAAsE,CAAC;AAC3H,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,eAAe,EACf,sBAAsB,GACvB,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gEAAgE,CAAC;AACnG,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,sEAAsE,CAAC;AAC9E,OAAO,EACL,2BAA2B,EAC3B,eAAe,EACf,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oDAAoD,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,oDAAoD,CAAC;AACxF,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,qCAAqC,EACrC,wBAAwB,EACxB,wBAAwB,EACxB,uBAAuB,EACvB,2BAA2B,EAC3B,0BAA0B,EAC1B,iCAAiC,EACjC,0BAA0B,EAC1B,iCAAiC,GAClC,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,EACL,eAAe,EACf,cAAc,GACf,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,wDAAwD,CAAC;AAC/F,OAAO,EACL,qBAAqB,EACrB,+BAA+B,EAC/B,8BAA8B,EAC9B,8BAA8B,EAC9B,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,EAC3B,uBAAuB,EACvB,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,wDAAwD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwaysmeticulous/sdk-bundles-api",
-  "version": "2.324.0",
+  "version": "2.325.0",
   "description": "Meticulous common types",
   "license": "ISC",
   "main": "dist/index.js",