scharff 1.3.0 → 2.0.0

package/README.md

@@ -1,39 +1,137 @@
-# Scharff Logger
-Scharff is a lightweight and versatile Node.js package designed to enhance your application's logging capabilities by seamlessly integrating a powerful outgoing request logger. With Scharff, you can effortlessly gain insights into the interactions your application has with external services, APIs, and resources.
+# Scharff
+Scharff is a lightweight Node.js interceptor that logs all `fetch` activity — outgoing requests, incoming responses, and related errors. It gives you clear, file-based visibility into your app's HTTP interactions with minimal setup.
 
 ## Installation
-1) run `npm install scharff`.
-2) fork the git repository `https://github.com/Minka1902/scharff.git`, and place it next to your project.
-
-## Usage
-1) in your entry point, import unregister from the package: `const { unregister } = require('scharff');`
-2) to stop the logger just run the unregister function: `unregister()`, or `npm uninstall scharff`.
-
-## What to expect
-1) The package will create a outgoingRequest.log file and start logging the requests to the file.
-2) In there you can see the fetch requests you sent.
-3) The request will be in the format below:</br>
-{</br>
-&nbsp;&nbsp;&nbsp;&nbsp;    "url":"http://www.example.com/update/ad423kbr1om82hu3d58a73g4",</br>
-&nbsp;&nbsp;&nbsp;&nbsp;    "originUrl":"/update/ad423kbr1om82hu3d58a73g4",</br>
-&nbsp;&nbsp;&nbsp;&nbsp;    "method":"GET",</br>
-&nbsp;&nbsp;&nbsp;&nbsp;    "headers":   </br>
-&nbsp;&nbsp;&nbsp;&nbsp;    {</br>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;        "Content-Type":"application/json",</br>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;        "Access-Control-Allow-Origin":"*"</br>
-&nbsp;&nbsp;&nbsp;&nbsp;    },</br>
-&nbsp;&nbsp;&nbsp;&nbsp;    "body":      </br>
-&nbsp;&nbsp;&nbsp;&nbsp;    {</br>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;        "isActive":true,</br>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;        "status":200,</br>
-&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;        "date":"2023-08-21T11:25:47.023Z"</br>
-&nbsp;&nbsp;&nbsp;&nbsp;    }</br>
+```bash
+npm install scharff
+```
+
+Or clone from GitHub:
+```bash
+git clone https://github.com/Minka1902/scharff.git
+```
+
+## Quick Start
+CommonJS:
+```js
+const listen = require('scharff');
+
+// Optional: override destinations
+listen.updateConfig({ outgoingLog: './logs/outgoing.log' });
+
+// Stop logging later
+listen();
+```
+
+TypeScript / ESM:
+```ts
+import listen = require('scharff');
+
+listen.updateConfig({ incomingLog: './logs/incoming.log' });
+// ... your app code
+listen(); // unregister
+```
+
+## What to Expect
+1) The package creates newline-delimited JSON (NDJSON) logs (defaults):
+    - `outgoingRequest.log`
+    - `outgoingRequestError.log`
+    - `incomingResponse.log`
+    - `incomingResponseError.log`
+2) Each `fetch` call is logged; request errors and response errors are separated.
+3) Example outgoing request entry:
+```jsx
+{
+    "url":"http://127.0.0.1:3000/update/www.example.com",
+    "ip":"192.168.1.10",
+    "date":{
+        "date":"2025-12-22",
+        "time":"14:05:10"
+    },
+    "originUrl":"/update/www.example.com",
+    "method":"PUT",
+    "headers":{
+        "Content-Type":"application/json",
+        "Access-Control-Allow-Origin":"*"
+    },
+    "body":{
+        "isActive":true,
+        "status":200,
+        "lastChecked":"2025-12-22T14:05:10.200Z"
+    }
 }
+```
+
+## New in this release
+1) Added request error logging
+2) Added response logging
+3) Added response error logging
+4) Made log file names configurable via environment variables
+5) Added runtime config API: `listen.updateConfig()` and `listen.getConfig()`
+
+## Requirements
+- Node.js v18+ (for native `fetch` and modern APIs)
+
+## Configuration
+Default log paths live in `config/default.js`. You can override them with environment variables or at runtime:
+
+```
+SCHARFF_OUTGOING_LOG=./outgoingRequest.log
+SCHARFF_OUTGOING_ERROR_LOG=./outgoingRequestError.log
+SCHARFF_INCOMING_LOG=./incomingResponse.log
+SCHARFF_INCOMING_ERROR_LOG=./incomingResponseError.log
+```
+
+### Runtime Overrides
+```js
+const listen = require('scharff');
+
+// Change any log destination at runtime
+listen.updateConfig({
+    outgoingLog: './logs/outgoing.log',
+    outgoingErrorLog: './logs/outgoing-errors.log',
+    incomingLog: './logs/incoming.log',
+    incomingErrorLog: './logs/incoming-errors.log'
+});
+
+// Inspect current config
+console.log(listen.getConfig());
+```
+
+### API
+- `listen()` – unregisters all interceptors (stops logging)
+- `listen.updateConfig(overrides)` – update any of `outgoingLog`, `outgoingErrorLog`, `incomingLog`, `incomingErrorLog`
+- `listen.getConfig()` – returns the current effective config
+
+## Features
+- **Outgoing request logging**: URL, method, headers, body, local IP, timestamps
+- **Request error logging**: errors before a request is sent
+- **Incoming response logging**: status, URL, redirects, timestamps
+- **Response error logging**: errors from failed responses
+- **Configurable destinations**: via env vars or runtime API
+- **Runtime configuration**: update settings without restarting
+- **IPv4 detection**: includes your machine’s IPv4 in entries
+- **Safe JSON parsing**: gracefully handles non‑JSON bodies
+- **Base URL stripping**: store clean paths alongside full URLs
+- **TypeScript types**: ships `dist/index.d.ts`
+
+## Project Structure
+```
+scharff/
+├── src/
+│   ├── config/default.ts     # Configuration defaults and loader
+│   ├── constants/functions.ts # Helper utilities (URL manipulation)
+│   ├── index.ts              # Main interceptor and API
+│   └── types/fetch-intercept.d.ts
+├── dist/                     # Build output (generated by `npm run build`)
+├── package.json
+├── tsconfig.json
+└── README.md
+```
 
