@journal.one/gateway-client 0.1.0

package/dist/server.d.ts

@@ -0,0 +1,84 @@
+import type { Integration, ToolDefinition, ToolResult, Skill } from "./types.js";
+export interface TokenValidationResult {
+    organizationId: string;
+    organizationName?: string;
+}
+export interface GatewayServerOptions {
+    port?: number;
+    validateToken: (token: string) => Promise<TokenValidationResult | null>;
+    pingIntervalMs?: number;
+    pullTimeoutMs?: number;
+}
+export interface ConnectedGateway {
+    id: string;
+    organizationId: string;
+    protocolVersion: number;
+    gatewayVersion: string;
+    integrations: Integration[];
+    mcpVersion: string | null;
+    skillsVersion: string | null;
+}
+export declare class GatewayServer {
+    private options;
+    private wss;
+    private gateways;
+    private _port;
+    private pingTimer;
+    private connCounter;
+    private reqCounter;
+    private pullCounter;
+    private pullTimeoutMs;
+    constructor(options: GatewayServerOptions);
+    get port(): number;
+    get url(): string;
+    get connectedGateways(): ConnectedGateway[];
+    get availableTools(): Array<{
+        integrationId: string;
+        name: string;
+        description: string;
+    }>;
+    onGatewayConnected?: (gateway: ConnectedGateway) => void;
+    onGatewayUpdated?: (gateway: ConnectedGateway) => void;
+    onGatewayDisconnected?: (gateway: ConnectedGateway) => void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    callTool(integrationId: string, toolName: string, args: Record<string, unknown>, timeoutMs?: number): Promise<ToolResult>;
+    /** Check if any gateway is connected for the given organization. */
+    hasGatewayForOrg(organizationId: string): boolean;
+    /** Get all connected gateways for an organization. */
+    getGatewaysForOrg(organizationId: string): ConnectedGateway[];
+    /** Get deduplicated tools across all gateways for an organization. */
+    getToolsForOrg(organizationId: string): Array<{
+        integrationId: string;
+        tool: ToolDefinition;
+    }>;
+    /** Pull current versions from a gateway. */
+    getVersions(gatewayId: string): Promise<{
+        mcpVersion: string | null;
+        skillsVersion: string | null;
+    }>;
+    /** Pull tools from a gateway. */
+    getTools(gatewayId: string): Promise<{
+        integrations: Integration[];
+        mcpVersion: string | null;
+    }>;
+    /** Pull skills from a gateway. */
+    getSkills(gatewayId: string): Promise<{
+        skills: Skill[];
+        skillsVersion: string | null;
+    }>;
+    /**
+     * Call a tool on any gateway for the given organization that provides the
+     * requested integration. Picks a random candidate for load balancing and
+     * retries on a different one if the call fails with a connection error.
+     */
+    callToolForOrg(organizationId: string, integrationId: string, toolName: string, args: Record<string, unknown>, timeoutMs?: number): Promise<ToolResult>;
+    private callToolOnEntry;
+    private sendPull;
+    private resolvePull;
+    private autoPull;
+    private pullTools;
+    private pullSkills;
+    private handleConnection;
+    private sendPings;
+}

package/dist/server.js

