Developer SDK

TypeScript examples

Install the SDK · View source on GitHub ↗

embed/main.ts

typescript
// The TypeScript embed example: a Node 24 console app for Windows, macOS and
// Linux that embeds URnetwork in your product (EMBED_CONTRACT.md). It obtains
// this installation's scoped client JWT from your backend's token server (or
// uses the client.jwt your backend tool wrote), starts the embedded device and
// shows its status and its own data caps. The device carries only the app's
// own traffic: no VPN. The JavaScript SDK cannot run a local Device, so the
// native companion (javascript/integration/companion, embed mode) owns the
// device as this program's child process and serves its status (session.ts).
//
// Usage: node main.ts [run] | --self-test | --licenses | --version. --licenses
// prints the SDK's licenses and data attributions, as JSON from the companion,
// to publish with the app. All installation state is in the private directory
// named by URNETWORK_EMBED_STATE_DIR (state.ts).
//
// Exit codes, for supervisors: 0 stopped on request, 78 configuration or
// credential problem (restarting does not help), 1 any other failure.

import {realpathSync} from "node:fs";
import {fileURLToPath} from "node:url";
import {parseCommand, usage} from "./command.ts";
import {type Environment, checkCompanionPath, companionLicenses, companionPath, companionVersion} from "./companion.ts";
import {runSelfTest} from "./selftest.ts";
import {EmbedSession, type EmbedSettings, type Installation, type LineWriter, exitConfig, exitFailure, exitStopped, loadEmbedSettings, obtainInstallation} from "./session.ts";
import {ConfigurationError} from "./state.ts";
import {startLine} from "./status.ts";
import {type FetchFunction, TokenError} from "./token.ts";

// The options of run, for tests.
export interface RunOptions {
  environment?: Environment;
  log?: LineWriter;
  error?: LineWriter;
  fetchFunction?: FetchFunction;
}

// The message of an error.
function errorMessage(error: unknown): string {
  return error instanceof Error ? error.message : String(error);
}

// The exit code for an error that stopped the run before the device started.
export function startExitCode(startError: unknown): number {
  if (startError instanceof ConfigurationError) {
    return exitConfig;
  }
  if (startError instanceof TokenError) {
    return startError.exitCode;
  }
  return exitFailure;
}

// Runs one command and returns the exit code. The options replace the process
// environment, the console and fetch, for tests.
export async function run(args: readonly string[], {environment = process.env, log = console.log, error = console.error, fetchFunction = globalThis.fetch}: RunOptions = {}): Promise<number> {
  const command = parseCommand(args);
  if (command === "self-test") {
    try {
      await runSelfTest();
    } catch (selfTestError) {
      error(`embed self-test failed: ${errorMessage(selfTestError)}`);
      return exitFailure;
    }
    log("embed self-test passed");
    return exitStopped;
  }
  if (command === "version" || command === "licenses") {
    const path = companionPath(environment);
    try {
      await checkCompanionPath(path);
      log(await (command === "version" ? companionVersion(path) : companionLicenses(path)));
    } catch (companionError) {
      error(errorMessage(companionError));
      return exitFailure;
    }
    return exitStopped;
  }
  if (command === null) {
    error(usage);
    return exitConfig;
  }

  let settings: EmbedSettings;
  let installation: Installation;
  const path = companionPath(environment);
  try {
    settings = await loadEmbedSettings(environment);
    // the companion is checked before a token fetch provisions a client
    await checkCompanionPath(path).catch((companionError: unknown) => {
      throw new ConfigurationError(errorMessage(companionError));
    });
    installation = await obtainInstallation(settings, fetchFunction);
  } catch (startError) {
    error(errorMessage(startError));
    return startExitCode(startError);
  }

  const controller = new AbortController();
  const stop = (): void => controller.abort();
  process.once("SIGINT", stop);
  process.once("SIGTERM", stop);
  const session = new EmbedSession({
    stateDir: settings.stateDir,
    companionPath: path,
    apiUrl: settings.apiUrl,
    initialDataCap: installation.dataCap,
    log,
    error,
    fetchFunction,
  });
  try {
    log(startLine(installation.clientId, installation.instanceId));
    await session.start(environment);
    return await session.run(controller.signal);
  } catch (runError) {
    error(`could not run the embedded device: ${errorMessage(runError)}`);
    return exitFailure;
  } finally {
    await session.close();
    process.removeListener("SIGINT", stop);
    process.removeListener("SIGTERM", stop);
  }
}

// Whether the module of meta is the program's entry point. Node 24.2 and later
// say so in import.meta.main; earlier Node 24 releases leave it undefined, so
// the entry script's real path decides.
export function isEntryPoint(meta: {main?: boolean; url: string}, entryPath: string | undefined): boolean {
  if (typeof meta.main === "boolean") {
    return meta.main;
  }
  return entryPath !== undefined && realpathSync(entryPath) === fileURLToPath(meta.url);
}

if (isEntryPoint(import.meta, process.argv[1])) {
  process.exitCode = await run(process.argv.slice(2));
}