@planetmoondrop/logger-client 2.1.0

package/README.md

@@ -0,0 +1,85 @@
+# @planetmoondrop/logger-client
+
+Axios interceptor for frontend apps that connects them to the `@planetmoondrop/centralized-logger` trace chain.
+
+Reads the `x-loki-trace-id` response header from any API response and injects it back into every subsequent request — so your frontend sessions appear as a continuous trace in Grafana alongside the backend logs.
+
+## Installation
+
+```bash
+npm install @planetmoondrop/logger-client axios
+# or
+pnpm add @planetmoondrop/logger-client axios
+```
+
+## Basic usage
+
+```ts
+import axios from 'axios';
+import { attachSessionInterceptor } from '@planetmoondrop/logger-client';
+
+const api = axios.create({ baseURL: 'https://api.example.com' });
+
+// Attach once at app startup.
+// Returns both interceptor IDs so you can eject later if needed.
+const { requestId, responseId } = attachSessionInterceptor(api);
+```
+
+That's it. Every response that includes `x-loki-trace-id` stores the value, and every outgoing request includes it so the backend can correlate the call to an existing trace.
+
+## Options
+
+```ts
+const ids = attachSessionInterceptor(api, {
+  // Response header to read the trace ID from
+  responseHeader: 'x-loki-trace-id', // default
+
+  // Request header to inject the trace ID into
+  requestHeader: 'x-loki-trace-id', // default
+
+  // Key used to store the trace ID in the storage backend
+  storageKey: 'sessionId', // default
+
+  // Custom storage — defaults to MemoryStorage (in-process Map).
+  // Provide any object that implements { getItem, setItem }.
+  storage: myStorage,
+});
+```
+
+## Custom storage
+
+The default `MemoryStorage` keeps the trace ID in a `Map` — it works fine for a single-page session but clears on page reload. Provide your own storage to persist across reloads:
+
+```ts
+import { attachSessionInterceptor, SessionStorage } from '@planetmoondrop/logger-client';
+
+// Browser localStorage
+const webStorage: SessionStorage = {
+  getItem: (key) => localStorage.getItem(key),
+  setItem: (key, value) => localStorage.setItem(key, value),
+};
+
+attachSessionInterceptor(api, { storage: webStorage });
+```
+
+```ts
+// React Native — AsyncStorage (async storage is fully supported)
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+attachSessionInterceptor(api, {
+  storage: {
+    getItem: (key) => AsyncStorage.getItem(key),
+    setItem: (key, value) => AsyncStorage.setItem(key, value),
+  },
+});
+```
+
+## Ejecting
+
+```ts
+const { requestId, responseId } = attachSessionInterceptor(api);
+
+// Remove both interceptors (e.g. on logout)
+api.interceptors.request.eject(requestId);
+api.interceptors.response.eject(responseId);
+```

package/dist/index.d.ts

@@ -0,0 +1,37 @@
+import type { AxiosInstance } from 'axios';
+import { SessionInterceptorOptions, SessionStorage } from './types';
+import { MemoryStorage, BrowserSessionStorage, BrowserLocalStorage } from './storage';
+export { MemoryStorage, BrowserSessionStorage, BrowserLocalStorage };
+export type { SessionInterceptorOptions, SessionStorage };
+/**
+ * IDs returned by `attachSessionInterceptor`, one per Axios interceptor slot.
+ * Pass them to `axiosInstance.interceptors.request.eject(requestId)` /
+ * `axiosInstance.interceptors.response.eject(responseId)` to detach.
+ */
+export interface SessionInterceptorIds {
+    /** ID of the request interceptor that injects the trace header. */
+    requestId: number;
+    /** ID of the response interceptor that captures the trace header. */
+    responseId: number;
+}
+/**
+ * Attaches request + response interceptors to the given Axios instance so that:
+ *
+ * - **Every response**: if the server returns `responseHeader`, the value is
+ *   written into `storage` under `storageKey`.
+ * - **Every request**: if `storage` contains a value for `storageKey`, it is
+ *   added to the request under `requestHeader`.
+ *
+ * Because MemoryStorage is cleared on page refresh, pass a `BrowserSessionStorage`
+ * or `BrowserLocalStorage` for production use so the trace context survives
+ * in-app navigations and full reloads.
+ *
+ * If `initialSessionId` is supplied (or auto-generated via `generateInitialId`),
+ * it is written to storage immediately so the **very first** outgoing request
+ * already carries a trace ID instead of waiting for the first response.
+ *
+ * @param axiosInstance - The Axios instance to instrument.
+ * @param options - Configuration options.
+ * @returns `{ requestId, responseId }` — Axios interceptor IDs for ejection.
+ */
+export declare function attachSessionInterceptor(axiosInstance: AxiosInstance, options?: SessionInterceptorOptions): SessionInterceptorIds;

package/dist/index.js

