@deployagram/logger-client 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,14 @@
+DEPLOYAGRAM PROPRIETARY LICENSE
+
+Copyright (c) 2025 Deployagram, Cookiebit and Andy Muir.
+
+Permission is hereby granted to use this software solely for its intended purpose.
+
+RESTRICTIONS:
+- No modification of the software is permitted
+- No reverse engineering, decompilation, or disassembly
+- No redistribution without explicit written permission
+- Source code remains proprietary and confidential
+- Usage is limited to the compiled npm package (the distributed tarball) artifact only
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @deployagram/logger-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A client for the Deployagram Collector (`living-http-logger`), built on Node's `fetch`. It is the
+Node.js equivalent of the Java `DiagramLoggerClient`.
+
+```bash
+npm install @deployagram/logger-client
+```
+
+```ts
+import { DiagramLoggerClient } from '@deployagram/logger-client';
+
+const logger = new DiagramLoggerClient({ baseUrl: 'http://localhost:1152' });
+
+await logger.log({
+  timestamp: new Date().toISOString(),
+  protocol: 'HTTP',
+  source: 'EmailClient',
+  target: 'Emailer',
+  message: 'POST /Emailer/email',
+  body: '{"email":"eddie@eddie.com"}',
+});
+
+const all = await logger.read();            // GET /log/read
+const marked = await logger.read('marker'); // GET /log/read/{id}
+await logger.markEnd('marker');             // POST /log/markEnd/{id}
+await logger.flushToCloud('Emailer', 'run-1'); // POST /run/markTestRunEnd/{container}/{run}
+```
+
+| Method | Collector endpoint |
+|---|---|
+| `log(log)` | `POST /log` |
+| `read()` | `GET /log/read` |
+| `read(id)` | `GET /log/read/{id}` |
+| `markEnd(id)` | `POST /log/markEnd/{id}` |
+| `flushToCloud(container, run)` | `POST /run/markTestRunEnd/{container}/{run}` |
+| `configureKafkaBroker(bootstrapServers)` | `PUT /kafka/configuration` |
+| `configureSchemaRegistry(url)` | `PUT /schemaRegistry/configuration` |
+| `kafkaConsumerRead(read)` | `POST /kafka/consumer` |
+
+Differences from the Java client:
+
+* A non-2xx response throws `CollectorError`, which has `status` and `responseBody`. The Java
+  client ignores the status.
+* Every method returns a Promise.
+* The configure calls need the Collector in runtime configuration mode. In static mode the Collector
+  answers `409`, which throws, so a test never silently reads from the wrong broker.
+* `flushToCloud` calls `markTestRunEnd`, as the Java client does. On a Collector with a Central
+  Logger configured, that also sends the run to the cloud.
+
+## Testing
+
+```bash
+npm test
+```
+
+The tests need no Collector. They stub the Collector's endpoints with
+[MSW (Mock Service Worker)](https://mswjs.io), declaring each route the way a WireMock stub is
+declared, then check the method, path, body and error handling. Any request without a matching
+stub fails the test. `flushToCloud` is not tested.

package/dist/diagram-logger-client.d.ts

@@ -0,0 +1,46 @@
+import type { DiagramLogger, Log, Logs } from '@deployagram/api';
+import type { KafkaConsumerRead } from './kafka.js';
+export interface DiagramLoggerClientOptions {
+    /** Base URL of the Collector, for example "http://localhost:1152". */
+    baseUrl: string;
+    /** Replaces the global fetch. Mainly for tests. */
+    fetch?: typeof fetch;
+}
+/**
+ * Client for the Deployagram Collector. Mirrors the Java DiagramLoggerClient, with two changes:
+ * HTTP errors are thrown (the Java client ignores them), and calls return Promises.
+ */
+export declare class DiagramLoggerClient implements DiagramLogger {
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(options: DiagramLoggerClientOptions);
+    /** POST /log: store one interaction. */
+    log(log: Log): Promise<void>;
+    /** GET /log/read: all logs held by the Collector. */
+    read(): Promise<Logs>;
+    /** GET /log/read/{logId}: the logs recorded under one marker. */
+    read(logId: string): Promise<Logs>;
+    /** POST /log/markEnd/{sequenceDiagramId}: close the current sequence diagram. */
+    markEnd(sequenceDiagramId: string): Promise<void>;
+    /**
+     * POST /run/markTestRunEnd/{containerId}/{testRunId}. As in the Java client, this is the call
+     * that ends a test run and, when a Central Logger is configured on the Collector, flushes it.
+     */
+    flushToCloud(containerId: string, testRunId: string): Promise<void>;
+    /**
+     * PUT /kafka/configuration: the broker the Collector reads Kafka records from. Needs the Collector
+     * in runtime configuration mode; otherwise it answers 409, which throws.
+     */
+    configureKafkaBroker(bootstrapServers: string): Promise<void>;
+    /**
+     * PUT /schemaRegistry/configuration: the registry the Collector decodes Avro and JSON-schema
+     * records with. Needs runtime mode, as configureKafkaBroker does.
+     */
+    configureSchemaRegistry(url: string): Promise<void>;
+    /**
+     * POST /kafka/consumer: tell the Collector a record was consumed. The Collector answers 204 and
+     * reads the record in the background.
+     */
+    kafkaConsumerRead(read: KafkaConsumerRead): Promise<void>;
+    private request;
+}

package/dist/diagram-logger-client.js

@@ -0,0 +1,67 @@
+import { CollectorError } from './errors.js';
+/**
+ * Client for the Deployagram Collector. Mirrors the Java DiagramLoggerClient, with two changes:
+ * HTTP errors are thrown (the Java client ignores them), and calls return Promises.
+ */
+export class DiagramLoggerClient {
+    baseUrl;
+    fetchImpl;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/+$/, '');
+        this.fetchImpl = options.fetch ?? fetch;
+    }
+    /** POST /log: store one interaction. */
+    async log(log) {
+        await this.request('POST', '/log', log);
+    }
+    async read(logId) {
+        const path = logId === undefined ? '/log/read' : `/log/read/${encodeURIComponent(logId)}`;
+        return (await this.request('GET', path));
+    }
+    /** POST /log/markEnd/{sequenceDiagramId}: close the current sequence diagram. */
+    async markEnd(sequenceDiagramId) {
+        await this.request('POST', `/log/markEnd/${encodeURIComponent(sequenceDiagramId)}`);
+    }
+    /**
+     * POST /run/markTestRunEnd/{containerId}/{testRunId}. As in the Java client, this is the call
+     * that ends a test run and, when a Central Logger is configured on the Collector, flushes it.
+     */
+    async flushToCloud(containerId, testRunId) {
+        await this.request('POST', `/run/markTestRunEnd/${encodeURIComponent(containerId)}/${encodeURIComponent(testRunId)}`);
+    }
+    /**
+     * PUT /kafka/configuration: the broker the Collector reads Kafka records from. Needs the Collector
+     * in runtime configuration mode; otherwise it answers 409, which throws.
+     */
+    async configureKafkaBroker(bootstrapServers) {
+        await this.request('PUT', '/kafka/configuration', { bootstrapServers });
+    }
+    /**
+     * PUT /schemaRegistry/configuration: the registry the Collector decodes Avro and JSON-schema
+     * records with. Needs runtime mode, as configureKafkaBroker does.
+     */
+    async configureSchemaRegistry(url) {
+        await this.request('PUT', '/schemaRegistry/configuration', { url });
+    }
+    /**
+     * POST /kafka/consumer: tell the Collector a record was consumed. The Collector answers 204 and
+     * reads the record in the background.
+     */
+    async kafkaConsumerRead(read) {
+        await this.request('POST', '/kafka/consumer', read);
+    }
+    async request(method, path, body) {
+        const init = { method, headers: { Accept: 'application/json' } };
+        if (body !== undefined) {
+            init.headers = { ...init.headers, 'Content-Type': 'application/json' };
+            init.body = JSON.stringify(body);
+        }
+        const response = await this.fetchImpl(this.baseUrl + path, init);
+        const text = await response.text();
+        if (!response.ok) {
+            throw new CollectorError(method, path, response.status, text);
+        }
+        return text ? JSON.parse(text) : undefined;
+    }
+}
+//# sourceMappingURL=diagram-logger-client.js.map

