pinqloq 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to the `pinqloq` npm package are documented here. This package follows
+[Semantic Versioning](https://semver.org). Its version numbers are independent of the .NET
+`pinqloq` NuGet package (`sdk/ClientLogs.Client/`) — the two ship on separate cadences for the
+same platform, and mirror each other's feature set rather than their version numbers.
+
+## 1.1.0 — 2026-09-08
+
+**Added:**
+
+- `PinqloqLogEntry.path` — a fixed, indexed field for the request path, matching the .NET SDK's
+  4.3.0 wire contract change ([pinqponq/pinqloq#108](https://github.com/pinqponq/pinqloq/issues/108)).
+  The request-logging middleware fills it automatically; on a manual `enqueue` it stays unset
+  unless set explicitly.
+
+**Changed:**
+
+- `event` and `path` are no longer duplicated into `metadata`. The request-logging middleware
+  used to also write `metadata.event`, `metadata.path`, and `metadata.RequestPath` — those keys
+  are gone from newly-sent logs now that `event` and `path` travel as their own fixed, indexed
+  fields. A `metadata: { event: ... }` enricher still overrides the event title; it just no
+  longer leaves a copy behind in `metadata`.
+
+If you built a saved filter or dashboard on `metadata.event`, `metadata.path`, or
+`metadata.RequestPath`, switch it to the `Event` / `Path` fields directly. No other consumer
+action is needed — existing code compiles unchanged.
+
+## 1.0.0 — 2026-09-04
+
+**Added:**
+
+- Initial release: feature parity with the .NET SDK's core surface.
+- `createPinqloq(options)` — buffered, batched manual structured logging (`logger.enqueue` /
+  `logger.enqueueMany`), delivered to the same `/bulk` ingest endpoint the .NET SDK uses.
+- `client.requestLogging(options)` — Express middleware for automatic HTTP request/response
+  logging: captures method/path/status/duration, request/response bodies (32KB cap) and headers,
+  resolves `deviceIdentifier` (selector → `device-identifier` header → global fallback, HTTP 400
+  if none resolve) and `correlationId` (`correlation-id` header → generated id).
+- Redaction: a built-in, unconditional credential-name floor (password, token, Authorization,
+  ...) plus `redactFields` (name-based, any nesting depth) and `redactPaths` (whole-body/header
+  masking, the `[PinqloqRedactEndpoint]` equivalent). Fails closed on a sensitive body that can't
+  be parsed as JSON, matching the .NET SDK's behavior.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pinqponq
+
+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,172 @@
+# Pinqloq (Node.js / Express)
+
+[![npm](https://img.shields.io/npm/v/pinqloq)](https://www.npmjs.com/package/pinqloq)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Pinqloq is a structured logging and log shipping SDK for centralized application logs. It
+captures HTTP request/response logs through Express middleware and sends manual application
+events to the Pinqloq log management platform using in-memory buffering, batching, and HTTPS
+delivery. This is the Node.js counterpart of the [.NET `pinqloq` SDK](https://www.nuget.org/packages/pinqloq) —
+same platform, same wire protocol, idiomatic API on each side.
+
+## Features
+
+- Automatic Express request/response logging
+- Correlation id read from the caller's header, falling back to a generated request id
+- Name-based redaction of sensitive fields, headers, and whole endpoints
+- Manual structured application events
+- Buffered and batched HTTPS delivery
+- Graceful shutdown flush
+
+## Requirements
+
+- Node.js 18 or later
+- Express 4 or 5
+- A Pinqloq project and secret key
+
+## Installation
+
+```bash
+npm install pinqloq
+```
+
+## Quick Start
+
+Store your secret key in an environment variable or a secret manager. Do not hardcode production
+credentials.
+
+```ts
+import express from "express";
+import { createPinqloq } from "pinqloq";
+
+const pinqloq = createPinqloq({
+  secretKey: process.env.PINQLOQ_SECRET_KEY!,
+  apiLogsCollectionName: "myapp_api_logs",
+  deviceIdentifier: "myapp-instance-1"
+});
+
+const app = express();
+app.use(express.json());
+
+// Mount AFTER body-parsing middleware so req.body is populated when the log is captured.
+app.use(
+  pinqloq.requestLogging({
+    excludePaths: ["/health"]
+  })
+);
+
+app.listen(3000);
+
+process.on("SIGTERM", async () => {
+  await pinqloq.shutdown();
+  process.exit(0);
+});
+```
+
+The middleware captures the HTTP method, path, and status code as searchable metadata. The
+request body, response body, request headers, and response headers go to the log detail as
+`InputJson`, `OutputJson`, `RequestHeaders`, and `ResponseHeaders`. Bodies are truncated at 32 KB.
+
+## Manual Logging
+
+Use `pinqloq.logger` to send structured application events:
+
+```ts
+pinqloq.logger.enqueue({
+  event: "order.created",
+  deviceIdentifier: order.customerId,
+  logLevel: PinqloqLogLevel.Information,
+  logSourceType: PinqloqLogSourceType.Backend,
+  metadata: { orderId: order.id }
+});
+```
+
+`event` and `deviceIdentifier` are required on every entry. Leave `deviceIdentifier` unset on an
+entry to inherit the global `deviceIdentifier` option. `enqueue` throws if an entry has no
+`deviceIdentifier` and no global fallback is set — a missing required field fails loudly rather
+than being silently dropped.
+
+## Add Request Metadata
+
+By default the middleware reads the required `deviceIdentifier` from the `device-identifier`
+request header automatically. Override how it is resolved with `resolveDeviceIdentifier`; the
+override wins, and if it returns undefined/blank the middleware falls back to the
+`device-identifier` header, then to the global `deviceIdentifier` option. If none of these resolve
+a value, the middleware rejects the request with **HTTP 400** before it runs.
+
+```ts
+app.use(
+  pinqloq.requestLogging({
+    excludePaths: ["/health"],
+    resolveDeviceIdentifier: (req) => req.user?.id,
+    resolveAppVersionName: (req) => req.header("x-app-version"),
+    metadata: {
+      userId: (req) => req.user?.id
+    }
+  })
+);
+```
+
+Use `metadata` for searchable values such as user and tenant IDs. Use `detail` for additional
+drill-down information. The `event` key (the panel title) defaults to `"{method} {path}"` and can
+be overridden via `metadata.event`.
+
+## Correlation ID
+
+Every log carries a `correlationId` that ties together the records of a single request or flow.
+The request-logging middleware fills it with no configuration: the caller's `correlation-id`
+request header when present, otherwise a generated id.
+
+```ts
+pinqloq.logger.enqueue({
+  event: "order.created",
+  deviceIdentifier: order.customerId,
+  correlationId: currentCorrelationId
+});
+```
+
+## Redacting Sensitive Values
+
+Request and response bodies and headers may contain credentials, tokens, or personal information.
+Unlike the .NET SDK's attribute-based redaction (which relies on C# reflection over typed DTOs —
+not available at runtime in TypeScript/Express), this SDK redacts by **name**:
+
+- `redactFields` — case-insensitive field/header names masked with `*****REDACTED*****` wherever
+  they appear in a captured body or header, at any nesting depth.
+- `redactPaths` — path prefixes (matched the same way as `excludePaths`) where every value in
+  `InputJson`, `OutputJson`, `RequestHeaders`, and `ResponseHeaders` is masked, keeping the JSON
+  structure and header names intact — the equivalent of the .NET SDK's `[PinqloqRedactEndpoint]`.
+
+```ts
+app.use(
+  pinqloq.requestLogging({
+    redactFields: ["ssnLastFour"],
+    redactPaths: ["/payment"]
+  })
+);
+```
+
+A built-in, unconditional floor of common credential names (password, token, `Authorization`,
+card numbers, ...) is always masked, even with no configuration — see
+[`src/redaction/plan.ts`](src/redaction/plan.ts) for the full list.
+
+## Security and Reliability
+
+Logs are buffered in memory and sent in batches. Buffered logs may be lost if the process is
+terminated without a graceful shutdown — call `pinqloq.shutdown()` on `SIGTERM`/`SIGINT`.
+
+Delivery failures are reported through `onFailed` callbacks and, even without callbacks, as
+throttled `console.error`/`console.warn` output — never silently discarded, but also never
+blocking. If your secret key is authorized for more than one collection, set
+`apiLogsCollectionName` (or a per-entry `collectionName`); otherwise the batch is rejected.
+
+## Documentation
+
+- [.NET SDK](https://www.nuget.org/packages/pinqloq) — the reference implementation for this
+  platform's wire protocol and feature set.
+- [Ruby SDK](https://rubygems.org/gems/pinqloq), [Go SDK](https://pkg.go.dev/github.com/pinqponq/pinqloq-go-sdk) — the other implementations.
+- [Full documentation](https://pinqloq.pinqponq.io/documentation.html)
+
+## License
+
+MIT