coakka-v2-connector-electron 1.3.1

package/CONSUMING.md

@@ -0,0 +1,14 @@
+# Consuming CoAkka Runtime Connector For Electron
+
+Install the published package through your normal application package feed.
+Electron itself remains the application framework dependency; this package owns
+the CoAkka runtime intent bridge and consumes the published Node connector as
+the main-process runtime host.
+
+Use the package only from the Electron main process and preload boundary:
+
+- main process: start `ElectronRuntimeIntentBridge`
+- preload: expose `createCoAkkaPreloadApi(ipcRenderer)`
+- renderer: call `window.coakka.intent(...)`
+
+Do not import the runtime 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,77 @@
+# CoAkka Runtime Connector For Electron
+
+This package is the Electron main-process intent bridge for CoAkka runtime v2.
+
+The boundary is intentionally strict:
+
+- renderer JavaScript sends an intent through `ipcRenderer.invoke`
+- preload exposes only a small `coakka.intent(...)` API
+- the Electron main process owns `ElectronRuntimeIntentBridge`
+- the main process converts the intent into runtime delivery and projects the
+  result back to the renderer
+
+Renderer code does not import the runtime connector, does not know runtime
+envelopes, and does not own native runtime lifecycle.
+
+## Main Process
+
+```js
+import { ipcMain } from "electron";
+import {
+  ElectronRuntimeIntentBridge,
+  registerElectronIntentIpcHandler,
+} from "coakka-v2-connector-electron";
+
+const target = "samples.electron.intent.echo";
+const bridge = ElectronRuntimeIntentBridge.start({
+  systemName: "electron-app",
+  nodeId: "electron-app-main",
+  defaultTarget: target,
+});
+
+bridge.registerJsonIntentHandler(target, async (intent) => ({
+  handledBy: "electron-main",
+  echo: intent.payload,
+}));
+
+registerElectronIntentIpcHandler(ipcMain, bridge);
+```
+
+## Preload
+
+```js
+const { contextBridge, ipcRenderer } = require("electron");
+const { createCoAkkaPreloadApi } = require("coakka-v2-connector-electron/preload");
+
+contextBridge.exposeInMainWorld("coakka", createCoAkkaPreloadApi(ipcRenderer));
+```
+
+## Renderer
+
+```js
+const result = await window.coakka.intent({
+  intentId: "intent-1",
+  source: "electron-renderer",
+  target: "samples.electron.intent.echo",
+  operation: "echo",
+  payload: { message: "hello-electron-runtime" },
+  payloadIdentity: {
+    messageType: "samples.electron.intent.echo.request.v1",
+    payloadSchemaVersion: 1,
+    payloadFormat: "json",
+  },
+  timeoutMs: 2000,
+});
+```
+
+## Smoke
+
+```sh
+npm run build
+bash scripts/smoke-packaged-package.sh
+```
+
+The packaged smoke installs the generated package into a disposable Electron
+app, loads a hidden renderer window, sends one renderer intent through preload
+and IPC, and verifies that the main process handles it through the runtime
+host exposed by the published Node connector package.

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+export declare const COAKKA_ELECTRON_CONNECTOR_VERSION = "1.3.1";
+export declare const COAKKA_ELECTRON_INTENT_CHANNEL = "coakka:intent";
+export interface ElectronIntentPayloadIdentity {
+    messageType: string;
+    payloadSchemaVersion?: number;
+    payloadFormat?: "json";
+}
+export interface ElectronIntentEnvelope {
+    intentId: string;
+    source: string;
+    target: string;
+    operation: string;
+    payload: Record<string, unknown>;
+    payloadIdentity: ElectronIntentPayloadIdentity;
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+}
+export interface ElectronIntentResult {
+    intentId: string;
+    source: string;
+    target: string;
+    operation: string;
+    payload: Record<string, unknown>;
+    runtime: {
+        generation: number;
+        delivered: number;
+        matchedResponses: number;
+        matchedDeadletters: number;
+    };
+}
+export interface ElectronRuntimeIntentBridgeOptions {
+    systemName: string;
+    nodeId: string;
+    defaultTarget: string;
+    routePort?: number;
+    queueCapacity?: number;
+    strictNoDrop?: boolean;
+    runtimeLibPath?: string;
+}
+export type ElectronJsonIntentHandler = (intent: ElectronIntentEnvelope) => Record<string, unknown> | Promise<Record<string, unknown>>;
+export interface IpcMainLike {
+    handle(channel: string, listener: (event: unknown, intent: ElectronIntentEnvelope) => Promise<ElectronIntentResult>): void;
+    removeHandler(channel: string): void;
+}
+export declare class ElectronRuntimeIntentBridge {
+    private readonly runtimeHost;
+    readonly defaultTarget: string;
+    static start(options: ElectronRuntimeIntentBridgeOptions): ElectronRuntimeIntentBridge;
+    private readonly handlers;
+    private closed;
+    private constructor();
+    registerJsonIntentHandler(target: string, handler: ElectronJsonIntentHandler): void;
+    handleIntent(intent: ElectronIntentEnvelope): Promise<ElectronIntentResult>;
+    close(): void;
+    private createRuntimeHandler;
+    private requireOpen;
+}
+export declare function registerElectronIntentIpcHandler(ipcMain: IpcMainLike, bridge: ElectronRuntimeIntentBridge, channel?: string): () => void;