package/dist/diagram-logger-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagram-logger-client.js","sourceRoot":"","sources":["../src/diagram-logger-client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+/** Thrown when the Collector answers with a non-2xx status. */
+export declare class CollectorError extends Error {
+    readonly status: number;
+    readonly responseBody: string;
+    constructor(method: string, path: string, status: number, responseBody: string);
+}

package/dist/errors.js

@@ -0,0 +1,12 @@
+/** Thrown when the Collector answers with a non-2xx status. */
+export class CollectorError extends Error {
+    status;
+    responseBody;
+    constructor(method, path, status, responseBody) {
+        super(`Collector ${method} ${path} failed with HTTP ${status}${responseBody ? `: ${responseBody}` : ''}`);
+        this.name = 'CollectorError';
+        this.status = status;
+        this.responseBody = responseBody;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,MAAM,CAAS;IACf,YAAY,CAAS;IAE9B,YAAY,MAAc,EAAE,IAAY,EAAE,MAAc,EAAE,YAAoB;QAC5E,KAAK,CAAC,aAAa,MAAM,IAAI,IAAI,qBAAqB,MAAM,GAAG,YAAY,CAAC,CAAC,CAAC,KAAK,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC1G,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { DiagramLoggerClient } from './diagram-logger-client.js';
+export type { DiagramLoggerClientOptions } from './diagram-logger-client.js';
+export { CollectorError } from './errors.js';
+export type { KafkaConsumerRead } from './kafka.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { DiagramLoggerClient } from './diagram-logger-client.js';
+export { CollectorError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/kafka.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A Kafka record a test observed being consumed. The Collector reads the record's key and value
+ * from the broker itself, so only its coordinates are sent. Mirrors the Java consumer interceptor.
+ */
+export interface KafkaConsumerRead {
+    nameOfConsumingApp: string;
+    protocol: 'KAFKA Consumer';
+    topic: string;
+    partition: number;
+    offset: number;
+}

package/dist/kafka.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=kafka.js.map

package/dist/kafka.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kafka.js","sourceRoot":"","sources":["../src/kafka.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@deployagram/logger-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "HTTP client for the Deployagram Collector (living-http-logger), built on fetch. Node.js 22+.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@deployagram/api": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "msw": "^3.0.4",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  }
+}