Example Code

This page collects small code samples that show how to talk to the coldwave backend from different environments.

For complete, up-to-date example projects, see the official GitHub repositories referenced here. For the overall architecture and recommended patterns, refer to the Application Developer Guide and the module guides (IAM, Websocket & Events, Service, Schema, Metadata, …).

---

Node.js (TypeScript) – Websocket client

The following minimal Node.js example shows how to:

• log in and obtain a token,
• request a websocket ticket,
• open a websocket connection,
• log all received events.

For a more complete example (better error handling, token refresh, graceful shutdown, etc.), see the GitHub repository:

• https://github.com/io-coldwave/coldwave-example-nodejs

TIP

Error handling is intentionally simplified here to keep the core logic visible. In real code, add proper retries, logging and token expiry handling.

config.ts

Configure the required parameters here:

// filename: config.ts

export const USER = "<<USERNAME>>";
export const PASSWORD = "<<PASSWORD>>";
export const URL = "<<URL>>"; // e.g. "backend.example.com"

utils.ts

Small utility to parse the response from an API call:

// filename: utils.ts

import { Response } from "node-fetch";

export async function extractObject<T extends Record<string, unknown>>(
  response: Response
): Promise<T | null> {
  if (!response.ok) {
    console.log(`Response status was ${response.status} - NOT_OK`);
    return null;
  }
  try {
    const json = await response.json();
    return json as T;
  } catch (e) {
    console.error("Unable to parse json from response");
  }
  return null;
}

token.ts

The code that handles the login part of the application. Note that the token will expire after a period of time; this example does not handle token expiration at all.

// filename: token.ts

import fetch from "node-fetch";
import { PASSWORD, USER, URL } from "./config";
import { extractObject } from "./utils";

// The token will expire at some point
let token: string | null = null;

export async function getToken(): Promise<string | null> {
  if (token !== null) return token;

  const authHeader =
    "Basic " + Buffer.from(USER + ":" + PASSWORD).toString("base64");

  const requestOptions = {
    method: "GET",
    headers: {
      Authorization: authHeader,
    },
  };

  const res = await fetch(`https://${URL}/api/v1/iam/token`, requestOptions);
  const parsed = await extractObject<{ token: string }>(res);
  if (parsed !== null) {
    token = parsed.token;
  }
  return token;
}

fetch.ts

Wrapper that adds the token to a fetch request and a helper that generates a websocket ticket.

// filename: fetch.ts

import fetch, { RequestInfo, RequestInit, Response } from "node-fetch";
import { getToken } from "./token";
import { extractObject } from "./utils";
import { URL } from "./config";

export async function fetchWithToken(
  input: RequestInfo | URL,
  init?: RequestInit
): Promise<Response> {
  const _init = init || {};
  const token = await getToken();
  if (token !== null) {
    _init.headers = Object.assign(
      {},
      { Authorization: `Bearer ${token}` },
      init?.headers
    );
  }
  return fetch(input, _init);
}

export async function getWebsocketTicket(): Promise<string | null> {
  const res = await fetchWithToken(`https://${URL}/api/v1/events/ticket`);
  const obj = await extractObject<{ ticket: string }>(res);
  if (obj && "ticket" in obj) {
    return obj.ticket;
  }
  return null;
}

index.ts

The entry point that retrieves a websocket ticket and opens a websocket connection. Incoming events are printed to the console.

// filename: index.ts

// npm install ws node-fetch
import { WebSocket } from "ws";
import { URL } from "./config";
import { getWebsocketTicket } from "./fetch";

(async () => {
  const ticket = await getWebsocketTicket();
  if (!ticket) {
    console.error("Unable to obtain websocket ticket");
    process.exit(1);
  }

  const ws = new WebSocket(`wss://${URL}/api/v1/events/${ticket}`);

  ws.on("open", () => {
    console.log("Websocket connected");
  });

  ws.on("message", (data) => {
    console.log("received:", data.toString());
  });

  ws.on("close", (code, reason) => {
    console.log("websocket closed:", code, reason.toString());
  });

  ws.on("error", (err) => {
    console.error("websocket error:", err);
  });
})();

---

Other languages

For other languages and environments (browser SPAs, Python, Go, etc.), use the same building blocks:

1. Obtain a token (or API key) via IAM.
2. Call REST endpoints under https://<<URL>>/api/v1/... with the appropriate headers.
3. Optionally open a websocket connection via /api/v1/events/ticket and route events by their type field.

Language-specific examples can be added here over time. For now, use the module docs plus the Application Developer Guide as your primary references and adapt the Node.js example to your stack.