@use-tusk/drift-node-sdk 0.1.0 → 0.1.4

package/README.md

@@ -3,8 +3,9 @@
 </p>
 
 <p align="center">
+  <a href="https://www.npmjs.com/package/@use-tusk/drift-node-sdk"><img src="https://img.shields.io/npm/v/@use-tusk/drift-node-sdk" alt="npm version"></a>
   <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a>
-  <a href="https://github.com/Use-Tusk/tusk-drift-sdk/commits/main"><img src="https://img.shields.io/github/last-commit/Use-Tusk/tusk-drift-sdk" alt="GitHub last commit"></a>
+  <a href="https://github.com/Use-Tusk/drift-node-sdk/commits/main/"><img src="https://img.shields.io/github/last-commit/Use-Tusk/drift-node-sdk" alt="GitHub last commit"></a>
 </p>
 
 The Node.js Tusk Drift SDK enables fast and deterministic API testing by capturing and replaying API calls made to/from your service. Automatically record real-world API calls, then replay them as tests using the [Tusk CLI](https://github.com/Use-Tusk/tusk-drift-cli) to find regressions. During replay, all outbound requests are intercepted with recorded data to ensure consistent behavior without side-effects.
@@ -49,28 +50,57 @@ npm install @use-tusk/drift-node-sdk
 Before setting up the SDK, ensure you have:
 
 - Completed the [CLI wizard](https://github.com/Use-Tusk/tusk-drift-cli?tab=readme-ov-file#quick-start)
-- Obtained an API key from the [Tusk Drift dashboard](https://usetusk.ai/app/settings/api-keysgoogle.com)
+- Obtained an API key from the [Tusk Drift dashboard](https://usetusk.ai/app/settings/api-keys) (only required if using Tusk Cloud)
 
 Follow these steps in order to properly initialize the Tusk Drift SDK:
 
 ### 1. Create SDK Initialization File
 
-Create a separate file (e.g. `tdInit.ts`) to initialize the Tusk Drift SDK. This ensures the SDK is initialized as early as possible before any other modules are loaded.
+Create a separate file (e.g. `tuskDriftInit.ts`) to initialize the Tusk Drift SDK. This ensures the SDK is initialized as early as possible before any other modules are loaded.
+
+**IMPORTANT**: Ensure that `TuskDrift` is initialized before any other telemetry providers (e.g. OpenTelemetry, Sentry, etc.). If not, your existing telemetry may not work properly.
+
+#### For CommonJS Applications
 
 ```typescript
-// tdInit.ts
+// tuskDriftInit.ts
 import { TuskDrift } from "@use-tusk/drift-node-sdk";
 
 // Initialize SDK immediately
 TuskDrift.initialize({
   apiKey: process.env.TUSK_DRIFT_API_KEY,
-  env: process.env.ENV,
-  logLevel: process.env.TUSK_DRIFT_LOG_LEVEL,
+  env: process.env.NODE_ENV,
 });
 
 export { TuskDrift };
 ```
 
+#### For ESM Applications
+
+ESM applications require additional setup to properly intercept module imports:
+
+```typescript
+// tuskDriftInit.ts
+import { register } from 'node:module';
+import { pathToFileURL } from 'node:url';
+
+// Register the ESM loader
+// This enables interception of ESM module imports
+register('@use-tusk/drift-node-sdk/hook.mjs', pathToFileURL('./'));
+
+import { TuskDrift } from "@use-tusk/drift-node-sdk";
+
+// Initialize SDK immediately
+TuskDrift.initialize({
+  apiKey: process.env.TUSK_DRIFT_API_KEY,
+  env: process.env.NODE_ENV,
+});
+
+export { TuskDrift };
+```
+
+**Why the ESM loader is needed**: ESM imports are statically analyzed and hoisted, meaning all imports are resolved before any code runs. The `register()` call sets up Node.js loader hooks that intercept module imports, allowing the SDK to instrument packages like `postgres`, `http`, etc. Without this, the SDK cannot patch ESM modules.
+
 #### Configuration Options
 
 <table>
@@ -86,13 +116,13 @@ export { TuskDrift };
     <tr>
       <td><code>apiKey</code></td>
       <td><code>string</code></td>
-      <td><b>Required.</b></td>
+      <td><b>Required if using Tusk Cloud</b></td>
       <td>Your Tusk Drift API key.</td>
     </tr>
     <tr>
       <td><code>env</code></td>
       <td><code>string</code></td>
-      <td><b>Required.</b></td>
+      <td><code>process.env.NODE_ENV</code></td>
       <td>The environment name.</td>
     </tr>
     <tr>
@@ -106,18 +136,37 @@ export { TuskDrift };
 
 ### 2. Import SDK at Application Entry Point
 
-In your main server file (e.g., `server.ts`, `index.ts`, `app.ts`), import the initialized SDK **at the very top**, before any other imports:
+#### For CommonJS Applications
+
+In your main server file (e.g., `server.ts`, `index.ts`, `app.ts`), require the initialized SDK **at the very top**, before any other requires:
 
 ```typescript
 // server.ts
-import { TuskDrift } from "./tdInit"; // MUST be the first import
+import { TuskDrift } from "./tuskDriftInit"; // MUST be the first import
 
 // ... other imports ...
 
 // Your application setup...
 ```
 
-> **IMPORTANT**: Ensure NO require/import calls are made before importing the SDK initialization file. This guarantees proper instrumentation of all dependencies.
+> **IMPORTANT**: Ensure NO require calls are made before requiring the SDK initialization file. This guarantees proper instrumentation of all dependencies.
+
+#### For ESM Applications
+
+For ESM applications, you **cannot** control import order within your application code because all imports are hoisted. Instead, use the `--import` flag:
+
+**Update your package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "dev": "node --import ./dist/tuskDriftInit.js dist/server.js",
+    "dev:record": "TUSK_DRIFT_MODE=RECORD node --import ./dist/tuskDriftInit.js dist/server.js"
+  }
+}
+```
+
+**Why `--import` is required for ESM**: In ESM, all `import` statements are hoisted and evaluated before any code runs, making it impossible to control import order within a file. The `--import` flag ensures the SDK initialization (including loader registration) happens in a separate phase before your application code loads, guaranteeing proper module interception.
 
 ### 3. Update Configuration File
 
@@ -165,13 +214,13 @@ recording:
   </tbody>
 </table>
 
-### 3. Mark App as Ready
+### 4. Mark App as Ready
 
 Once your application has completed initialization (database connections, middleware setup, etc.), mark it as ready:
 
 ```typescript
 // server.ts
-import { TuskDrift } from "./tdInit";
+import { TuskDrift } from "./tuskDriftInit";
 
 // ... other imports ...
 
@@ -259,7 +308,11 @@ You should see output similar to:
 
 1. **Check sampling rate**: Ensure `sampling_rate` in `.tusk/config.yaml` is 1.0
 2. **Verify app readiness**: Make sure you're calling `TuskDrift.markAppAsReady()`
-3. **Check endpoint paths**: Ensure your endpoint isn't in `exclude_paths`
+3. **Use debug mode in SDK**: Add `logLevel: 'debug'` to the initialization parameters
+
+#### Existing telemetry not working
+
+Ensure that `TuskDrift.initialize()` is called before any other telemetry providers (e.g. OpenTelemetry, Sentry, etc.).
 
 #### Replay failures