package/dist/index.js

@@ -0,0 +1,161 @@
+import { DeliveryHint, EndpointFlag, NodeRuntimeClient, PayloadFormat, PayloadIdentity, RuntimeHost, } from "coakka-v2-connector-node";
+export const COAKKA_ELECTRON_CONNECTOR_VERSION = "1.3.1";
+export const COAKKA_ELECTRON_INTENT_CHANNEL = "coakka:intent";
+const DEFAULT_ROUTE_PORT = 19481;
+export class ElectronRuntimeIntentBridge {
+    runtimeHost;
+    defaultTarget;
+    static start(options) {
+        const target = requireNonBlank(options.defaultTarget, "defaultTarget");
+        const startSpec = {
+            systemName: requireNonBlank(options.systemName, "systemName"),
+            nodeId: requireNonBlank(options.nodeId, "nodeId"),
+            queueCapacity: options.queueCapacity ?? 64,
+            strictNoDrop: options.strictNoDrop ?? true,
+            generation: 1,
+            routes: [
+                {
+                    target,
+                    endpoints: [
+                        {
+                            host: "127.0.0.1",
+                            port: options.routePort ?? DEFAULT_ROUTE_PORT,
+                            flags: EndpointFlag.LOCAL,
+                        },
+                    ],
+                },
+            ],
+        };
+        return new ElectronRuntimeIntentBridge(RuntimeHost.start(startSpec, options.runtimeLibPath), target);
+    }
+    handlers = new Map();
+    closed = false;
+    constructor(runtimeHost, defaultTarget) {
+        this.runtimeHost = runtimeHost;
+        this.defaultTarget = defaultTarget;
+    }
+    registerJsonIntentHandler(target, handler) {
+        const normalizedTarget = requireNonBlank(target, "target");
+        this.handlers.set(normalizedTarget, handler);
+        this.runtimeHost.registerHandler(normalizedTarget, this.createRuntimeHandler(normalizedTarget), true);
+    }
+    async handleIntent(intent) {
+        this.requireOpen();
+        const normalized = normalizeIntent(intent);
+        const identity = toPayloadIdentity(normalized.payloadIdentity);
+        const response = await this.runtimeHost.askJson(normalized.source, normalized.target, normalized.payload, identity, normalized.timeoutMs ?? 2_000, normalized.operation, DeliveryHint.ROUTER_DEFAULT, normalized.headers ?? {});
+        const clientStats = this.runtimeHost.clientStats();
+        const runtimeStats = this.runtimeHost.stats();
+        return {
+            intentId: normalized.intentId,
+            source: normalized.source,
+            target: normalized.target,
+            operation: normalized.operation,
+            payload: response,
+            runtime: {
+                generation: runtimeStats.appliedGeneration,
+                delivered: clientStats.deliveredRequests,
+                matchedResponses: clientStats.matchedResponses,
+                matchedDeadletters: clientStats.matchedDeadletters,
+            },
+        };
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.runtimeHost.close();
+    }
+    createRuntimeHandler(target) {
+        return async (request) => {
+            const handler = this.handlers.get(target);
+            if (handler == null) {
+                throw new Error(`no Electron intent handler registered for target=${target}`);
+            }
+            const payload = JSON.parse(Buffer.from(request.payload).toString("utf8"));
+            const resultPayload = await handler({
+                intentId: request.message_id,
+                source: request.source,
+                target,
+                operation: "intent",
+                payload,
+                payloadIdentity: {
+                    messageType: request.message_type,
+                    payloadSchemaVersion: request.payload_schema_version,
+                    payloadFormat: "json",
+                },
+                headers: request.headers,
+            });
+            return NodeRuntimeClient.makeJsonReplyFromRequestIdentity(request, target, resultPayload);
+        };
+    }
+    requireOpen() {
+        if (this.closed) {
+            throw new Error("Electron runtime intent bridge is closed");
+        }
+    }
+}
+export function registerElectronIntentIpcHandler(ipcMain, bridge, channel = COAKKA_ELECTRON_INTENT_CHANNEL) {
+    ipcMain.handle(channel, async (_event, intent) => bridge.handleIntent(intent));
+    return () => ipcMain.removeHandler(channel);
+}
+function normalizeIntent(intent) {
+    if (intent == null || typeof intent !== "object") {
+        throw new Error("intent envelope is required");
+    }
+    return {
+        intentId: requireNonBlank(intent.intentId, "intentId"),
+        source: requireNonBlank(intent.source, "source"),
+        target: requireNonBlank(intent.target, "target"),
+        operation: requireNonBlank(intent.operation, "operation"),
+        payload: requireJsonObject(intent.payload, "payload"),
+        payloadIdentity: requirePayloadIdentity(intent.payloadIdentity),
+        timeoutMs: normalizeTimeout(intent.timeoutMs),
+        headers: normalizeHeaders(intent.headers),
+    };
+}
+function toPayloadIdentity(identity) {
+    return new PayloadIdentity(identity.messageType, identity.payloadSchemaVersion ?? 1, PayloadFormat.JSON).requireTyped("Electron intent payloadIdentity");
+}
+function requirePayloadIdentity(identity) {
+    if (identity == null || typeof identity !== "object") {
+        throw new Error("payloadIdentity is required");
+    }
+    return {
+        messageType: requireNonBlank(identity.messageType, "payloadIdentity.messageType"),
+        payloadSchemaVersion: identity.payloadSchemaVersion ?? 1,
+        payloadFormat: "json",
+    };
+}
+function requireJsonObject(value, what) {
+    if (value == null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${what} must be a JSON object`);
+    }
+    return value;
+}
+function normalizeHeaders(headers) {
+    if (headers == null) {
+        return {};
+    }
+    const normalized = {};
+    for (const [key, value] of Object.entries(headers)) {
+        normalized[requireNonBlank(key, "header key")] = String(value);
+    }
+    return normalized;
+}
+function normalizeTimeout(timeoutMs) {
+    if (timeoutMs == null) {
+        return undefined;
+    }
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1) {
+        throw new Error("timeoutMs must be a positive integer");
+    }
+    return timeoutMs;
+}
+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_INTENT_CHANNEL = "coakka:intent";
+
+function createCoAkkaPreloadApi(ipcRenderer, channel = COAKKA_ELECTRON_INTENT_CHANNEL) {
+  return {
+    intent(intent) {
+      return ipcRenderer.invoke(channel, intent);
+    },
+  };
+}
+
+module.exports = {
+  COAKKA_ELECTRON_INTENT_CHANNEL,
+  createCoAkkaPreloadApi,
+};

package/dist/preload.d.ts

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

package/dist/preload.js

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "coakka-v2-connector-electron",
+  "version": "1.3.1",
+  "description": "Electron main-process intent bridge for the CoAkka runtime v2",
+  "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-v2-connector-node": "1.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.8.3"
+  }
+}