Lemonfiber
← The specification

Repo: sdk-ts

Rendered from spec at76d46f3 (2026-10-25) · its source · Edit this page

Status: Accepted

The TypeScript client for lemonfiber’s web API, packaged as @lemonfiber/sdk-ts. Consumers take it as a commit-pinned git dependency; registry publication waits on a stable major, as it does for sdk-php. TypeScript, Hippocratic 3.0.

Implements: the client half of the web API contract.

What this repo is

A library with no user interface and no server. It speaks the web API and exposes it as typed calls, a typed event stream, and a typed error. It is the first thing any consumer of the API should reach for, and the only thing lemonfiber-web uses to talk to the core.

Named for the language rather than the product (ADR-0013), so sdk-py and sdk-rs need no renaming. Each is a peer implementation of one specification. The spec is the reference; an SDK that disagrees with the contract is wrong.

What it owns

Piece Obligation
envelope The { api_version, kind, data } shape, and refusing a version it cannot speak (ARCH-R46, ARCH-R55)
client One method per endpoint, mirroring the commands (ARCH-R47)
actions POST /api/actions/<name>, and following a job to completion (ARCH-R48)
events The stream: heartbeat detection (ARCH-R50), resumption, and marking pre-gap values stale (ARCH-R51)
problem The error model, in the language G2 requires

Also the token: supplied by the caller, sent as a header, never placed in a URL (ARCH-R52).

And the address: loopback only, with no pinned exception. ARCH-R99 lets a client reach a non-loopback stack when it holds a certificate pin, and sdk-php takes that up for the companion. This one does not, and the reason is where it runs: a browser cannot resolve a name, has no pin to be given, and is the party ARCH-R60’s DNS-rebinding reasoning is about. The two SDKs are peers of one contract rather than copies of each other (ADR-0025), and this is the first place that distinction does work.

What it must not own

  • Rendering. No DOM, no components, no framework dependency. A consumer that is not a browser must be able to use it.
  • Policy. It reports what the core said. Deciding what to do about a stuck download is the core’s job, and displaying it is the surface’s.
  • State beyond the stream. It does not cache, reconcile or invent. A figure it has not been given is one it does not have.

Versioning

Two numbers doing different jobs, and conflating them is the mistake to avoid:

  • The package carries semver. Ordinary software, ordinary breaking changes.
  • api_version is a monotonic integer describing the wire (ARCH-R2).

The package declares which api_version it speaks. Many package versions may speak one wire version. That declaration is what ARCH-R54 validates against the binary at build time, surfaced through the application that embeds it.

Quality bar

The same standards as lemonfiber-web: 100% coverage across lines, statements, branches and functions; strict TypeScript with noUncheckedIndexedAccess and exactOptionalPropertyTypes; typescript-eslint strictTypeChecked with no warnings tolerated; no escape hatches.

Two obligations are specific to a published library: no runtime dependencies without a recorded reason, since a client library’s dependency tree becomes every consumer’s problem; and a changelog, since people pin it.