coakka-logger-electron 1.2.1

package/CONSUMING.md

@@ -0,0 +1,14 @@
+# Consuming CoAkka Logger For Electron
+
+Install the published package through your normal application package feed.
+Electron itself remains the application framework dependency; this package owns
+the CoAkka logger intent bridge and consumes the published Node logger package
+from the Electron main process.
+
+Use the package only from the Electron main process and preload boundary:
+
+- main process: start `ElectronLoggerIntentBridge`
+- preload: expose `createCoAkkaLoggerPreloadApi(ipcRenderer)`
+- renderer: call `window.coakkaLogger.log(...)`
+
+Do not import the logger connector directly from renderer code.

package/LICENSE.md

@@ -0,0 +1,115 @@
+# CoAkka Public Artifact Preview License 1.0
+
+Effective: 2026-07-19
+
+This repository is the public binary artifact surface for CoAkka. It contains
+headers, native libraries, connector packages, Maven artifacts, checksums, and
+artifact metadata. It is not a source-build repository.
+
+Unless a specific release artifact includes different license terms, the
+artifacts in this repository are made available under the following preview
+terms.
+
+This is not an OSI-approved open source license. The separate
+`coakka-samples` repository may use a permissive open source license for sample
+code and documentation; that sample license does not change the terms for the
+artifacts distributed from this repository.
+
+## Definitions
+
+`Artifacts` means the CoAkka binaries, headers, libraries, connector packages,
+Maven artifacts, container-bundle files, checksums, manifests, and release
+metadata distributed from this repository or from an official release page for
+this repository.
+
+`Production` means any environment that serves live end-user traffic, live
+customer data, live operational data, revenue-generating workloads, or
+customer-facing workloads outside development, test, CI, sample execution, or
+proof-of-concept evaluation.
+
+`Official sample images` means container images published by the CoAkka
+project or repository owner, including the current
+`docker.io/gabrielgun1983/*` sample image namespace and any future images
+published under an official CoAkka container namespace, that bundle unmodified
+artifacts solely to run official CoAkka samples.
+
+## Allowed Use
+
+You may download, copy, and use the artifacts from this repository to:
+
+- evaluate CoAkka locally
+- run the official public samples
+- build proof-of-concept integrations
+- run development and test environments for applications that integrate with
+  CoAkka
+- run CI jobs, automated tests, and integration verification for
+  non-production applications or evaluations
+- run company evaluations, proofs of concept, and integration tests,
+  including evaluations inside commercial organizations
+- redistribute unmodified CoAkka artifacts inside local development, test, or
+  sample environments, provided this notice and the included checksums or
+  manifests remain available
+- pull, cache internally, and run official sample images for local development,
+  CI, test, sample execution, proof-of-concept integration, and evaluation
+
+## Reserved Uses
+
+The following uses require a separate written license:
+
+- selling, hosting, or offering CoAkka artifacts as a managed runtime service
+- running CoAkka artifacts in production systems
+- bundling CoAkka artifacts into a product distributed to customers
+- redistributing CoAkka artifacts as part of a paid product, support package,
+  appliance, cloud image, or hosted service
+- offering a product or service that presents modified CoAkka artifacts as
+  official CoAkka artifacts
+- removing or obscuring copyright, license, checksum, or provenance notices
+- reverse engineering artifacts except where that restriction is prohibited by
+  applicable law
+- using the CoAkka name, package names, artifact names, image names, or other
+  project identifiers in a way that implies endorsement of an unofficial fork,
+  hosted service, or product
+
+## Official Samples
+
+Official sample images may bundle unmodified artifacts solely so users can run
+official CoAkka samples without installing the artifacts manually.
+
+This sample-image permission does not grant third parties the right to create,
+publish, sell, host, or distribute derivative images for production, customer
+distribution, hosted services, paid support packages, appliances, or cloud
+marketplace offerings.
+
+## Production Use
+
+These preview terms are intended for developer evaluation, sample execution,
+non-production proof-of-concept work, CI, and integration testing. Production
+use, hosted service use, customer distribution, and paid redistribution require
+explicit release terms or a separate written agreement.
+
+For production, hosted service, customer distribution, paid redistribution, or
+other commercial rights, contact the project through `SUPPORT.md`.
+
+## No Warranty
+
+The artifacts are provided as-is, without warranties or conditions of any kind,
+to the maximum extent permitted by applicable law.
+
+## Limitation Of Liability
+
+To the maximum extent permitted by applicable law, the project contributors and
+artifact publishers are not liable for any direct, indirect, incidental,
+special, consequential, exemplary, or other damages arising from use of the
+artifacts.
+
+## No Patent Or Trademark Grant
+
+These preview terms do not grant patent rights, trademark rights, or rights to
+use the CoAkka name beyond the limited artifact and sample uses allowed above.
+Trademark use is governed by `TRADEMARKS.md`.
+
+## Legal Notice
+
+This file is not legal advice. If your intended use depends on legal
+interpretation of these terms, consult your own counsel or request a separate
+written agreement.

package/README.md

