cipher-logger 0.1.1 → 0.1.2

package/.agents/README.md

@@ -0,0 +1,103 @@
+---
+name: cipher-logger
+description: >
+  Guidance for correct usage of the `cipher-logger` package (npm: cipher-logger,
+  organization: cipherunits) — an HTTP logging library for Node.js used with Express
+  and Next.js. Activate this skill whenever a user wants request logging, error
+  logging, middleware logs, or basic observability added to an Express or Next.js
+  project (especially cipherunits projects like rayyan-backend, Mananegar, Setad
+  Mahalle, Fusion GUI), or when imports of "cipher-logger" or `createCipherLogger`
+  are detected in code. Also use this skill to review/debug code that uses
+  cipher-logger (for example, incorrect status/duration in Next.js middleware or
+  optional fields not being logged) — even if the user simply asks "set up a
+  logger" or "add request logging" without naming the package.
+---
+
+# Cipher Logger — Agent Skill
+
+This skill is the official reference for installing, configuring, and correctly
+using **cipher-logger** — a lightweight, production-ready HTTP logging library
+for Node.js (organization: `cipherunits`, repository: `github.com/cipherunits/CipherLogger`).
+Important: do not assume the API based on similarity to winston/pino/morgan — use
+the exact API documented here.
+
+## Golden Rule
+
+cipher-logger has three distinct parts that must not be mixed:
+
+1. **`Logger`** — the base application logger class (independent of HTTP). Use for
+  `logger.info/warn/error/debug`.
+2. **`createCipherLogger(config)`** — factory that creates the main instance,
+  configures optional fields and level, and exposes `.express()`, `.next()`, and
+  `.logRequest()`.
+3. **Framework adapters** (`cipher.express()` and `cipher.next()`) — ready-made
+  middleware; mount them rather than writing manual request logging.
+
+If the user only asks to "log requests", they usually need steps 2 and 3, not 1.
+
+## Installation
+
+```bash
+pnpm add cipher-logger
+# Framework packages are peer dependencies:
+pnpm add express   # if using Express
+pnpm add next      # if using Next.js
+```
+
+Node.js 18+ is required. Install only the peer dependency actually used by the
+project (e.g., `express` or `next`).
+
+## Quick Decision Map
+
+| Project type | What to mount/call |
+|---|---|
+| Express API (e.g. rayyan-backend if the backend is Node) | `cipher.express()` mounted before routes |
+| Next.js (e.g. Setad Mahalle, Mananegar) | `middleware.ts` using `cipher.next()` |
+| Manual non-HTTP event logging | `new Logger({...})` and `.info/.warn/.error/.debug` |
+| Manual request logging (e.g. inside a job/cron) | `cipher.logRequest(input)` |
+
+## Usage Steps (Summary)
+
+1. Create a logger with `createCipherLogger({ fields: {...}, level: "info", prefix: "..." })` —
+  enable only the fields the user actually needs; all optional fields default to `false`.
+2. For Express: mount `app.use(cipher.express())` **before** route definitions, otherwise
+  status/duration will be incorrect because the middleware must observe the request.
+3. For Next.js: use `cipher.next()` in `middleware.ts` (or `src/middleware.ts`) and
+  always restrict `config.matcher` to exclude static/image routes to avoid noisy logs.
+4. For more detailed guidance, read the related skill files below — only open the
+  section relevant to the user's request:
+  - `skills/fusion-references/SKILL.md` — configuration options and optional fields
+  - `skills/fusion-express-integration/SKILL.md` — Express integration and sample output
+  - `skills/fusion-nextjs-integration/SKILL.md` — Next.js middleware and the important
+    status/duration limitation
+  - `skills/fusion-log-schema/SKILL.md` — full log schema (required/optional fields)
+  - `skills/fusion-api-reference/SKILL.md` — function/class signatures and TypeScript exports
+  - `skills/fusion-architecture/SKILL.md` — internal package structure (for debugging/contrib)
+
+## Common Pitfalls (Follow these)
+
+- **Check peer dependencies**: If the project is Express but `express` is not installed
+  (or vice versa), a runtime error will occur. Check `package.json` before suggesting code.
+- **Default `level` is `"debug"`**, not `"info"` — in production `"info"` is usually
+  more appropriate; set it explicitly in config instead of relying on the package default.
+- **In Next.js middleware, `status` and `duration` reflect the middleware's execution, not
+  the final route response** (because middleware runs before route handlers). Remind the
+  user of this when they expect the actual response status — route-handler wrappers are
+  planned for future versions but are not available now.
+- **In Express the opposite is true**: `status` and `duration` are recorded after `res.finish`
+  and therefore reflect the real response — explain this difference when comparing adapters.
+- **Optional fields are off by default**; the user must explicitly enable `ip`, `userAgent`,
+  `query`, etc.
+- **This package is lightweight** — don't recommend adding heavy log frameworks like
+  winston/pino unless the user specifically asks; the package is intended to be minimal.
+- **Exclude static routes in Next.js matcher** (example: `/((?!_next/static|_next/image|favicon.ico).*)`) to
+  avoid excessive noisy logs.
+
+## Before Suggesting Code
+
+1. Check whether the project is Express or Next.js (via `package.json` or folder structure).
+2. If `middleware.ts` already exists, merge the new code instead of replacing it (it may
+  contain other middleware like auth or i18n).
+3. If the project is a monorepo (e.g. Mananegar), determine which workspace/app the
+  package should be installed into, not necessarily the monorepo root.
+

