lt4c-sdk

TypeScript/JavaScript SDK for the LT4C Daemon API. The client works in Node.js services, browser dashboards (with a compatible fetch), and lightweight edge workers. It ships as a dual ESM + CommonJS package so it can be consumed from modern bundlers as well as legacy require-based code.

Features

• Lt4cClient wrapper for every documented daemon endpoint
• Built-in authentication via X-DAEMON-TOKEN
• Strict URL handling so baseUrl + relative paths never double up
• File/folder helpers with ~/~/path shortcuts, UTF-8/Base64 conversion, and binary reads
• pollStatus and tailLogs utilities for higher-level workflows
• Fully typed responses + error model (Lt4cApiError)
• Tested with Vitest + MSW, bundled by tsup, linted via ESLint

Installation

npm install lt4c-sdk

Token management & security

The daemon exposes a single bearer-style token that must be attached to every request. The SDK reads this from your code; the daemon does not provide a login exchange.

• The token is stored at LT4C_TOKEN_PATH (file path). Your service is responsible for reading it (e.g., using fs.readFileSync).
• Never ship daemon tokens to untrusted browser clients. For dashboards, proxy requests through a backend that injects the token.

Example helper:

import fs from "node:fs";

function readDaemonToken(): string {
  const tokenPath = process.env.LT4C_TOKEN_PATH ?? "/var/run/lt4c/token";
  return fs.readFileSync(tokenPath, "utf8").trim();
}

Usage

Node.js (ESM)

import { Lt4cClient } from "lt4c-sdk";

const client = new Lt4cClient("http://localhost:8080", readDaemonToken(), {
  timeout: 30_000,
  userAgent: "my-service/1.2.3",
});

Node.js (CommonJS)

const { Lt4cClient } = require("lt4c-sdk");

const client = new Lt4cClient(process.env.LT4C_BASE_URL, readDaemonToken());

Browser / Edge runtimes

import { Lt4cClient } from "lt4c-sdk";
import fetch from "cross-fetch";

const client = new Lt4cClient(baseUrl, token, { fetchImpl: fetch });

Creating a box

const box = await client.createBox({
  userId: "demo-user",
  image: "node:18",
  internalPort: 3000,
  command: "npm start",
  resourceLimits: { cpu: 0.5, memoryMb: 512 },
});

The client maps these camelCase fields to the daemon's expected payloads (docker_image, resource_limits, string command, etc.), matching the LT4C Daemon API Lab HTML tool.

Fetching status

const status = await client.getStatus(box.id);
if (status.status === "RUNNING") {
  console.log("ready");
}

Reading / writing files

await client.writeFile(box.id, "~/app/index.js", "console.log('hi');", "utf8");
const contents = await client.readTextFile(box.id, "~/app/index.js");

writeFile first attempts PATCH and, if the daemon returns 404, falls back to POST. Binary payloads should pass Uint8Array and specify encoding: "base64"; the helper automatically base64-encodes the bytes.

Polling for RUNNING

await client.pollStatus(box.id, {
  intervalMs: 1000,
  timeoutMs: 120_000,
  until: (payload) => payload.status === "RUNNING" || payload.status === "ERROR",
});

Tailing logs

const abort = new AbortController();
for await (const batch of client.tailLogs(box.id, { signal: abort.signal, limit: 100 })) {
  for (const line of batch) {
    console.log(`[${line.timestamp}] ${line.message}`);
  }
}

Health checks

const health = await client.health();
if (health === true || health.status === "ok") {
  console.log("daemon reachable");
}

Examples

• examples/create-box.ts: minimal CLI that creates a box and waits for RUNNING.
• examples/tail-logs.ts: CLI log tailer (Ctrl+C to stop).
• examples/sdk-lab.html: browser playground for all Lt4cClient helpers. Run npm run build, then serve examples/ (e.g., npx serve examples) so the page can import ../dist/index.js.

Run with ts-node or compile first:

npx ts-node examples/create-box.ts

File/folder API semantics

• Paths accept ~, ~/sub/path, ., and / prefixes. They normalize to root-relative segments so requests hit /boxes/{id}/files/... exactly like the HTML lab helper.
• Folder rename payloads follow { new_path: "<relative-path>" }, so the SDK simply sanitizes segments before sending the value.
• File GET responses are expected to look like { path, type, encoding, contents }; directories can return { children: [...] }. When encoding === "base64", the SDK decodes to UTF-8 (for readTextFile) or bytes (for readBinaryFile).

API coverage

| Endpoint | Helper | | --- | --- | | POST /boxes | createBox | | GET /boxes | listBoxes | | GET /boxes/:id | getBox | | PATCH /boxes/:id | updateBox | | DELETE /boxes/:id | deleteBox | | GET /boxes/:id/logs | getLogs, tailLogs | | PATCH /boxes/:id/command | updateCommand | | PATCH /boxes/:id/domain | updateDomain | | GET /boxes/:id/ports | getPorts | | GET /boxes/:id/status | getStatus, pollStatus | | GET /boxes/:id/files/* | browsePath, readTextFile, readBinaryFile | | POST/PATCH/DELETE /boxes/:id/files/* | createFile, updateFile, writeFile, deleteFile | | POST/PATCH/DELETE /boxes/:id/folders/* | createFolder, renameFolder, deleteFolder | | GET /healthz | health |

Building & testing

npm install
npm run lint
npm test
npm run build

• tsup builds both ESM (dist/index.js) and CommonJS (dist/index.cjs) bundles plus declarations.
• vitest + msw cover client configuration, error handling, boxes/files flows, utilities, and log polling.
• eslint (with @typescript-eslint + import rules) keeps the codebase consistent.

CI/CD

Two GitHub Actions workflows are included:

• .github/workflows/ci.yml – runs on pushes / PRs targeting main with a Node 18/20 matrix. Steps: checkout ? setup-node (with caching) ? npm ci ? npm run lint ? npm test ? npm run build.
• .github/workflows/release.yml – runs on tags that match v*.*.*. Installs deps, runs tests + build, then executes npm publish --access public (requires NPM_TOKEN secret).

Publishing & versioning

1. Update CHANGELOG.md (recommended sections: Added, Changed, Fixed, Breaking).
2. Bump the version in package.json using SEMVER:
   • MAJOR – backward-incompatible changes.
   • MINOR – new backwards-compatible features.
   • PATCH – bug fixes.
3. Commit, tag vX.Y.Z, push. The release workflow builds/tests and publishes when NPM_TOKEN is configured.
4. Manual publish alternative:

npm login
npm publish --access public

Assumptions

• Box schema includes id, docker_image, user_id, status, timestamps, optional string command, domain, resource_limits, ports, and internal_port metadata.
• File browsing returns FileNodeResponse objects with type: "file" | "directory", optional encoding, contents, and nested children for directories.
• Log endpoints support limit and sinceId query params.
• Folder rename payloads use { new_path: "src/ui" } (no implicit /home prefix).
• Response bodies can include requestId, responseId, or id to identify the request; all are captured on Lt4cApiError.

If the live daemon deviates from these assumptions, adjust the corresponding types and helper payloads.

Example CLI scripts

• node examples/create-box.js – create + wait for a box (after compiling or using ts-node).
• node examples/tail-logs.js <boxId> – stream logs until Ctrl+C.

OpenAPI

An approximate openapi.json can be produced later if LT4C publishes a formal spec. Until then, the TypeScript types (src/types.ts) document the schema that informed the SDK.