@@ -0,0 +1,117 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserLocalStorage = exports.BrowserSessionStorage = exports.MemoryStorage = void 0;
+exports.attachSessionInterceptor = attachSessionInterceptor;
+const storage_1 = require("./storage");
+Object.defineProperty(exports, "MemoryStorage", { enumerable: true, get: function () { return storage_1.MemoryStorage; } });
+Object.defineProperty(exports, "BrowserSessionStorage", { enumerable: true, get: function () { return storage_1.BrowserSessionStorage; } });
+Object.defineProperty(exports, "BrowserLocalStorage", { enumerable: true, get: function () { return storage_1.BrowserLocalStorage; } });
+/**
+ * Attaches request + response interceptors to the given Axios instance so that:
+ *
+ * - **Every response**: if the server returns `responseHeader`, the value is
+ *   written into `storage` under `storageKey`.
+ * - **Every request**: if `storage` contains a value for `storageKey`, it is
+ *   added to the request under `requestHeader`.
+ *
+ * Because MemoryStorage is cleared on page refresh, pass a `BrowserSessionStorage`
+ * or `BrowserLocalStorage` for production use so the trace context survives
+ * in-app navigations and full reloads.
+ *
+ * If `initialSessionId` is supplied (or auto-generated via `generateInitialId`),
+ * it is written to storage immediately so the **very first** outgoing request
+ * already carries a trace ID instead of waiting for the first response.
+ *
+ * @param axiosInstance - The Axios instance to instrument.
+ * @param options - Configuration options.
+ * @returns `{ requestId, responseId }` — Axios interceptor IDs for ejection.
+ */
+function attachSessionInterceptor(axiosInstance, options = {}) {
+    const { responseHeader = 'x-loki-trace-id', requestHeader = 'x-loki-trace-id', storageKey = 'lokiTraceId', storage = new storage_1.MemoryStorage(), initialSessionId, generateInitialId = false, } = options;
+    // Seed storage so the first outgoing request already has a trace ID.
+    // IMPORTANT: only write if nothing is already stored — this ensures a page
+    // refresh within the same tab continues the same trace rather than resetting it.
+    // Priority: explicitly passed ID > auto-generated > nothing
+    void (() => __awaiter(this, void 0, void 0, function* () {
+        try {
+            const existing = yield storage.getItem(storageKey);
+            if (!existing) {
+                if (initialSessionId) {
+                    yield storage.setItem(storageKey, initialSessionId);
+                }
+                else if (generateInitialId) {
+                    yield storage.setItem(storageKey, generateHexId(32));
+                }
+            }
+        }
+        catch (_a) {
+            /* Silently ignore — storage errors must never break the app */
+        }
+    }))();
+    // Request interceptor: inject stored trace ID into outgoing headers
+    const requestId = axiosInstance.interceptors.request.use((config) => __awaiter(this, void 0, void 0, function* () {
+        try {
+            const traceId = yield storage.getItem(storageKey);
+            if (traceId) {
+                config.headers[requestHeader] = traceId;
+            }
+        }
+        catch (err) {
+            console.warn('[moondrop-logger-client] Failed to read trace ID:', err);
+        }
+        return config;
+    }), (error) => Promise.reject(error));
+    // Response interceptor: capture trace ID from response headers
+    const responseId = axiosInstance.interceptors.response.use((response) => __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const traceId = (_a = response.headers) === null || _a === void 0 ? void 0 : _a[responseHeader.toLowerCase()];
+        if (traceId && typeof traceId === 'string') {
+            try {
+                yield storage.setItem(storageKey, traceId);
+            }
+            catch (err) {
+                console.warn('[moondrop-logger-client] Failed to save trace ID:', err);
+            }
+        }
+        return response;
+    }), (error) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        // Still attempt to capture the trace ID from error responses (4xx / 5xx)
+        const traceId = (_b = (_a = error === null || error === void 0 ? void 0 : error.response) === null || _a === void 0 ? void 0 : _a.headers) === null || _b === void 0 ? void 0 : _b[responseHeader.toLowerCase()];
+        if (traceId && typeof traceId === 'string') {
+            try {
+                yield storage.setItem(storageKey, traceId);
+            }
+            catch (_c) {
+                /* ignore */
+            }
+        }
+        return Promise.reject(error);
+    }));
+    return { requestId, responseId };
+}
+/** Generates a random lowercase hex string of the requested character length. */
+function generateHexId(length) {
+    const bytes = new Uint8Array(Math.ceil(length / 2));
+    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+        crypto.getRandomValues(bytes);
+    }
+    else {
+        // Node.js fallback (for SSR edge cases / tests)
+        for (let i = 0; i < bytes.length; i++) {
+            bytes[i] = Math.floor(Math.random() * 256);
+        }
+    }
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, '0'))
+        .join('')
+        .slice(0, length);
+}

package/dist/storage.d.ts

@@ -0,0 +1,30 @@
+import { SessionStorage } from './types';
+/**
+ * In-memory storage (default).
+ * Data is lost when the page is refreshed — use BrowserSessionStorage or
+ * BrowserLocalStorage for persistence across navigations.
+ */
+export declare class MemoryStorage implements SessionStorage {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * sessionStorage-backed storage.
+ * Data persists for the lifetime of the browser tab/session and survives
+ * in-app navigations (Next.js route changes, React Router, etc.).
+ * A new tab or page refresh after the session ends starts fresh.
+ */
+export declare class BrowserSessionStorage implements SessionStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * localStorage-backed storage.
+ * Data persists across page refreshes and across tabs for the same origin.
+ * Use when you want to correlate a user's activity across multiple visits.
+ */
+export declare class BrowserLocalStorage implements SessionStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}

