@alwaysmeticulous/backend-recorder-launcher 2.277.0

package/README.md

@@ -0,0 +1,78 @@
+# Backend Recorder Launcher
+
+Downloads the backend-recorder bundle script and executes it. The backend recorder intercepts HTTP requests/responses in Node.js apps using OpenTelemetry and exports spans to Meticulous.
+
+## Setup
+
+```bash
+npm install @alwaysmeticulous/backend-recorder-launcher
+```
+
+### Option 1: Using `instrumentation.js` (recommended)
+
+Create or update your `instrumentation.js` (or `instrumentation.ts`) file at the root of your project:
+
+```js
+const { initBackendRecorder } = require("@alwaysmeticulous/backend-recorder-launcher");
+
+initBackendRecorder({
+  recordingToken: process.env.METICULOUS_RECORDING_TOKEN,
+});
+```
+
+Then start your app with the `--require` flag so the recorder is loaded before your application code:
+
+```bash
+node --require ./instrumentation.js app.js
+```
+
+If you are using Next.js, add the instrumentation hook in `instrumentation.ts`:
+
+```ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    const { initBackendRecorder } = await import(
+      "@alwaysmeticulous/backend-recorder-launcher"
+    );
+    await initBackendRecorder({
+      recordingToken: process.env.METICULOUS_RECORDING_TOKEN,
+    });
+  }
+}
+```
+
+### Option 2: Auto-init (zero-code)
+
+Use the `auto-init` entry point which initializes the recorder as a side effect. No code changes needed — just add the `--require` flag:
+
+```bash
+node --require @alwaysmeticulous/backend-recorder-launcher/auto-init app.js
+```
+
+The auto-init entry point reads configuration from environment variables.
+
+## Configuration
+
+`initBackendRecorder` accepts an optional `BackendRecorderConfig` object:
+
+| Option                 | Type                  | Description                                      |
+|------------------------|-----------------------|--------------------------------------------------|
+| `enabled`              | `boolean`             | Enable/disable the recorder (default: `true`)    |
+| `meticulousProjectName`| `string`              | The name of the Meticulous project                |
+| `recordingToken`       | `string`              | Token used to authenticate span uploads           |
+| `exportMode`           | `"local" \| "s3"`     | Where to export spans (default: `"local"`)       |
+| `localOutputDir`       | `string`              | Directory for local exports                       |
+| `flushIntervalMs`      | `number`              | How often to flush spans (ms)                     |
+
+## Graceful shutdown
+
+`initBackendRecorder` returns a `BackendRecorderHandle` with a `stopRecording()` method. Call it before your process exits to flush any pending spans:
+
+```js
+const handle = await initBackendRecorder({ /* ... */ });
+
+process.on("SIGTERM", async () => {
+  await handle?.stopRecording();
+  process.exit(0);
+});
+```

package/dist/auto-init.d.ts

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

package/dist/auto-init.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const downloading_helpers_1 = require("@alwaysmeticulous/downloading-helpers");
+const AUTO_INIT_BUNDLE_PATH = "backend-record-js/v1/auto-init.bundle.js";
+const autoInit = async () => {
+    const bundleLocation = await (0, downloading_helpers_1.fetchAsset)(AUTO_INIT_BUNDLE_PATH);
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    require(bundleLocation);
+};
+autoInit().catch((error) => {
+    console.error("[meticulous] Error while bootstrapping backend recorder!");
+    console.error(error);
+});
+//# sourceMappingURL=auto-init.js.map

package/dist/auto-init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-init.js","sourceRoot":"","sources":["../src/auto-init.ts"],"names":[],"mappings":";;AAAA,+EAAmE;AAEnE,MAAM,qBAAqB,GACzB,0CAA0C,CAAC;AAE7C,MAAM,QAAQ,GAAG,KAAK,IAAI,EAAE;IAC1B,MAAM,cAAc,GAAG,MAAM,IAAA,gCAAU,EAAC,qBAAqB,CAAC,CAAC;IAC/D,iEAAiE;IACjE,OAAO,CAAC,cAAc,CAAC,CAAC;AAC1B,CAAC,CAAC;AAEF,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACzB,OAAO,CAAC,KAAK,CACX,0DAA0D,CAC3D,CAAC;IACF,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { BackendRecorderConfig, BackendRecorderHandle } from "@alwaysmeticulous/sdk-bundles-api";
+export declare const initBackendRecorder: (config?: BackendRecorderConfig) => Promise<BackendRecorderHandle | undefined>;
+export declare const getBackendRecorderBundlePath: (version?: string | null) => string;