@@ -0,0 +1,59 @@
+# CoAkka Logger For Electron
+
+This package is the Electron main-process intent bridge for CoAkka logger.
+
+The boundary is intentionally strict:
+
+- renderer JavaScript sends a log intent through `ipcRenderer.invoke`
+- preload exposes only a small `coakkaLogger.log(...)` API
+- the Electron main process owns `ElectronLoggerIntentBridge`
+- the main process submits the log record and projects counters back to the
+  renderer
+
+Renderer code does not import the logger connector, does not own native logger
+lifecycle, and does not need a native library path in the normal path.
+
+## Main Process
+
+```js
+import { ipcMain } from "electron";
+import {
+  ElectronLoggerIntentBridge,
+  registerElectronLoggerIpcHandler,
+} from "coakka-logger-electron";
+
+const bridge = ElectronLoggerIntentBridge.start({
+  systemName: "electron-app-logger",
+});
+
+registerElectronLoggerIpcHandler(ipcMain, bridge);
+```
+
+## Preload
+
+```js
+const { contextBridge, ipcRenderer } = require("electron");
+const { createCoAkkaLoggerPreloadApi } = require("coakka-logger-electron/preload");
+
+contextBridge.exposeInMainWorld("coakkaLogger", createCoAkkaLoggerPreloadApi(ipcRenderer));
+```
+
+## Renderer
+
+```js
+const result = await window.coakkaLogger.log({
+  intentId: "log-1",
+  source: "electron-renderer",
+  level: "info",
+  category: "app.orders",
+  message: '{"event":"accepted"}',
+  awaitDrainMs: 1000,
+});
+```
+
+## Smoke
+
+```sh
+npm run build
+bash scripts/smoke-packaged-package.sh
+```

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { type LoggerRecordSnapshot, type LoggerSpec, type LoggerStatsSnapshot } from "coakka-logger-node";
+export declare const COAKKA_LOGGER_ELECTRON_VERSION = "1.2.1";
+export declare const COAKKA_ELECTRON_LOGGER_INTENT_CHANNEL = "coakka:logger-intent";
+export type ElectronLoggerLevelName = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+export interface ElectronLoggerIntent {
+    intentId: string;
+    source: string;
+    level: ElectronLoggerLevelName | number;
+    category: string;
+    message: string;
+    awaitDrainMs?: number;
+}
+export interface ElectronLoggerIntentResult {
+    intentId: string;
+    source: string;
+    accepted: boolean;
+    sequence: number | null;
+    record: LoggerRecordSnapshot | null;
+    stats: LoggerStatsSnapshot;
+}
+export interface ElectronLoggerIntentBridgeOptions extends LoggerSpec {
+    loggerLibPath?: string;
+}
+export interface IpcMainLike {
+    handle(channel: string, listener: (event: unknown, intent: ElectronLoggerIntent) => Promise<ElectronLoggerIntentResult>): void;
+    removeHandler(channel: string): void;
+}
+export declare class ElectronLoggerIntentBridge {
+    private readonly logger;
+    static start(options?: ElectronLoggerIntentBridgeOptions): ElectronLoggerIntentBridge;
+    private closed;
+    private constructor();
+    handleLogIntent(intent: ElectronLoggerIntent): Promise<ElectronLoggerIntentResult>;
+    stats(): LoggerStatsSnapshot;
+    close(): void;
+    private drainIfRequested;
+    private resultFor;
+    private requireOpen;
+}
+export declare function registerElectronLoggerIpcHandler(ipcMain: IpcMainLike, bridge: ElectronLoggerIntentBridge, channel?: string): () => void;

package/dist/index.js