package/.agents/skills/fusion-api-reference/SKILL.md

@@ -0,0 +1,61 @@
+# API Reference
+
+## `createCipherLogger(config?)`
+
+instance اصلی cipher-logger را می‌سازد.
+
+```ts
+const cipher = createCipherLogger(config);
+```
+
+### Instance methods
+
+| Method                       | Description                              |
+| ----------------------------- | ---------------------------------------- |
+| `cipher.logRequest(input)`   | Manually log an HTTP request             |
+| `cipher.express()`           | Returns Express middleware               |
+| `cipher.next()`              | Returns Next.js middleware               |
+
+Use `cipher.logRequest(input)` when the request cannot be captured by standard
+middleware — for example inside a route handler when you need to log the actual
+response status (not the middleware's status), subject to the limitation described
+in `skills/fusion-nextjs-integration/SKILL.md`.
+
+## `Logger` — base application logger (non-HTTP)
+
+For regular application logs (server startup, non-HTTP errors, deprecation warnings)
+use `Logger` directly rather than `createCipherLogger`:
+
+```ts
+import { Logger } from "cipher-logger";
+
+const logger = new Logger({ level: "info", prefix: "app" });
+
+logger.info("Server started");
+logger.warn("Deprecated API used", { route: "/old" });
+logger.error("Unhandled error", { err: "..." });
+logger.debug("Debug info");
+```
+
+Each method (`info` / `warn` / `error` / `debug`) accepts a text message and an
+optional metadata object.
+
+## TypeScript Exports
+
+```ts
+import type {
+  CipherLogger,
+  CipherLoggerConfig,
+  RequestLog,
+  RequestLogInput,
+  OptionalRequestField,
+  LogLevel,
+  LoggerOptions,
+  ExpressMiddleware,
+  NextMiddleware,
+} from "cipher-logger";
+```
+
+If the user wants to write a type-safe wrapper or factory over this package
+(for example for Fusion GUI or a shared package in the Mananegar monorepo), use
+the provided types rather than redefining them manually.

package/.agents/skills/fusion-architecture/SKILL.md

@@ -0,0 +1,64 @@
+# Architecture Reference
+
+Only when the user needs to modify the CipherLogger package itself (not a project
+that uses it) — for example, bug fixes, adding a new optional field, or writing an
+adapter for another framework (like Fastify or Hono).
+
+## Folder structure
+
+```
+cipher-logger/
+├── src/
+│   ├── core/           # core — field configuration and log construction
+│   │   ├── logger.ts
+│   │   ├── types.ts
+│   │   ├── build-request-log.ts
+│   │   └── create-cipher-logger.ts
+│   ├── express/         # Express adapter
+│   │   └── middleware.ts
+│   ├── next/            # Next.js adapter
+│   │   └── middleware.ts
+│   └── index.ts          # public entry point
+```
+
+## Data flow
+
+```
+              Core
+   fields config → buildRequestLog
+              │
+    ┌─────────┴─────────┐
+    ▼                   ▼
+ Express             Next.js
+middleware           middleware
+```
+
+Both adapters (`express/middleware.ts` and `next/middleware.ts`) rely on the
+same `buildRequestLog` core — only the extraction of request/response fields from
+the framework differs. The difference in `status`/`duration` behavior between the
+two adapters stems from how each adapter calls the core, not from `buildRequestLog`
+itself.
+
+## Local development
+
+```bash
+git clone https://github.com/cipherunits/CipherLogger.git
+cd CipherLogger
+pnpm install
+pnpm run build
+```
+
+## Adding a new adapter (e.g. Fastify)
+
+Create a new file such as `src/fastify/middleware.ts` that calls the same
+`buildRequestLog` from `core/build-request-log.ts` and only differs in how fields
+are extracted from the framework — do not reimplement the log-construction logic
+inside the new adapter.
+
+## Contribution rules (from README)
+
+- Commits must follow [Conventional Commits](https://www.conventionalcommits.org/)
+- Run `pnpm run build` before opening a PR
+- Keep changes focused and small
+- Update README for any API changes
+- License: MIT © Cipher Unit

package/.agents/skills/fusion-express-integration/SKILL.md

@@ -0,0 +1,61 @@
+# Express Integration Reference
+
+## Installation and mount
+
+```ts
+import express from "express";
+import { createCipherLogger } from "cipher-logger";
+
+const app = express();
+
+const cipher = createCipherLogger({
+  fields: {
+    ip: true,
+    userAgent: true,
+    query: true,
+    requestId: true,
+  },
+  level: "info",
+  prefix: "express",
+});
+
+// Mount before defining routes
+app.use(cipher.express());
+
+app.get("/users", (req, res) => {
+  res.json({ users: [] });
+});
+
+app.listen(3000, () => {
+  console.log("Server running on http://localhost:3000");
+});
+```
+
+## Critical note: mount order
+
+`app.use(cipher.express())` must be called **before any route handlers** (it is
+usually fine to mount it after body-parser/CORS at the start of the chain) so the
+middleware can observe `res.finish`.
+
+## Sample real output
+
+```
+[2026-09-01T20:00:00.000Z] [INFO] [express] HTTP Request {
+  id: 'a1b2c3d4-...',
+  type: 'http',
+  timestamp: '2026-09-01T20:00:00.000Z',
+  method: 'GET',
+  path: '/users?page=1',
+  status: 200,
+  duration: 12,
+  ip: '::1',
+  userAgent: 'Mozilla/5.0 ...',
+  query: { page: '1' }
+}
+```
+
+## Why Express is more accurate than Next.js
+
+In Express, `status` and `duration` are recorded **after the `res.finish` event** —
+so they reflect the actual response sent to the client. Mention this when explaining
+the behavioral difference between adapters (see `skills/fusion-nextjs-integration/SKILL.md`).

package/.agents/skills/fusion-log-schema/SKILL.md

@@ -0,0 +1,34 @@
+# Log Schema Reference
+
+## Required fields (`required`) — always present in every HTTP log
+
+| Field       | Type     | Description                |
+| ----------- | -------- | --------------------------- |
+| `id`        | `string` | Unique identifier (UUID)    |
+| `type`      | `"http"` | Log type                   |
+| `timestamp` | `string` | ISO 8601 timestamp         |
+| `method`    | `string` | HTTP method                |
+| `path`      | `string` | Request path               |
+| `status`    | `number` | HTTP status code           |
+| `duration`  | `number` | Duration in milliseconds   |
+
+## Optional fields (`optional`) — enabled via `fields` in config
+
+| Field       | Type                        | Description                  |
+| ----------- | ---------------------------- | ---------------------------- |
+| `ip`        | `string`                    | Client IP address            |
+| `userAgent` | `string`                    | User-Agent header            |
+| `referer`   | `string`                    | Referer header               |
+| `protocol`  | `string`                    | `http` / `https`             |
+| `host`      | `string`                    | Host header                  |
+| `query`     | `Record<string, string>`    | Query string parameters      |
+| `requestId` | `string`                    | From the `x-request-id` header |
+| `metadata`  | `Record<string, unknown>`   | Arbitrary metadata           |
+
+See `skills/fusion-references/SKILL.md` for the full configuration details of these fields.
+
+## Note for log processing/ingestion (for example, when sending to a log pipeline)
+
+Each HTTP log is a flat object with `type: "http"` — if you need to distinguish
+between HTTP logs and manual logs (calls to `logger.info(...)` from the `Logger`
+class), check the `type` field; manual logs do not include `type: "http"`.

package/.agents/skills/fusion-nextjs-integration/SKILL.md

@@ -0,0 +1,81 @@
+# Next.js Integration Reference
+
+## Full approach — `middleware.ts` at project root (or `src/middleware.ts`)
+
+```ts
+import { createCipherLogger } from "cipher-logger";
+import type { NextRequest } from "next/server";
+
+const cipher = createCipherLogger({
+  fields: {
+    ip: true,
+    userAgent: true,
+    host: true,
+    query: true,
+  },
+  level: "info",
+});
+
+export function middleware(request: NextRequest) {
+  return cipher.next()(request);
+}
+
+export const config = {
+  matcher: [
+    // all paths except static and image files
+    "/((?!_next/static|_next/image|favicon.ico).*)",
+  ],
+};
+```
+
+## Short approach (when no other middleware exists in the project)
+
+```ts
+import { createCipherLogger } from "cipher-logger";
+
+const cipher = createCipherLogger({
+  fields: { ip: true, userAgent: true },
+});
+
+export default cipher.next();
+
+export const config = {
+  matcher: ["/api/:path*", "/dashboard/:path*"],
+};
+```
+
+⚠️ If the project already has `middleware.ts` (for example auth or i18n — like
+Mananegar/Setad Mahalle which are multilingual), do not use the short approach; instead
+merge the export function with the existing logic using the full method above, because
+only one default middleware export is allowed per Next.js project.
+
+## ⚠️ Important limitation — read before explaining status/duration to the user
+
+Next.js middleware runs **before** the route handler. Therefore:
+
+- `status` and `duration` recorded in the logs refer to the **middleware's execution**,
+  not the final response returned by the route handler.
+- If the user expects the actual API route status code (e.g. 404 or 500 from inside a
+  handler) to appear in this log, **that is not possible** with the current package.
+- According to the official package docs, a "route handler wrapper for more accurate
+  logging" is planned for future versions but is not available now — do not claim
+  such an API exists at present.
+- If the user needs accurate status/duration for a route, the current solution is to
+  manually call `cipher.logRequest(input)` inside the route handler or use the `Logger`
+  class (see `skills/fusion-api-reference/SKILL.md`), not the middleware.
+
+## Always restrict the matcher
+
+Without a restricted `matcher`, static requests (`_next/static`, `_next/image`,
+`favicon.ico`) will also be logged and produce a lot of noise. Official suggested
+pattern:
+
+```ts
+matcher: ["/((?!_next/static|_next/image|favicon.ico).*)"];
+```
+
+Or restrict to specific paths:
+
+```ts
+matcher: ["/api/:path*", "/dashboard/:path*"];
+```

package/.agents/skills/fusion-references/SKILL.md

@@ -0,0 +1,51 @@
+# Configuration Reference
+
+## `createCipherLogger(config?)`
+
+```ts
+import { createCipherLogger } from "cipher-logger";
+
+const cipher = createCipherLogger({
+  fields: {
+    ip: true,
+    userAgent: true,
+    referer: false,
+    protocol: true,
+    host: true,
+    query: true,
+    requestId: true,
+    metadata: false,
+  },
+  level: "info",
+  prefix: "api",
+});
+```
+
+## Options Table
+
+| Option   | Type                                              | Default      | Description                          |
+| -------- | -------------------------------------------------- | ------------ | ------------------------------------ |
+| `fields` | `Partial<Record<OptionalRequestField, boolean>>`   | all `false`  | Which optional fields to include in logs |
+| `level`  | `"debug" \| "info" \| "warn" \| "error"`  | `"debug"`   | Minimum log level                    |
+| `prefix` | `string`                                           | —            | Prefix used in console output        |
+> **Note:** The package default `level` is `"debug"`, which is often too verbose for
+production. If the user doesn't specify a level, explicitly set `"info"` in the
+config and document the reason rather than relying on the package default.
+
+## Optional fields (`fields`) — all default to `false`
+
+| Field       | Type                       | Description                    |
+| ----------- | -------------------------- | ------------------------------ |
+| `ip`        | `string`                   | Client IP address              |
+| `userAgent` | `string`                   | User-Agent header              |
+| `referer`   | `string`                   | Referer header                 |
+| `protocol`  | `string`                   | `http` or `https`             |
+| `host`      | `string`                   | Host header                    |
+| `query`     | `Record<string, string>`   | Query string parameters        |
+| `requestId` | `string`                   | From the `x-request-id` header |
+| `metadata`  | `Record<string, unknown>`  | Arbitrary metadata             |
+
+Enable only the fields the user truly needs; turning on everything can produce
+large logs and risk leaking sensitive data (for example IPs or query params that
+contain tokens). If query params may contain secrets (passwords, tokens), warn the
+user before enabling `query: true`.

package/README.md

@@ -383,16 +383,8 @@ Contributions are welcome and appreciated.
 
 ## License
 
-This project is licensed under the [BSD 3-Clause License](LICENSE).
-
-```
-Copyright (c) 2026, Cipher Logger
-```
-
-Free to use, modify, and distribute — provided the copyright notice and license terms are preserved. See [LICENSE](LICENSE) for full details.
-
----
+[MIT](./LICENSE) © Cipher Unit
 
 <p align="center">
-  Built with ❤️ by <a href="https://github.com/cipherunits">CipherUnits</a>
+  <i>Built by <a href="https://cipherunit.xyz">Cipher Unit</a></i>
 </p>

package/dist/index.js

@@ -151,7 +151,7 @@ function buildRequestLog(fields, input) {
   return log;
 }
 
-// src/express/middleware.ts
+// src/adapters/express/middleware.ts
 function parseQuery(query) {
   const result = {};
   for (const [key, value] of Object.entries(query)) {
@@ -191,7 +191,7 @@ function createExpressMiddleware(cipher) {
   };
 }
 
-// src/next/middleware.ts
+// src/adapters/next/middleware.ts
 var import_server = require("next/server");
 function getHeader2(request, name) {
   return request.headers.get(name) ?? void 0;

package/dist/index.mjs

@@ -121,7 +121,7 @@ function buildRequestLog(fields, input) {
   return log;
 }
 
-// src/express/middleware.ts
+// src/adapters/express/middleware.ts
 function parseQuery(query) {
   const result = {};
   for (const [key, value] of Object.entries(query)) {
@@ -161,7 +161,7 @@ function createExpressMiddleware(cipher) {
   };
 }
 
-// src/next/middleware.ts
+// src/adapters/next/middleware.ts
 import { NextResponse } from "next/server";
 function getHeader2(request, name) {
   return request.headers.get(name) ?? void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cipher-logger",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "See every request. Capture every error. Understand your application.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",