package/dist/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBackendRecorderBundlePath = exports.initBackendRecorder = void 0;
+const common_1 = require("@alwaysmeticulous/common");
+const downloading_helpers_1 = require("@alwaysmeticulous/downloading-helpers");
+const MANUAL_INIT_BUNDLE_PATH = "backend-record-js/v1/manual-init.bundle.js";
+const initBackendRecorder = async (config) => {
+    const logger = (0, common_1.initLogger)();
+    logger.debug("Downloading backend recorder bundle...");
+    const bundleLocation = await (0, downloading_helpers_1.fetchAsset)(MANUAL_INIT_BUNDLE_PATH);
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return (await require(bundleLocation)).initBackendRecorder(config);
+};
+exports.initBackendRecorder = initBackendRecorder;
+const getBackendRecorderBundlePath = (version) => {
+    const versionFolder = version == null ? "v1" : `v/${version}`;
+    return `backend-record-js/${versionFolder}/manual-init.bundle.js`;
+};
+exports.getBackendRecorderBundlePath = getBackendRecorderBundlePath;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,qDAAsD;AACtD,+EAAmE;AAMnE,MAAM,uBAAuB,GAC3B,4CAA4C,CAAC;AAExC,MAAM,mBAAmB,GAAG,KAAK,EACtC,MAA8B,EACc,EAAE;IAC9C,MAAM,MAAM,GAAG,IAAA,mBAAU,GAAE,CAAC;IAC5B,MAAM,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;IACvD,MAAM,cAAc,GAAG,MAAM,IAAA,gCAAU,EAAC,uBAAuB,CAAC,CAAC;IAEjE,iEAAiE;IACjE,OAAO,CAAC,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC;AACrE,CAAC,CAAC;AATW,QAAA,mBAAmB,uBAS9B;AAEK,MAAM,4BAA4B,GAAG,CAC1C,OAAuB,EACf,EAAE;IACV,MAAM,aAAa,GACjB,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;IAC1C,OAAO,qBAAqB,aAAa,wBAAwB,CAAC;AACpE,CAAC,CAAC;AANW,QAAA,4BAA4B,gCAMvC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@alwaysmeticulous/backend-recorder-launcher",
+  "version": "2.277.0",
+  "description": "Downloads the backend-recorder bundle script and executes it",
+  "license": "ISC",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./auto-init": {
+      "types": "./dist/auto-init.d.ts",
+      "default": "./dist/auto-init.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "clean": "rimraf dist tsconfig.tsbuildinfo",
+    "build": "tsc --build tsconfig.json",
+    "dev": "tsc --build tsconfig.json --watch",
+    "format": "prettier --write src",
+    "lint": "eslint \"src/**/*.{js,ts,tsx}\"  --cache",
+    "lint:commit": "eslint --cache $(git diff --relative --name-only --diff-filter=ACMRTUXB master | grep  -E \"(.js$|.ts$|.tsx$)\")",
+    "lint:fix": "eslint \"src/**/*.{js,ts,tsx}\"  --cache --fix",
+    "depcheck": "depcheck --ignore-patterns=dist"
+  },
+  "dependencies": {
+    "@alwaysmeticulous/common": "workspace:*",
+    "@alwaysmeticulous/downloading-helpers": "workspace:*",
+    "@alwaysmeticulous/sdk-bundles-api": "workspace:*"
+  },
+  "author": {
+    "name": "The Meticulous Team",
+    "email": "eng@meticulous.ai",
+    "url": "https://meticulous.ai"
+  },
+  "engines": {
+    "node": ">= 18"
+  },
+  "homepage": "https://github.com/alwaysmeticulous/meticulous-sdk",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alwaysmeticulous/meticulous-sdk.git",
+    "directory": "packages/backend-recorder-launcher"
+  },
+  "bugs": {
+    "url": "https://github.com/alwaysmeticulous/meticulous-sdk/issues"
+  }
+}