SocketX Client, public package

socketx-client-public is the all in one JavaScript client for the SocketX server that ships in the Eclypses cloud marketplace images. It bundles the socketxclient core, one build of the MTE WASM library, and the license that build is tied to, so it installs from npm with no registry credential, no peer dependency, and no license setup.

See https://socketx.eclypses.com for the product.

Example usage

SocketXClient implements the standard WebSocket interface. Swap the constructor and keep the rest.

import { SocketXClient } from "socketx-client-public";

// The URL names the upstream. Its origin is the relay, and its path plus query travel to
// the relay inside the ciphertext.
const socket = new SocketXClient("wss://relay.example.com/ws/echo");

socket.onopen = () => socket.send("hello");
socket.onmessage = (event) => console.log(event.data);
socket.onclose = (event) => console.log(event.code, event.reason);

Two differences from a plain WebSocket are worth knowing. Opening takes two round trips and a Kyber pairing, so readyState stays CONNECTING measurably longer. And send before open throws rather than buffering, because there is no encoder until the pairing completes.

Options

The second argument is optional. It takes every option of the core client except the license, which this package supplies.

const socket = new SocketXClient("wss://relay.example.com/ws/echo", {
  relayOrigin: "https://relay.example.com", // when the relay is not the URL's origin
  headers: { cookie: "session=abc" },        // forwarded upstream inside the ciphertext
  discovery: false,                          // skip the discovery call; the default fetches it
});

Handling errors

A relay generated failure reaches you as a close event, not a thrown object. The code is the relay code mapped into the application range and the reason is the registry token. relayCodeFromClose inverts the mapping and defaultAction answers what a client should do about that code and reason. The library never reconnects on its own.

import { defaultAction, relayCodeFromClose } from "socketx-client-public";

socket.onclose = (event) => {
  const code = relayCodeFromClose(event.code);
  if (code === undefined) return; // 1000 through 1015: a clean close or a transport failure
  switch (defaultAction(code, event.reason)) {
    case "stop": // a revoked key or a denied alias; retrying turns one misconfiguration into a flood
      break;
    case "back_off": // a limit; wait before reopening
      break;
    default: // open a new connection, which mints a new pair
      break;
  }
};

What is bundled

• socketxclient, the core client. Its README documents the protocol, the layout, and the license bearing constructor. This package re-exports everything it exports and replaces SocketXClient with the license free one above.
• The MTE WASM client build, inlined. It pairs only with the server build the marketplace images link. A relay on any other build fails on the first message, not intermittently.
• The marketplace license, matched to that build and those images.

Nothing else. The published package has no dependencies, and the declarations under dist/types are complete on their own.

Building and publishing

npm ci                 # from the committed lockfile; mte comes from the Eclypses registry named in .npmrc
npm run build          # tsc, vite build, then bundle the declarations
npm test               # packs the tarball and checks it from a clean directory
npm publish --tag beta

prepack runs the build, so a publish never ships a stale dist.

package.json pins the exact socketxclient and mte versions a release bundles, and package-lock.json is committed so a CI build reproduces the same archive. The core is published first, from socketx-client-typescript-core; then this package takes that exact version: bump the pin, run npm install --allow-remote=root, commit the lockfile, and publish. A lockfile that resolves the core from a local archive is a workstation artifact and must not be committed.

On npm 12, add --allow-remote=root to npm install. Its default refuses any tarball it does not recognize as a registry fetch, and it does not recognize the scoped Eclypses registry, so it refuses the mte package. root rather than all because only this package's own dependencies need it.

The pipeline in azure-pipelines.yml builds and verifies the package on main, using the ECLYPSES_NPM_TOKEN secret to reach the registry, and mirrors the public branch to github.com/Eclypses/socketx-client-public, the way mte-relay-browser-public-client is mirrored. That destination has to exist before the first push to public.