# scharff

> Logger for outgoing and incoming fetch requests

Latest version **2.0.0** (published 2025-12-22) · ISC license · 0 weekly downloads

## Install

```sh
npm install scharff
pnpm add scharff
yarn add scharff
bun add scharff
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2025-12-22 |
| First published | 2023-08-21 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=18 |
| Dependencies | 1 |
| Unpacked size | 10.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Michael Scharff |
| Maintainers | minka1902 |
| Keywords | logger, outgoing, request, response, error, fetch, fetch-inspector, inspector, scharff, npm |

## Links

- npm: https://www.npmjs.com/package/scharff
- Repository: https://github.com/Minka1902/scharff
- Homepage: https://github.com/Minka1902/scharff#readme
- Issues: https://github.com/Minka1902/scharff/issues
- npm.io page: https://npm.io/package/scharff

## Dependencies (1)

- [fetch-intercept](https://npm.io/package/fetch-intercept.md) ^2.4.0

## Alternatives

- [@sentry/react-native](https://npm.io/package/@sentry/react-native.md) — 2.6M weekly downloads
- [@ardatan/aggregate-error](https://npm.io/package/@ardatan/aggregate-error.md) — 708.1K weekly downloads
- [custom-error-generator](https://npm.io/package/custom-error-generator.md) — 2.0K weekly downloads
- [@technik-sde/prosemirror-recreate-transform](https://npm.io/package/@technik-sde/prosemirror-recreate-transform.md) — 1.5K weekly downloads
- [@suchipi/error-utils](https://npm.io/package/@suchipi/error-utils.md) — 78 weekly downloads

## Recent versions

- 2.0.0 (latest) — 2025-12-22
- 1.0.5 — 2024-12-22
- 1.0.4 — 2023-08-30
- 1.3.0 — 2023-08-22
- 1.1.0 — 2023-08-22
- 1.0.0 — 2023-08-21

## README

# 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
```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
```

## 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`

Tip: Logs are newline‑delimited JSON (NDJSON). Use tools like `jq`, `ripgrep`, or `grep` to filter and analyze.

---
_Source: https://npm.io/package/scharff · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._