@@ -0,0 +1,130 @@
+import { CoakkaLoggerLevel, Logger, LoggerStatusError, } from "coakka-logger-node";
+export const COAKKA_LOGGER_ELECTRON_VERSION = "1.2.1";
+export const COAKKA_ELECTRON_LOGGER_INTENT_CHANNEL = "coakka:logger-intent";
+export class ElectronLoggerIntentBridge {
+    logger;
+    static start(options = {}) {
+        const logger = Logger.start({
+            systemName: options.systemName ?? "electronLogger",
+            queueCapacity: options.queueCapacity,
+            categoryCapacity: options.categoryCapacity,
+            messageCapacity: options.messageCapacity,
+            minLevel: options.minLevel,
+        }, options.loggerLibPath);
+        return new ElectronLoggerIntentBridge(logger);
+    }
+    closed = false;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    async handleLogIntent(intent) {
+        this.requireOpen();
+        const normalized = normalizeIntent(intent);
+        let sequence = null;
+        try {
+            sequence = this.logger.log(normalized.level, normalized.category, normalized.message);
+        }
+        catch (error) {
+            if (error instanceof LoggerStatusError && error.statusName === "queue_full") {
+                return this.resultFor(normalized, null, null);
+            }
+            throw error;
+        }
+        const record = sequence == null ? null : this.drainIfRequested(normalized.awaitDrainMs);
+        return this.resultFor(normalized, sequence, record);
+    }
+    stats() {
+        this.requireOpen();
+        return this.logger.stats();
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.logger.close();
+    }
+    drainIfRequested(awaitDrainMs) {
+        if (awaitDrainMs == null) {
+            return null;
+        }
+        return this.logger.awaitNext(awaitDrainMs);
+    }
+    resultFor(intent, sequence, record) {
+        return {
+            intentId: intent.intentId,
+            source: intent.source,
+            accepted: sequence != null,
+            sequence,
+            record,
+            stats: this.logger.stats(),
+        };
+    }
+    requireOpen() {
+        if (this.closed) {
+            throw new Error("Electron logger intent bridge is closed");
+        }
+    }
+}
+export function registerElectronLoggerIpcHandler(ipcMain, bridge, channel = COAKKA_ELECTRON_LOGGER_INTENT_CHANNEL) {
+    ipcMain.handle(channel, async (_event, intent) => bridge.handleLogIntent(intent));
+    return () => ipcMain.removeHandler(channel);
+}
+function normalizeIntent(intent) {
+    if (intent == null || typeof intent !== "object") {
+        throw new Error("logger intent is required");
+    }
+    return {
+        intentId: requireNonBlank(intent.intentId, "intentId"),
+        source: requireNonBlank(intent.source, "source"),
+        level: normalizeLevel(intent.level),
+        category: requireNonBlank(intent.category, "category"),
+        message: requireString(intent.message, "message"),
+        awaitDrainMs: normalizeAwaitDrainMs(intent.awaitDrainMs),
+    };
+}
+function normalizeLevel(level) {
+    if (typeof level === "number") {
+        if (!Number.isInteger(level) || level < CoakkaLoggerLevel.TRACE || level > CoakkaLoggerLevel.FATAL) {
+            throw new Error("level must be a logger level integer");
+        }
+        return level;
+    }
+    switch (level) {
+        case "trace":
+            return CoakkaLoggerLevel.TRACE;
+        case "debug":
+            return CoakkaLoggerLevel.DEBUG;
+        case "info":
+            return CoakkaLoggerLevel.INFO;
+        case "warn":
+            return CoakkaLoggerLevel.WARN;
+        case "error":
+            return CoakkaLoggerLevel.ERROR;
+        case "fatal":
+            return CoakkaLoggerLevel.FATAL;
+        default:
+            throw new Error("level must be trace, debug, info, warn, error, or fatal");
+    }
+}
+function normalizeAwaitDrainMs(value) {
+    if (value == null) {
+        return undefined;
+    }
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error("awaitDrainMs must be a non-negative integer");
+    }
+    return value;
+}
+function requireString(value, what) {
+    if (typeof value !== "string") {
+        throw new Error(`${what} must be a string`);
+    }
+    return value;
+}
+function requireNonBlank(value, what) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`${what} is required`);
+    }
+    return value;
+}

package/dist/preload.cjs

@@ -0,0 +1,16 @@
+"use strict";
+
+const COAKKA_ELECTRON_LOGGER_INTENT_CHANNEL = "coakka:logger-intent";
+
+function createCoAkkaLoggerPreloadApi(ipcRenderer, channel = COAKKA_ELECTRON_LOGGER_INTENT_CHANNEL) {
+  return {
+    log(intent) {
+      return ipcRenderer.invoke(channel, intent);
+    },
+  };
+}
+
+module.exports = {
+  COAKKA_ELECTRON_LOGGER_INTENT_CHANNEL,
+  createCoAkkaLoggerPreloadApi,
+};

package/dist/preload.d.ts

@@ -0,0 +1,8 @@
+export declare const COAKKA_ELECTRON_LOGGER_INTENT_CHANNEL = "coakka:logger-intent";
+export interface IpcRendererLike {
+    invoke(channel: string, payload: unknown): Promise<unknown>;
+}
+export interface CoAkkaElectronLoggerPreloadApi {
+    log(intent: unknown): Promise<unknown>;
+}
+export declare function createCoAkkaLoggerPreloadApi(ipcRenderer: IpcRendererLike, channel?: string): CoAkkaElectronLoggerPreloadApi;

package/dist/preload.js

@@ -0,0 +1,8 @@
+export const COAKKA_ELECTRON_LOGGER_INTENT_CHANNEL = "coakka:logger-intent";
+export function createCoAkkaLoggerPreloadApi(ipcRenderer, channel = COAKKA_ELECTRON_LOGGER_INTENT_CHANNEL) {
+    return {
+        log(intent) {
+            return ipcRenderer.invoke(channel, intent);
+        },
+    };
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "coakka-logger-electron",
+  "version": "1.2.1",
+  "description": "Electron main-process intent bridge for the CoAkka logger",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./preload": {
+      "types": "./dist/preload.d.ts",
+      "import": "./dist/preload.js",
+      "require": "./dist/preload.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "CONSUMING.md",
+    "LICENSE.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build-package.mjs",
+    "verify": "npm run build",
+    "pack:release": "npm run build && node scripts/pack-release.mjs",
+    "smoke:packaged": "bash scripts/smoke-packaged-package.sh"
+  },
+  "dependencies": {
+    "coakka-logger-node": "1.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.3"
+  }
+}