@alwaysmeticulous/sdk-bundles-api 2.159.0 → 2.160.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { RecordConfig, RecordSettings, RecordState } from "./record";
 export { MeticulousWindowConfig, NetworkResponseSanitizer, } from "./record/record-settings";
+export * from "./record/middleware";
 export { ReplayAndStoreResultsOptions, ReplayTarget, SnapshottedAssetsReplayTarget, URLReplayTarget, OriginalRecordedURLReplayTarget, ReplayExecutionOptions, ReplayOrchestratorScreenshottingOptions, GeneratedBy, GeneratedByNotebookRun, GeneratedByTestRun, GeneratedByReplayCommand, ScreenshotComparisonOptions, ScreenshotComparisonEnabledOptions, CompareScreenshotsTo, CompareScreenshotsToSpecificReplay, CompareScreenshotsToTestRun, DoNotCompareScreenshots, OutOfDateClientError, BeforeUserEventOptions, AppUrlConfig, } from "./replay-orchestrator/sdk-to-bundle/execute-replay";
 export { ExecuteTestRunOptions } from "./replay-orchestrator/sdk-to-bundle/execute-test-run";
 export { ExecuteScheduledTestRunOptions } from "./replay-orchestrator/sdk-to-bundle/execute-scheduled-test-run";

package/dist/index.js

@@ -1,3 +1,18 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./record/middleware"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAKA,sDAAoC"}

package/dist/record/middleware.d.ts

@@ -0,0 +1,135 @@
+import { Cookie, HarRequest, HarResponse, IDBObjectStoreWithEntries, StorageEntry, WebSocketConnectionData } from "@alwaysmeticulous/api";
+/**
+ * Transformations that are applied to a recorder payload before it is sent to Meticulous's servers. This is
+ * useful for redacting sensitive information from the payload before it is sent.
+ *
+ * Notes:
+ *  - For each of these transforms returning `null` will cause that value to be dropped from the payload.
+ *  - The sanitized responses should be designed such that the app can still correctly function at replay time.
+ *    For example, if you want to sanitize email addresses, replace them with a dummy email address
+ *    of a current format. That will ensure that the email address will still pass any validation the application may have.
+ *  - Please ensure that these functions are fast to run, and handle errors gracefully, since they'll be applied to all
+ *    data. Some of the data, such as network response bodies, may be very large.
+ *  - Please do not mutate the objects. Instead return a new object with the desired changes.
+ *  - New fields may be added to objects in future. This means that:
+ *
+ *      `transformLocalStorageEntry: ({ key, value }) => ({ key, value: "REDACTED" })`
+ *
+ *    Is unsafe. While:
+ *
+ *      `transformLocalStorageEntry: ({ value, ...rest }) => ({ ...rest, value: "REDACTED" })`
+ *
+ *    Is safe.
+ */
+export interface RecorderMiddleware {
+    /**
+     * Transforms local storage entries before they are sent to Meticulous's servers.
+     *
+     * Returning null will cause the entry to be dropped from the payload.
+     *
+     * See JSDoc for {@link RecorderMiddleware} before implementing.
+     */
+    transformLocalStorageEntry?: (entry: StorageEntry) => StorageEntry | null;
+    /**
+     * Transforms session storage entries before they are sent to Meticulous's servers.
+     *
+     * Returning null will cause the entry to be dropped from the payload.
+     *
+     * See JSDoc for {@link RecorderMiddleware} before implementing.
+     */
+    transformSessionStorageEntry?: (entry: StorageEntry) => StorageEntry | null;
+    /**
+     * Transforms IndexedDB entries before they are sent to Meticulous's servers.
+     *
+     * Returning null will cause the entry to be dropped from the payload.
+     *
+     * Please note that the entries for a single database may be split across multiple payloads.
+     *
+     * See JSDoc for {@link RecorderMiddleware} before implementing.
+     */
+    transformIndexedDBEntries?: (entries: IndexedDBStoreEntries) => IndexedDBStoreEntries | null;
+    /**
+     * Transforms cookies before they are sent to Meticulous's servers.
+     *
+     * Returning null will cause the cookie to be dropped from the payload.
+     *
+     * See JSDoc for {@link RecorderMiddleware} before implementing.
+     */
+    transformCookie?: (cookie: Cookie) => Cookie | null;
+    /**
+     * Transforms network requests before they are sent to Meticulous's servers.
+     *
+     * Please ensure you call tryLoadAndStartRecorder with your middleware, or set
+     * `window.METICULOUS_RECORDER_MIDDLEWARE_V1`, when Meticulous is replaying sessions at test time ('replay time'),
+     * and not just when you want to record. This allows Meticulous to auto-detect your middleware and transform the
+     * requests at replay time when finding an appropiate request to match with. This enables correctly matching
+     * requests with the corresponding saved responses even if the requests have been substantially transformed by
+     * your middleware.
+     *
+     * Please note however that enough unique information must still be preserved in the redacted network request
+     * to allow Meticulous to correctly match a request that is performed at replay time by your application with
+     * the correct corresponding saved request stored in the recording / recorded session.
+     *
+     * For example: if you replace all query string values with "[REDACTED]", and there are multiple distinct requests with
+     * identical paths but different query string values then Meticulous will not have enough information to match
+     * them correctly. However if instead you md5 hash all query string values then Meticulous would have enough
+     * information to match the requests correctly.
+     *
+     * Note: returning null will cause the request and the corresponding response to be dropped from the payload.
+     * If the request/response is dropped from the payload but at replay time your application still makes
+     * the request then Meticulous will look for another closely matching recorded request, and replay that,
+     * or if none can be found it will fail the request with 'net::ERR_FAILED'/'Failed to fetch'.
+     *
+     * See JSDoc for {@link RecorderMiddleware} before implementing.
+     */
+    transformNetworkRequest?: (request: Omit<HarRequest, "queryString">, metadata: NetworkRequestMetadata) => Omit<HarRequest, "queryString"> | null;
+    /**
+     * Transforms network requests before they are sent to Meticulous's servers.
+     *
+     * Returning null will cause the request and the response to be dropped from the payload.
+     * If the request/response is dropped from the payload but at replay time your application still makes
+     * the request then Meticulous will look for another closely matching recorded request, and replay that,
+     * or if none can be found it will fail the request with 'net::ERR_FAILED'/'Failed to fetch'.
+     *
+     * See JSDoc for {@link RecorderMiddleware} before implementing.
+     */
+    transformNetworkResponse?: (response: HarResponse, metadata: NetworkResponseMetadata) => HarResponse | null;
+    /**
+     * Transforms WebSocket messages before they are sent to Meticulous's servers.
+     *
+     * Returning null will cause the data to be dropped from the payload.
+     *
+     * Please note that the messages sent across a connection to a single URL may be split across multiple payloads.
+     *
+     * Note: we pass the WebSocketConnectionData to your middleware without the id field, and re-add the id field after
+     * you return the transformed data.
+     *
+     * See JSDoc for {@link RecorderMiddleware} before implementing.
+     */
+    transformWebSocketConnectionData?: (entry: Omit<WebSocketConnectionData, "id">) => Omit<WebSocketConnectionData, "id"> | null;
+}
+export interface IndexedDBStoreEntries {
+    databaseName: string;
+    objectStoreName: string;
+    entries: IDBObjectStoreWithEntries["entries"];
+}
+export interface NetworkRequestMetadata {
+    /**
+     * Milliseconds since unix epoch when the request was sent
+     *
+     * Note: this is only defined at record time, not when we redact the requests at replay time
+     * for matching with the stored redacted requests in the original recording. See JSDoc on
+     * {@link RecorderMiddleware.transformNetworkRequest} for more information.
+     */
+    requestStartedAt?: number;
+}
+export interface NetworkResponseMetadata {
+    /**
+     * Milliseconds since unix epoch when the request was sent
+     */
+    requestStartedAt: number;
+    /**
+     * Milliseconds since unix epoch when the response was received
+     */
+    responseReceivedAt: number;
+}

