sdk-ts — the TypeScript client

Lemonfiber — sdk-ts

@lemonfiber/sdk-ts: a TypeScript client for the web API that lemonfiber serves on your machine. For anyone writing a script, tool or web page that reads or controls a lemonfiber media stack.

---

It gives you typed calls, a typed live event stream and typed errors, with no runtime dependencies. It runs in Node and in the browser, and it only talks to a lemonfiber running on the same machine.

Not on npm. There is no release yet; install it from GitHub at a commit.

Requirements

• Node 26 or newer, or a current browser.
• lemonfiber, serving its web API with lemonfiber ui on the same machine.

Install

Pin a commit from the commit list:

npm install github:lemonfiber/sdk-ts#<commit>

npm builds the package as it installs it.

Quick start

Start lemonfiber’s web API. It prints the address and a token for this run:

$ lemonfiber ui --port 9000 --no-browser
lemonfiber is serving at:
  http://[::1]:9000
  http://127.0.0.1:9000
…
The token for this run, which the page will ask you for:
  <token>

Then ask it how the stack is doing. Save this as status.ts:

import { Client } from "@lemonfiber/sdk-ts";

const opened = Client.at({
  url: "http://127.0.0.1:9000",
  token: process.env.LEMONFIBER_TOKEN ?? "",
  sending: fetch,
});
if (!opened.ok) throw new Error(opened.problem.message);

const status = await opened.client.read("status");
if (!status.ok) throw new Error(status.problem.message);
console.log(status.value.data.condition, status.value.data.active_forms);

Run it with the token lemonfiber printed:

$ LEMONFIBER_TOKEN=<token> node status.ts
active [ 'library' ]

That is the output with only the library form running and healthy. A form is a named part of the stack, such as library or tv; see forms.

Nothing throws for an expected failure: every call returns either { ok: true, value } or { ok: false, problem }, and problem.message is a sentence you can show a person.

Where to go next

• The guide: actions, files, the live event stream, every kind of problem, refusal codes and version handling.
• The web API: the envelope every answer arrives in, every payload kind and the field-by-field reference.
• The command reference: every read and action is a command, and takes the same arguments.

Contributing

npm ci        # installs, builds and turns on the git hooks
npm run ci    # format, lint, types, guards, contract check, tests at 100% coverage, build

src/generated/ is generated from lemonfiber’s contract and never edited by hand; the guide says how to regenerate it. Every change cites a requirement in the specification; start with the contributing guide. Changes are listed in CHANGELOG.md.

Security

Report a vulnerability privately, as the security policy describes. Do not open a public issue.

Licence

Hippocratic License 3.0: source-available and ethical-source, not OSI-approved. The licence rationale explains what that means for you. Made by NightWorksIO.

---

 ·