@@ -0,0 +1,465 @@
+import { WebSocketServer } from "ws";
+import { GatewayMessageSchema } from "./types.js";
+export class GatewayServer {
+    options;
+    wss = null;
+    gateways = new Map();
+    _port;
+    pingTimer = null;
+    connCounter = 0;
+    reqCounter = 0;
+    pullCounter = 0;
+    pullTimeoutMs;
+    constructor(options) {
+        this.options = options;
+        this._port = options.port ?? 0;
+        this.pullTimeoutMs = options.pullTimeoutMs ?? 30_000;
+    }
+    get port() {
+        return this._port;
+    }
+    get url() {
+        return `ws://localhost:${this._port}`;
+    }
+    get connectedGateways() {
+        return Array.from(this.gateways.values()).map((g) => g.gateway);
+    }
+    get availableTools() {
+        const tools = [];
+        for (const { gateway } of this.gateways.values()) {
+            for (const integration of gateway.integrations) {
+                for (const tool of integration.tools) {
+                    tools.push({
+                        integrationId: integration.id,
+                        name: tool.name,
+                        description: tool.description,
+                    });
+                }
+            }
+        }
+        return tools;
+    }
+    onGatewayConnected;
+    onGatewayUpdated;
+    onGatewayDisconnected;
+    async start() {
+        return new Promise((resolve) => {
+            this.wss = new WebSocketServer({ port: this._port }, () => {
+                const addr = this.wss.address();
+                if (typeof addr === "object" && addr !== null) {
+                    this._port = addr.port;
+                }
+                resolve();
+            });
+            this.wss.on("connection", (ws) => this.handleConnection(ws));
+            const interval = this.options.pingIntervalMs ?? 30_000;
+            if (interval > 0) {
+                this.pingTimer = setInterval(() => this.sendPings(), interval);
+            }
+        });
+    }
+    async stop() {
+        if (this.pingTimer) {
+            clearInterval(this.pingTimer);
+            this.pingTimer = null;
+        }
+        for (const entry of this.gateways.values()) {
+            if (entry.pongTimer)
+                clearTimeout(entry.pongTimer);
+            for (const pending of entry.pending.values()) {
+                clearTimeout(pending.timer);
+                pending.reject(new Error("Server shutting down"));
+            }
+            for (const pull of entry.pendingPulls.values()) {
+                clearTimeout(pull.timer);
+                pull.reject(new Error("Server shutting down"));
+            }
+            entry.ws.close();
+        }
+        this.gateways.clear();
+        return new Promise((resolve) => {
+            if (this.wss) {
+                this.wss.close(() => resolve());
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    async callTool(integrationId, toolName, args, timeoutMs = 90_000) {
+        let targetEntry;
+        for (const entry of this.gateways.values()) {
+            if (entry.gateway.integrations.some((i) => i.id === integrationId)) {
+                targetEntry = entry;
+                break;
+            }
+        }
+        if (!targetEntry) {
+            throw new Error(`No gateway has integration "${integrationId}"`);
+        }
+        return this.callToolOnEntry(targetEntry, integrationId, toolName, args, timeoutMs);
+    }
+    /** Check if any gateway is connected for the given organization. */
+    hasGatewayForOrg(organizationId) {
+        for (const { gateway } of this.gateways.values()) {
+            if (gateway.organizationId === organizationId)
+                return true;
+        }
+        return false;
+    }
+    /** Get all connected gateways for an organization. */
+    getGatewaysForOrg(organizationId) {
+        const result = [];
+        for (const { gateway } of this.gateways.values()) {
+            if (gateway.organizationId === organizationId) {
+                result.push(gateway);
+            }
+        }
+        return result;
+    }
+    /** Get deduplicated tools across all gateways for an organization. */
+    getToolsForOrg(organizationId) {
+        const seen = new Set();
+        const tools = [];
+        for (const { gateway } of this.gateways.values()) {
+            if (gateway.organizationId !== organizationId)
+                continue;
+            for (const integration of gateway.integrations) {
+                for (const tool of integration.tools) {
+                    const key = `${integration.id}.${tool.name}`;
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        tools.push({ integrationId: integration.id, tool });
+                    }
+                }
+            }
+        }
+        return tools;
+    }
+    /** Pull current versions from a gateway. */
+    async getVersions(gatewayId) {
+        const data = await this.sendPull(gatewayId, "get_versions");
+        return data;
+    }
+    /** Pull tools from a gateway. */
+    async getTools(gatewayId) {
+        const data = await this.sendPull(gatewayId, "get_tools");
+        return data;
+    }
+    /** Pull skills from a gateway. */
+    async getSkills(gatewayId) {
+        const data = await this.sendPull(gatewayId, "get_skills");
+        return data;
+    }
+    /**
+     * Call a tool on any gateway for the given organization that provides the
+     * requested integration. Picks a random candidate for load balancing and
+     * retries on a different one if the call fails with a connection error.
+     */
+    async callToolForOrg(organizationId, integrationId, toolName, args, timeoutMs = 90_000) {
+        const candidates = [];
+        for (const entry of this.gateways.values()) {
+            if (entry.gateway.organizationId === organizationId &&
+                entry.gateway.integrations.some((i) => i.id === integrationId)) {
+                candidates.push(entry);
+            }
+        }
+        if (candidates.length === 0) {
+            throw new Error(`No gateway for org "${organizationId}" has integration "${integrationId}"`);
+        }
+        // Shuffle candidates for load balancing
+        for (let i = candidates.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [candidates[i], candidates[j]] = [candidates[j], candidates[i]];
+        }
+        let lastError;
+        for (const entry of candidates) {
+            try {
+                return await this.callToolOnEntry(entry, integrationId, toolName, args, timeoutMs);
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                // Only retry on connection-level errors
+                if (!lastError.message.includes("Gateway disconnected")) {
+                    throw lastError;
+                }
+            }
+        }
+        throw lastError ?? new Error("All gateway candidates failed");
+    }
+    callToolOnEntry(entry, integrationId, toolName, args, timeoutMs) {
+        const requestId = `req_${++this.reqCounter}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                entry.pending.delete(requestId);
+                reject(new Error(`Tool call timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            entry.pending.set(requestId, { resolve, reject, timer });
+            entry.ws.send(JSON.stringify({
+                type: "tool_call",
+                requestId,
+                integrationId,
+                toolName,
+                arguments: args,
+            }));
+        });
+    }
+    sendPull(gatewayId, type) {
+        const entry = this.gateways.get(gatewayId);
+        if (!entry) {
+            return Promise.reject(new Error(`Gateway "${gatewayId}" not found`));
+        }
+        const requestId = `pull_${++this.pullCounter}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                entry.pendingPulls.delete(requestId);
+                reject(new Error(`Pull ${type} timed out`));
+            }, this.pullTimeoutMs);
+            entry.pendingPulls.set(requestId, { resolve, reject, timer });
+            entry.ws.send(JSON.stringify({ type, requestId }));
+        });
+    }
+    resolvePull(connId, requestId, data) {
+        const entry = this.gateways.get(connId);
+        if (!entry)
+            return;
+        const pull = entry.pendingPulls.get(requestId);
+        if (pull) {
+            clearTimeout(pull.timer);
+            entry.pendingPulls.delete(requestId);
+            pull.resolve(data);
+        }
+    }
+    async autoPull(connId) {
+        const entry = this.gateways.get(connId);
+        if (!entry)
+            return;
+        const pulls = [];
+        if (entry.gateway.mcpVersion !== null) {
+            pulls.push(this.pullTools(connId));
+        }
+        if (entry.gateway.skillsVersion !== null) {
+            pulls.push(this.pullSkills(connId));
+        }
+        await Promise.all(pulls);
+    }
+    async pullTools(connId) {
+        const entry = this.gateways.get(connId);
+        if (!entry)
+            return;
+        const data = await this.sendPull(connId, "get_tools");
+        entry.gateway.integrations = [
+            ...data.integrations,
+            ...entry.gateway.integrations.filter((i) => i.id === "skills"),
+        ];
+        entry.gateway.mcpVersion = data.mcpVersion;
+    }
+    async pullSkills(connId) {
+        const entry = this.gateways.get(connId);
+        if (!entry)
+            return;
+        const data = await this.sendPull(connId, "get_skills");
+        // Build skills integration if any skills exist
+        const nonSkillIntegrations = entry.gateway.integrations.filter((i) => i.id !== "skills");
+        if (data.skills.length > 0) {
+            nonSkillIntegrations.push({
+                id: "skills",
+                name: "Skills",
+                description: "Gateway skills",
+                tools: [],
+                skills: data.skills,
+            });
+        }
+        entry.gateway.integrations = nonSkillIntegrations;
+        entry.gateway.skillsVersion = data.skillsVersion;
+    }
+    handleConnection(ws) {
+        const connId = `gw_${++this.connCounter}`;
+        let authenticated = false;
+        let organizationId = "";
+        let protocolVersion = 0;
+        let gatewayVersion = "unknown";
+        const authTimer = setTimeout(() => {
+            if (!authenticated) {
+                ws.close();
+            }
+        }, 10_000);
+        ws.on("message", async (data) => {
+            let msg;
+            try {
+                msg = GatewayMessageSchema.parse(JSON.parse(data.toString()));
+            }
+            catch {
+                return;
+            }
+            switch (msg.type) {
+                case "authenticate": {
+                    const result = await this.options.validateToken(msg.token);
+                    if (result) {
+                        clearTimeout(authTimer);
+                        authenticated = true;
+                        organizationId = result.organizationId;
+                        protocolVersion = msg.protocolVersion;
+                        gatewayVersion = msg.gatewayVersion;
+                        ws.send(JSON.stringify({
+                            type: "authenticated",
+                            organizationId: result.organizationId,
+                            ...(result.organizationName
+                                ? { organizationName: result.organizationName }
+                                : {}),
+                        }));
+                    }
+                    else {
+                        clearTimeout(authTimer);
+                        ws.send(JSON.stringify({
+                            type: "auth_error",
+                            error: "Invalid token",
+                        }));
+                        ws.close();
+                    }
+                    break;
+                }
+                case "version_changed": {
+                    if (!authenticated) {
+                        ws.close();
+                        return;
+                    }
+                    const mcpVersion = msg.mcpVersion;
+                    const skillsVersion = msg.skillsVersion;
+                    const existing = this.gateways.get(connId);
+                    if (existing) {
+                        // Subsequent version_changed: update versions and pull what changed
+                        const mcpChanged = mcpVersion !== existing.gateway.mcpVersion;
+                        const skillsChanged = skillsVersion !== existing.gateway.skillsVersion;
+                        existing.gateway.mcpVersion = mcpVersion;
+                        existing.gateway.skillsVersion = skillsVersion;
+                        const pulls = [];
+                        if (mcpChanged && mcpVersion !== null) {
+                            pulls.push(this.pullTools(connId));
+                        }
+                        else if (mcpChanged && mcpVersion === null) {
+                            // MCP removed: clear tool integrations
+                            existing.gateway.integrations = existing.gateway.integrations.filter((i) => i.id === "skills");
+                        }
+                        if (skillsChanged && skillsVersion !== null) {
+                            pulls.push(this.pullSkills(connId));
+                        }
+                        else if (skillsChanged && skillsVersion === null) {
+                            // Skills removed: clear skills integrations
+                            existing.gateway.integrations = existing.gateway.integrations.filter((i) => i.id !== "skills");
+                        }
+                        if (pulls.length > 0) {
+                            await Promise.all(pulls);
+                        }
+                        this.onGatewayUpdated?.(existing.gateway);
+                    }
+                    else {
+                        // First version_changed: create gateway entry, auto-pull, then fire connected
+                        const gateway = {
+                            id: connId,
+                            organizationId,
+                            protocolVersion,
+                            gatewayVersion,
+                            integrations: [],
+                            mcpVersion,
+                            skillsVersion,
+                        };
+                        const entry = {
+                            ws,
+                            gateway,
+                            pending: new Map(),
+                            pendingPulls: new Map(),
+                            pongTimer: null,
+                        };
+                        this.gateways.set(connId, entry);
+                        // Auto-pull and then fire connected callback
+                        await this.autoPull(connId);
+                        this.onGatewayConnected?.(gateway);
+                    }
+                    break;
+                }
+                case "tool_result": {
+                    const entry = this.gateways.get(connId);
+                    if (!entry)
+                        return;
+                    const pending = entry.pending.get(msg.requestId);
+                    if (pending) {
+                        clearTimeout(pending.timer);
+                        entry.pending.delete(msg.requestId);
+                        pending.resolve(msg.result);
+                    }
+                    break;
+                }
+                case "tool_error": {
+                    const entry = this.gateways.get(connId);
+                    if (!entry)
+                        return;
+                    const pending = entry.pending.get(msg.requestId);
+                    if (pending) {
+                        clearTimeout(pending.timer);
+                        entry.pending.delete(msg.requestId);
+                        pending.reject(new Error(`Tool error [${msg.error.code}]: ${msg.error.message}`));
+                    }
+                    break;
+                }
+                case "pong": {
+                    const entry = this.gateways.get(connId);
+                    if (entry?.pongTimer) {
+                        clearTimeout(entry.pongTimer);
+                        entry.pongTimer = null;
+                    }
+                    break;
+                }
+                case "versions": {
+                    this.resolvePull(connId, msg.requestId, {
+                        mcpVersion: msg.mcpVersion,
+                        skillsVersion: msg.skillsVersion,
+                    });
+                    break;
+                }
+                case "tools": {
+                    this.resolvePull(connId, msg.requestId, {
+                        integrations: msg.integrations,
+                        mcpVersion: msg.mcpVersion,
+                    });
+                    break;
+                }
+                case "skills": {
+                    this.resolvePull(connId, msg.requestId, {
+                        skills: msg.skills,
+                        skillsVersion: msg.skillsVersion,
+                    });
+                    break;
+                }
+            }
+        });
+        ws.on("close", () => {
+            clearTimeout(authTimer);
+            const entry = this.gateways.get(connId);
+            if (entry) {
+                if (entry.pongTimer)
+                    clearTimeout(entry.pongTimer);
+                for (const pending of entry.pending.values()) {
+                    clearTimeout(pending.timer);
+                    pending.reject(new Error("Gateway disconnected"));
+                }
+                for (const pull of entry.pendingPulls.values()) {
+                    clearTimeout(pull.timer);
+                    pull.reject(new Error("Gateway disconnected"));
+                }
+                this.gateways.delete(connId);
+                this.onGatewayDisconnected?.(entry.gateway);
+            }
+        });
+    }
+    sendPings() {
+        for (const entry of this.gateways.values()) {
+            entry.ws.send(JSON.stringify({ type: "ping" }));
+            if (entry.pongTimer)
+                clearTimeout(entry.pongTimer);
+            entry.pongTimer = setTimeout(() => {
+                entry.ws.close();
+            }, 10_000);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export type { Integration, ToolDefinition, ToolResult, ContentBlock, TextContent, ImageContent, Skill, GatewayError, GatewayErrorCode, GatewayMessage, VersionChangedMessage, VersionsMessage, ToolsMessage, SkillsMessage, GatewayVersions, ServiceMessage, } from "@journal.one/gateway-protocol";
+export { GatewayMessageSchema, VersionChangedMessageSchema, VersionsMessageSchema, ToolsMessageSchema, SkillsMessageSchema, ServiceMessageSchema, IntegrationSchema, ToolResultSchema, } from "@journal.one/gateway-protocol";

package/dist/types.js

@@ -0,0 +1 @@
+export { GatewayMessageSchema, VersionChangedMessageSchema, VersionsMessageSchema, ToolsMessageSchema, SkillsMessageSchema, ServiceMessageSchema, IntegrationSchema, ToolResultSchema, } from "@journal.one/gateway-protocol";

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@journal.one/gateway-client",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/server.js",
+  "types": "./dist/server.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ws": "^8",
+    "zod": "^3.24",
+    "@journal.one/gateway-protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "@types/ws": "^8",
+    "typescript": "^5.7",
+    "vitest": "^3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  }
+}