-## Next release
-1) 
+## Development / Publish
+- Build: `npm run build` (outputs to `dist/`)
+- Publish: `npm publish --access public` (runs build via `prepare`)
+- Entry points: `main` → `dist/index.js`, `types` → `dist/index.d.ts`
 
-## Future additions
-1) We will add a request error logger.
-2) We will add a response logger.
-3) We will add a response error logger.
+Tip: Logs are newline‑delimited JSON (NDJSON). Use tools like `jq`, `ripgrep`, or `grep` to filter and analyze.

package/config/default.js

@@ -0,0 +1,15 @@
+const defaults = {
+  outgoingLog: './outgoingRequest.log',
+  outgoingErrorLog: './outgoingRequestError.log',
+  incomingLog: './incomingResponse.log',
+  incomingErrorLog: './incomingResponseError.log'
+};
+
+const loadConfig = () => ({
+  outgoingLog: process.env.SCHARFF_OUTGOING_LOG || defaults.outgoingLog,
+  outgoingErrorLog: process.env.SCHARFF_OUTGOING_ERROR_LOG || defaults.outgoingErrorLog,
+  incomingLog: process.env.SCHARFF_INCOMING_LOG || defaults.incomingLog,
+  incomingErrorLog: process.env.SCHARFF_INCOMING_ERROR_LOG || defaults.incomingErrorLog
+});
+
+module.exports = { loadConfig, defaults };

package/constants/functions.js