package/dist/record/middleware.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=middleware.js.map

package/dist/record/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/record/middleware.ts"],"names":[],"mappings":""}

package/dist/record/record-settings.d.ts

@@ -1,3 +1,4 @@
+import { NetworkResponseMetadata, RecorderMiddleware } from "./middleware";
 export interface MeticulousWindowConfig {
     METICULOUS_RECORDING_TOKEN?: string;
     METICULOUS_UPLOAD_INTERVAL_MS?: number;
@@ -6,6 +7,7 @@ export interface MeticulousWindowConfig {
     METICULOUS_FORCE_RECORDING?: boolean;
     METICULOUS_IS_PRODUCTION_ENVIRONMENT?: boolean;
     METICULOUS_NETWORK_RESPONSE_SANITIZERS?: NetworkResponseSanitizer[];
+    METICULOUS_RECORDER_MIDDLEWARE_V1: RecorderMiddleware[];
 }
 /**
  * Allows sanitizing network responses before they are sent to Meticulous's servers.
@@ -26,13 +28,3 @@ export interface NetworkResponseSanitizer {
      */
     sanitizeBody: (body: string, metadata: NetworkResponseMetadata) => string;
 }
-export interface NetworkResponseMetadata {
-    /**
-     * Milliseconds since unix epoch when the request was sent
-     */
-    requestStartedAt: number;
-    /**
-     * Milliseconds since unix epoch when the response was received
-     */
-    responseReceivedAt: number;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwaysmeticulous/sdk-bundles-api",
-  "version": "2.159.0",
+  "version": "2.160.0",
   "description": "Meticulous common types",
   "license": "ISC",
   "main": "dist/index.js",
@@ -46,5 +46,5 @@
   "bugs": {
     "url": "https://github.com/alwaysmeticulous/meticulous-sdk/issues"
   },
-  "gitHead": "887a4a6010a3d0aa7fc5e52e0180f48a76e5bf65"
+  "gitHead": "d1e2c73931448733dd3ad91d9def2720bb5f3b47"
 }