@cedvict/http-guardian-plugin-logger 0.0.1-next.10

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1-next.7
+
+- Initial prerelease.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cedvict
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @cedvict/http-guardian-plugin-logger
+
+Logger plugin for http-guardian. Adds a guard that logs request / response /
+error events to a `LoggerSink` (defaults to `console`).
+
+## Usage
+
+```ts
+import { loggerPlugin } from "@cedvict/http-guardian-plugin-logger";
+import { createHttpClient, createApiParserStructured, bearerAuth } from "@cedvict/http-guardian";
+
+const api = createHttpClient({
+  baseUrl: "https://api.example.com",
+  auth: bearerAuth(() => token),
+  parser: createApiParserStructured(),
+  plugins: [loggerPlugin({ label: "api" })],
+});
+```
+
+Custom sink (e.g. pino, winston, browser-side ring buffer):
+
+```ts
+loggerPlugin({
+  sink: {
+    log: (label, payload) => myStructuredLogger.info({ label, ...payload }),
+    error: (label, payload) => myStructuredLogger.error({ label, ...payload }),
+  },
+});
+```
+
+## Combining with `correlationIdGuard`
+
+When [`correlationIdGuard`](../http-guardian) is active, the resolved
+`correlationId` lives on `ctx.meta.correlationId`. Surface it in your structured
+logs by writing a small wrapper guard that reads `ctx.meta` and forwards
+the field:
+
+```ts
+import { correlationIdGuard, type Guard } from "@cedvict/http-guardian";
+
+const correlationLog: Guard = async (ctx, next) => {
+  const res = await next(ctx);
+  myStructuredLogger.info({
+    method: ctx.method,
+    url: ctx.url,
+    status: res.status,
+    correlation_id: ctx.meta?.correlationId,
+    trace_id: ctx.meta?.traceId,
+  });
+  return res;
+};
+
+createHttpClient({
+  // ...
+  guards: [correlationIdGuard(), correlationLog],
+  plugins: [loggerPlugin()],
+});
+```
+
+This pattern keeps `loggerPlugin` framework-agnostic while letting you ship the
+correlation/trace fields straight into your structured-log pipeline (Datadog,
+Loki, ELK, etc.).

package/dist/index.cjs