@@ -1,10 +1,17 @@
 module.exports.removeBaseUrl = (url) => {
-    if (url) {
+    if (typeof url !== 'object') {
         const indexOfEnd = url.indexOf('/', 7);
         if (indexOfEnd === -1) {
             return url;
         } else {
             return url.slice(indexOfEnd, url.length);
         }
+    } else {
+        const indexOfEnd = url.url.indexOf('/', 7);
+        if (indexOfEnd === -1) {
+            return url.url;
+        } else {
+            return url.url.slice(indexOfEnd, url.url.length);
+        }
     }
 };

package/index.js

@@ -1,66 +1,160 @@
-const fetchIntercept = require('fetch-intercept');
-const fs = require('fs');
 const { removeBaseUrl } = require('./constants/functions');
+const fetchIntercept = require('fetch-intercept');
+const fs = require('fs').promises;
 const os = require('os');
+const { loadConfig } = require('./config/default');
 
-module.exports.unregister = fetchIntercept.register({
-  request: function (url, config) {
-    const interfaces = os.networkInterfaces();
-    let addresses = [];
-    let tempUrl = url;
-    for (let i in interfaces) {
-      for (var i2 in interfaces[i]) {
-        var address = interfaces[i][i2];
-        if (address.family === 'IPv4' && !address.internal) {
-          addresses.push(address.address);
-        }
+const config = loadConfig();
+const allowedConfigKeys = ['outgoingLog', 'outgoingErrorLog', 'incomingLog', 'incomingErrorLog'];
+
+const logFileMap = {
+  request: 'outgoingLog',
+  requestError: 'outgoingErrorLog',
+  response: 'incomingLog',
+  responseError: 'incomingErrorLog'
+};
+
+const logEvent = async (kind, payload) => {
+  const appendLogEntry = async (filePath, payload) => {
+    await fs.appendFile(filePath, JSON.stringify(payload) + '\n', 'utf8');
+  };
+  const configKey = logFileMap[kind];
+  if (!configKey || !config[configKey]) return;
+  await appendLogEntry(config[configKey], payload);
+};
+
+const getIpv4Addresses = () => {
+  const interfaces = os.networkInterfaces();
+  const addresses = [];
+
+  for (const iface in interfaces) {
+    for (const addr of interfaces[iface]) {
+      if (addr.family === 'IPv4' && !addr.internal) {
+        addresses.push(addr.address);
       }
     }
-    let tempReq = { url, ip: addresses[0] };
-    let date = new Date().toLocaleString();
-    tempReq.date = date;
-    tempUrl = removeBaseUrl(tempUrl);
-    if (tempUrl !== url) {
-      tempReq.originUrl = tempUrl;
+  }
+
+  return addresses;
+};
+
+const safeParseBody = (body) => {
+  if (!body) return undefined;
+  try {
+    return JSON.parse(body);
+  } catch (err) {
+    return body;
+  }
+};
+
+const updateConfig = (overrides = {}) => {
+  if (!overrides || typeof overrides !== 'object') return { ...config };
+
+  for (const key of allowedConfigKeys) {
+    const value = overrides[key];
+    if (typeof value === 'string' && value.trim()) {
+      config[key] = value.trim();
     }
-    if (config === undefined) {
-      tempReq.method = 'GET';
-    } else {
-      if (config) {
-        if (config.method) {
-          tempReq.method = config.method;
-        }
-        if (config.headers) {
-          tempReq.headers = config.headers;
-        }
-        if (config.body) {
-          tempReq.body = JSON.parse(config.body);
-        }
+  }
+
+  return { ...config };
+};
+
+const listen = fetchIntercept.register({
+  request: async function (url, config) {
+    try {
+      const addresses = getIpv4Addresses();
+
+      const tempReq = {
+        type: 'Outgoing_Request',
+        url,
+        ip: addresses[0],
+        date: {
+          date: new Date().toLocaleDateString(),
+          time: new Date().toLocaleTimeString()
+        },
+        method: config?.method || 'GET',
+        headers: config?.headers,
+        body: safeParseBody(config?.body)
+      };
+
+      const cleanUrl = removeBaseUrl(url);
+      if (cleanUrl !== url) {
+        tempReq.originUrl = cleanUrl;
       }
-    }
 
-    fs.open('./outgoingRequest.log', 'a', function (e, id) {
-      fs.write(id, JSON.stringify(tempReq) + "\n", null, 'utf8', function () {
-        fs.close(id, function () {
-        });
-      });
-    });
+      await logEvent('request', tempReq);
+    } catch (error) {
+      console.error('Request logging error:', error);
+    }
 
     return [url, config];
   },
 
-  // requestError: function (error) {
-  //   // Called when an error occurred during another 'request' interceptor call
-  //   return Promise.reject(error);
-  // },
+  requestError: async function (error) {
+    try {
+      const payload = {
+        type: 'Outgoing_Request_Error',
+        message: error?.message,
+        stack: error?.stack,
+        date: {
+          date: new Date().toLocaleDateString(),
+          time: new Date().toLocaleTimeString()
+        }
+      };
+      await logEvent('requestError', payload);
+    } catch (logError) {
+      console.error('Request error logging failed:', logError);
+    }
 
-  // response: function (response) {
-  //   // Modify the response object
-  //   return response;
-  // },
+    return Promise.reject(error);
+  },
+
+  response: async function (response) {
+    try {
+      const payload = {
+        type: 'Incoming_Response',
+        url: response?.url,
+        status: response?.status,
+        statusText: response?.statusText,
+        ok: response?.ok,
+        redirected: response?.redirected,
+        date: {
+          date: new Date().toLocaleDateString(),
+          time: new Date().toLocaleTimeString()
+        }
+      };
+
+      await logEvent('response', payload);
+    } catch (logError) {
+      console.error('Response logging error:', logError);
+    }
 
-  // responseError: function (error) {
-  //   // Handle an fetch error
-  //   return Promise.reject(error);
-  // }
+    return response;
+  },
+
+  responseError: async function (error) {
+    try {
+      const payload = {
+        type: 'Incoming_Response_Error',
+        message: error?.message,
+        stack: error?.stack,
+        date: {
+          date: new Date().toLocaleDateString(),
+          time: new Date().toLocaleTimeString()
+        }
+      };
+
+      await logEvent('responseError', payload);
+    } catch (logError) {
+      console.error('Response error logging failed:', logError);
+    }
+
+    return Promise.reject(error);
+  }
 });
+
+listen.updateConfig = updateConfig;
+listen.getConfig = () => ({ ...config });
+
+module.exports = listen;

package/package.json

@@ -1,8 +1,19 @@
 {
   "name": "scharff",
-  "version": "1.3.0",
-  "description": "Logger for outgoing requests",
+  "version": "2.0.0",
+  "description": "Logger for outgoing and incoming fetch requests",
   "main": "index.js",
+  "types": "types/index.d.ts",
+  "files": [
+    "index.js",
+    "constants",
+    "config",
+    "types",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
@@ -29,5 +40,9 @@
   "license": "ISC",
   "dependencies": {
     "fetch-intercept": "^2.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
   }
 }

package/types/index.d.ts

@@ -0,0 +1,15 @@
+export interface ScharffConfig {
+  outgoingLog: string;
+  outgoingErrorLog: string;
+  incomingLog: string;
+  incomingErrorLog: string;
+}
+
+declare function listen(): void;
+
+declare namespace listen {
+  function updateConfig(overrides?: Partial<ScharffConfig>): ScharffConfig;
+  function getConfig(): ScharffConfig;
+}
+
+export = listen;