package/dist/storage.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrowserLocalStorage = exports.BrowserSessionStorage = exports.MemoryStorage = void 0;
+/**
+ * In-memory storage (default).
+ * Data is lost when the page is refreshed — use BrowserSessionStorage or
+ * BrowserLocalStorage for persistence across navigations.
+ */
+class MemoryStorage {
+    constructor() {
+        this.store = new Map();
+    }
+    getItem(key) {
+        var _a;
+        return (_a = this.store.get(key)) !== null && _a !== void 0 ? _a : null;
+    }
+    setItem(key, value) {
+        this.store.set(key, value);
+    }
+}
+exports.MemoryStorage = MemoryStorage;
+/**
+ * sessionStorage-backed storage.
+ * Data persists for the lifetime of the browser tab/session and survives
+ * in-app navigations (Next.js route changes, React Router, etc.).
+ * A new tab or page refresh after the session ends starts fresh.
+ */
+class BrowserSessionStorage {
+    getItem(key) {
+        if (typeof window === 'undefined')
+            return null;
+        try {
+            return window.sessionStorage.getItem(key);
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    setItem(key, value) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            window.sessionStorage.setItem(key, value);
+        }
+        catch (_a) {
+            /* Silently ignore quota errors */
+        }
+    }
+}
+exports.BrowserSessionStorage = BrowserSessionStorage;
+/**
+ * localStorage-backed storage.
+ * Data persists across page refreshes and across tabs for the same origin.
+ * Use when you want to correlate a user's activity across multiple visits.
+ */
+class BrowserLocalStorage {
+    getItem(key) {
+        if (typeof window === 'undefined')
+            return null;
+        try {
+            return window.localStorage.getItem(key);
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    setItem(key, value) {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            window.localStorage.setItem(key, value);
+        }
+        catch (_a) {
+            /* Silently ignore quota errors */
+        }
+    }
+}
+exports.BrowserLocalStorage = BrowserLocalStorage;

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Storage interface for saving/loading the trace session ID.
+ * Both synchronous and async implementations are accepted.
+ */
+export interface SessionStorage {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+}
+/**
+ * Options for `attachSessionInterceptor`.
+ */
+export interface SessionInterceptorOptions {
+    /**
+     * Name of the response header to read the trace ID from.
+     * @default 'x-loki-trace-id'
+     */
+    responseHeader?: string;
+    /**
+     * Name of the request header to send the trace ID in.
+     * @default 'x-loki-trace-id'
+     */
+    requestHeader?: string;
+    /**
+     * Key used to store the trace ID in the storage backend.
+     * @default 'lokiTraceId'
+     */
+    storageKey?: string;
+    /**
+     * Storage backend.
+     * - `MemoryStorage` (default): ephemeral, cleared on page refresh.
+     * - `BrowserSessionStorage`: survives in-app navigation and reloads within the same tab.
+     * - `BrowserLocalStorage`: persists across tabs and full page refreshes.
+     */
+    storage?: SessionStorage;
+    /**
+     * An explicit session / trace ID to seed into storage immediately on setup.
+     * This ensures the **first outgoing request** already carries a trace ID.
+     * Takes precedence over `generateInitialId`.
+     */
+    initialSessionId?: string;
+    /**
+     * When `true`, a random 32-char hex trace ID is auto-generated and seeded
+     * into storage on setup so the first request is already correlated.
+     * Ignored if `initialSessionId` is provided.
+     * @default false
+     */
+    generateInitialId?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@planetmoondrop/logger-client",
+  "version": "2.1.0",
+  "description": "Axios interceptor to manage x-loki-trace-id header",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "axios",
+    "interceptor",
+    "trace",
+    "trace-id",
+    "traceId",
+    "x-loki-trace-id",
+    "planetmoondrop interceptor",
+    "axios interceptor",
+    "planetmoondrop",
+    "logger-client",
+    "logger",
+    "observability",
+    "distributed-tracing",
+    "microservices",
+    "nestjs",
+    "nestjs-logger",
+    "nestjs-logger-client",
+    "nestjs-logger-client-axios",
+    "nestjs-logger-client-axios-interceptor",
+    "nestjs-logger-client-axios-interceptor-loki",
+    "nestjs-logger-client-axios-interceptor-loki-trace-id",
+    "nestjs-logger-client-axios-interceptor-loki-trace-id-header",
+    "nestjs-logger-client-axios-interceptor-loki-trace-id-header-x-loki-trace-id",
+    "nestjs-logger-client-axios-interceptor-loki-trace-id-header-x-loki-trace-id"
+  ],
+  "author": "Planetmoondrop",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "axios": ">=0.21.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "axios": "^1.6.0",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc"
+  }
+}