@@ -0,0 +1,52 @@
+'use strict';
+
+// src/index.ts
+function toSafeUrl(u) {
+  return typeof u === "string" ? u : String(u);
+}
+function createLoggerGuard(sink, label) {
+  return async (ctx, next) => {
+    const t0 = Date.now();
+    try {
+      sink.log(label, {
+        event: "request",
+        method: ctx.method,
+        url: toSafeUrl(ctx.url)
+      });
+      const res = await next(ctx);
+      sink.log(label, {
+        event: "response",
+        method: ctx.method,
+        url: toSafeUrl(ctx.url),
+        status: res.status,
+        ms: Date.now() - t0
+      });
+      return res;
+    } catch (err) {
+      (sink.error ?? sink.log)(label, {
+        event: "error",
+        method: ctx.method,
+        url: toSafeUrl(ctx.url),
+        ms: Date.now() - t0,
+        error: err
+      });
+      throw err;
+    }
+  };
+}
+function loggerPlugin(opts = {}) {
+  const sink = opts.sink ?? console;
+  const label = opts.label ?? "http-guardian";
+  return {
+    name: "logger",
+    apply(options) {
+      options.guards ??= [];
+      options.guards.push(createLoggerGuard(sink, label));
+      return options;
+    }
+  };
+}
+
+exports.loggerPlugin = loggerPlugin;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";;;AAeA,SAAS,UAAU,CAAA,EAAyB;AAG1C,EAAA,OAAO,OAAO,CAAA,KAAM,QAAA,GAAW,CAAA,GAAI,OAAO,CAAC,CAAA;AAC7C;AAEA,SAAS,iBAAA,CAAkB,MAAkB,KAAA,EAAsB;AACjE,EAAA,OAAO,OAAO,KAAK,IAAA,KAAS;AAC1B,IAAA,MAAM,EAAA,GAAK,KAAK,GAAA,EAAI;AACpB,IAAA,IAAI;AACF,MAAA,IAAA,CAAK,IAAI,KAAA,EAAO;AAAA,QACd,KAAA,EAAO,SAAA;AAAA,QACP,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,GAAA,EAAK,SAAA,CAAU,GAAA,CAAI,GAAG;AAAA,OACvB,CAAA;AAED,MAAA,MAAM,GAAA,GAAM,MAAM,IAAA,CAAK,GAAG,CAAA;AAE1B,MAAA,IAAA,CAAK,IAAI,KAAA,EAAO;AAAA,QACd,KAAA,EAAO,UAAA;AAAA,QACP,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,GAAA,EAAK,SAAA,CAAU,GAAA,CAAI,GAAG,CAAA;AAAA,QACtB,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,EAAA,EAAI,IAAA,CAAK,GAAA,EAAI,GAAI;AAAA,OAClB,CAAA;AAED,MAAA,OAAO,GAAA;AAAA,IACT,SAAS,GAAA,EAAK;AACZ,MAAA,CAAC,IAAA,CAAK,KAAA,IAAS,IAAA,CAAK,GAAA,EAAK,KAAA,EAAO;AAAA,QAC9B,KAAA,EAAO,OAAA;AAAA,QACP,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,GAAA,EAAK,SAAA,CAAU,GAAA,CAAI,GAAG,CAAA;AAAA,QACtB,EAAA,EAAI,IAAA,CAAK,GAAA,EAAI,GAAI,EAAA;AAAA,QACjB,KAAA,EAAO;AAAA,OACR,CAAA;AACD,MAAA,MAAM,GAAA;AAAA,IACR;AAAA,EACF,CAAA;AACF;AAKO,SAAS,YAAA,CAAa,IAAA,GAA4B,EAAC,EAAe;AACvE,EAAA,MAAM,IAAA,GAAmB,KAAK,IAAA,IAAQ,OAAA;AACtC,EAAA,MAAM,KAAA,GAAQ,KAAK,KAAA,IAAS,eAAA;AAE5B,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,QAAA;AAAA,IACN,MAAM,OAAA,EAAS;AACb,MAAA,OAAA,CAAQ,WAAW,EAAC;AACpB,MAAA,OAAA,CAAQ,MAAA,CAAO,IAAA,CAAK,iBAAA,CAAkB,IAAA,EAAM,KAAK,CAAC,CAAA;AAClD,MAAA,OAAO,OAAA;AAAA,IACT;AAAA,GACF;AACF","file":"index.cjs","sourcesContent":["import type { Guard, HttpPlugin } from \"@cedvict/http-guardian\";\n\nexport type LoggerSink = {\n  log: (...args: any[]) => void;\n  warn?: (...args: any[]) => void;\n  error?: (...args: any[]) => void;\n};\n\nexport type LoggerPluginOptions = {\n  /** Where logs are written. Defaults to console. */\n  sink?: LoggerSink;\n  /** Optional tag/prefix to help identify logs. */\n  label?: string;\n};\n\nfunction toSafeUrl(u: string | URL): string {\n  // In http-guardian's internal context, `url` may be a string (already resolved)\n  // or a URL instance depending on the runtime/fetch implementation.\n  return typeof u === \"string\" ? u : String(u);\n}\n\nfunction createLoggerGuard(sink: LoggerSink, label: string): Guard {\n  return async (ctx, next) => {\n    const t0 = Date.now();\n    try {\n      sink.log(label, {\n        event: \"request\",\n        method: ctx.method,\n        url: toSafeUrl(ctx.url),\n      });\n\n      const res = await next(ctx);\n\n      sink.log(label, {\n        event: \"response\",\n        method: ctx.method,\n        url: toSafeUrl(ctx.url),\n        status: res.status,\n        ms: Date.now() - t0,\n      });\n\n      return res;\n    } catch (err) {\n      (sink.error ?? sink.log)(label, {\n        event: \"error\",\n        method: ctx.method,\n        url: toSafeUrl(ctx.url),\n        ms: Date.now() - t0,\n        error: err,\n      });\n      throw err;\n    }\n  };\n}\n\n/**\n * Production-friendly logging plugin: adds a guard that logs request/response.\n */\nexport function loggerPlugin(opts: LoggerPluginOptions = {}): HttpPlugin {\n  const sink: LoggerSink = opts.sink ?? console;\n  const label = opts.label ?? \"http-guardian\";\n\n  return {\n    name: \"logger\",\n    apply(options) {\n      options.guards ??= [];\n      options.guards.push(createLoggerGuard(sink, label));\n      return options;\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,19 @@
+import { HttpPlugin } from '@cedvict/http-guardian';
+
+type LoggerSink = {
+    log: (...args: any[]) => void;
+    warn?: (...args: any[]) => void;
+    error?: (...args: any[]) => void;
+};
+type LoggerPluginOptions = {
+    /** Where logs are written. Defaults to console. */
+    sink?: LoggerSink;
+    /** Optional tag/prefix to help identify logs. */
+    label?: string;
+};
+/**
+ * Production-friendly logging plugin: adds a guard that logs request/response.
+ */
+declare function loggerPlugin(opts?: LoggerPluginOptions): HttpPlugin;
+
+export { type LoggerPluginOptions, type LoggerSink, loggerPlugin };

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import { HttpPlugin } from '@cedvict/http-guardian';
+
+type LoggerSink = {
+    log: (...args: any[]) => void;
+    warn?: (...args: any[]) => void;
+    error?: (...args: any[]) => void;
+};
+type LoggerPluginOptions = {
+    /** Where logs are written. Defaults to console. */
+    sink?: LoggerSink;
+    /** Optional tag/prefix to help identify logs. */
+    label?: string;
+};
+/**
+ * Production-friendly logging plugin: adds a guard that logs request/response.
+ */
+declare function loggerPlugin(opts?: LoggerPluginOptions): HttpPlugin;
+
+export { type LoggerPluginOptions, type LoggerSink, loggerPlugin };

package/dist/index.js

@@ -0,0 +1,50 @@
+// src/index.ts
+function toSafeUrl(u) {
+  return typeof u === "string" ? u : String(u);
+}
+function createLoggerGuard(sink, label) {
+  return async (ctx, next) => {
+    const t0 = Date.now();
+    try {
+      sink.log(label, {
+        event: "request",
+        method: ctx.method,
+        url: toSafeUrl(ctx.url)
+      });
+      const res = await next(ctx);
+      sink.log(label, {
+        event: "response",
+        method: ctx.method,
+        url: toSafeUrl(ctx.url),
+        status: res.status,
+        ms: Date.now() - t0
+      });
+      return res;
+    } catch (err) {
+      (sink.error ?? sink.log)(label, {
+        event: "error",
+        method: ctx.method,
+        url: toSafeUrl(ctx.url),
+        ms: Date.now() - t0,
+        error: err
+      });
+      throw err;
+    }
+  };
+}
+function loggerPlugin(opts = {}) {
+  const sink = opts.sink ?? console;
+  const label = opts.label ?? "http-guardian";
+  return {
+    name: "logger",
+    apply(options) {
+      options.guards ??= [];
+      options.guards.push(createLoggerGuard(sink, label));
+      return options;
+    }
+  };
+}
+
+export { loggerPlugin };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AAeA,SAAS,UAAU,CAAA,EAAyB;AAG1C,EAAA,OAAO,OAAO,CAAA,KAAM,QAAA,GAAW,CAAA,GAAI,OAAO,CAAC,CAAA;AAC7C;AAEA,SAAS,iBAAA,CAAkB,MAAkB,KAAA,EAAsB;AACjE,EAAA,OAAO,OAAO,KAAK,IAAA,KAAS;AAC1B,IAAA,MAAM,EAAA,GAAK,KAAK,GAAA,EAAI;AACpB,IAAA,IAAI;AACF,MAAA,IAAA,CAAK,IAAI,KAAA,EAAO;AAAA,QACd,KAAA,EAAO,SAAA;AAAA,QACP,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,GAAA,EAAK,SAAA,CAAU,GAAA,CAAI,GAAG;AAAA,OACvB,CAAA;AAED,MAAA,MAAM,GAAA,GAAM,MAAM,IAAA,CAAK,GAAG,CAAA;AAE1B,MAAA,IAAA,CAAK,IAAI,KAAA,EAAO;AAAA,QACd,KAAA,EAAO,UAAA;AAAA,QACP,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,GAAA,EAAK,SAAA,CAAU,GAAA,CAAI,GAAG,CAAA;AAAA,QACtB,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,EAAA,EAAI,IAAA,CAAK,GAAA,EAAI,GAAI;AAAA,OAClB,CAAA;AAED,MAAA,OAAO,GAAA;AAAA,IACT,SAAS,GAAA,EAAK;AACZ,MAAA,CAAC,IAAA,CAAK,KAAA,IAAS,IAAA,CAAK,GAAA,EAAK,KAAA,EAAO;AAAA,QAC9B,KAAA,EAAO,OAAA;AAAA,QACP,QAAQ,GAAA,CAAI,MAAA;AAAA,QACZ,GAAA,EAAK,SAAA,CAAU,GAAA,CAAI,GAAG,CAAA;AAAA,QACtB,EAAA,EAAI,IAAA,CAAK,GAAA,EAAI,GAAI,EAAA;AAAA,QACjB,KAAA,EAAO;AAAA,OACR,CAAA;AACD,MAAA,MAAM,GAAA;AAAA,IACR;AAAA,EACF,CAAA;AACF;AAKO,SAAS,YAAA,CAAa,IAAA,GAA4B,EAAC,EAAe;AACvE,EAAA,MAAM,IAAA,GAAmB,KAAK,IAAA,IAAQ,OAAA;AACtC,EAAA,MAAM,KAAA,GAAQ,KAAK,KAAA,IAAS,eAAA;AAE5B,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,QAAA;AAAA,IACN,MAAM,OAAA,EAAS;AACb,MAAA,OAAA,CAAQ,WAAW,EAAC;AACpB,MAAA,OAAA,CAAQ,MAAA,CAAO,IAAA,CAAK,iBAAA,CAAkB,IAAA,EAAM,KAAK,CAAC,CAAA;AAClD,MAAA,OAAO,OAAA;AAAA,IACT;AAAA,GACF;AACF","file":"index.js","sourcesContent":["import type { Guard, HttpPlugin } from \"@cedvict/http-guardian\";\n\nexport type LoggerSink = {\n  log: (...args: any[]) => void;\n  warn?: (...args: any[]) => void;\n  error?: (...args: any[]) => void;\n};\n\nexport type LoggerPluginOptions = {\n  /** Where logs are written. Defaults to console. */\n  sink?: LoggerSink;\n  /** Optional tag/prefix to help identify logs. */\n  label?: string;\n};\n\nfunction toSafeUrl(u: string | URL): string {\n  // In http-guardian's internal context, `url` may be a string (already resolved)\n  // or a URL instance depending on the runtime/fetch implementation.\n  return typeof u === \"string\" ? u : String(u);\n}\n\nfunction createLoggerGuard(sink: LoggerSink, label: string): Guard {\n  return async (ctx, next) => {\n    const t0 = Date.now();\n    try {\n      sink.log(label, {\n        event: \"request\",\n        method: ctx.method,\n        url: toSafeUrl(ctx.url),\n      });\n\n      const res = await next(ctx);\n\n      sink.log(label, {\n        event: \"response\",\n        method: ctx.method,\n        url: toSafeUrl(ctx.url),\n        status: res.status,\n        ms: Date.now() - t0,\n      });\n\n      return res;\n    } catch (err) {\n      (sink.error ?? sink.log)(label, {\n        event: \"error\",\n        method: ctx.method,\n        url: toSafeUrl(ctx.url),\n        ms: Date.now() - t0,\n        error: err,\n      });\n      throw err;\n    }\n  };\n}\n\n/**\n * Production-friendly logging plugin: adds a guard that logs request/response.\n */\nexport function loggerPlugin(opts: LoggerPluginOptions = {}): HttpPlugin {\n  const sink: LoggerSink = opts.sink ?? console;\n  const label = opts.label ?? \"http-guardian\";\n\n  return {\n    name: \"logger\",\n    apply(options) {\n      options.guards ??= [];\n      options.guards.push(createLoggerGuard(sink, label));\n      return options;\n    },\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@cedvict/http-guardian-plugin-logger",
+  "version": "0.0.1-next.10",
+  "description": "Logger plugin for http-guardian.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.js",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cedvict/http-guardian.git"
+  },
+  "peerDependencies": {
+    "@cedvict/http-guardian": "^0.0.1-next.6"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "lint": "eslint . --max-warnings=0",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "prepublishOnly": "npm -w @cedvict/http-guardian run build && npm run test && npm run lint && npm run typecheck && npm run build",
+    "prebuild": "npm -w @cedvict/http-guardian run build",
+    "pretypecheck": "npm -w @cedvict/http-guardian run build"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.4.0",
+    "tsup": "^8.0.0",
+    "vitest": "^1.5.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0"
+  },
+  "dependencies": {
+    "@cedvict/http-guardian": "^0.0.1-next.10"
+  }
+}