Introduction
The server-side TypeScript SDK for inklet e-ink displays — push text, links, images, and PDFs, and let inklet handle layout, routing, and rendering.
@inklethq/sdk is the server-side client for inklet displays. You hand it
something worth showing — a sentence, a link, a chart, a PDF — and inklet
summarises it, decides which panel should carry it, lays it out, and renders
it for e-ink.
import { Inklet } from "@inklethq/sdk";
const inklet = new Inklet({ pat: process.env.INKLET_PAT! });
await inklet.push.auto({
title: "Daily brief",
intent: "Make the key update easy to scan",
assets: [
inklet.assets.text("Revenue is up 12% week over week."),
inklet.assets.link("https://example.com/report"),
],
});A personal access token is a server credential. The SDK refuses to construct
a client in any environment with a document, so a token cannot reach a
browser bundle by accident. See Authentication.
The five nouns
Everything in the API is one of these.
| Noun | What it is |
|---|---|
| Display | A physical panel bound to your account. It reports battery, firmware, tags, and the geometry and formats it can render. |
| Asset | One piece of raw input: text, a link, an image, or a file. Assets are validated locally before anything is sent. |
| Content | A submission — a set of assets. It is storage, not work; it is pending until its assets land, then ready. |
| Analysis | One agent run over some Contents, the user's history, or both. It is what actually reads, plans, renders, and delivers. |
| Presentation | One finished frame — for a Display, or display-free Scene JSON and PNG renditions. |
The shape of a normal day: you upload a Content made of Assets, start an Analysis over it, and inklet produces one or more Presentations that a Display picks up the next time it wakes.
Uploading spends nothing. The Analysis is the call that does the work.
Three ways to push
inklet.push.* is one call for the common case — upload a Content, then
analyze it — and the three methods differ in how much of the decision you keep.
Auto
inklet chooses the displays and the layout.
Manual
You choose the display; inklet still sets the type.
Hardcode
You supply the finished image.
Reach past them — contents.upload() and
analyses.analyze() — when you want to analyze the user's
history, target several displays, or render without a panel at all.
Requirements
- Node.js 22 or newer — the SDK uses the global
fetch,Blob,FormData, andAbortSignal - A trusted server environment
- A personal access token from the Portal dashboard
ESM and CommonJS builds ship together, each with its own TypeScript
declarations; you do not need a @types package. The SDK is MIT licensed.
Versioning
The SDK is pre-1.0. A minor release (0.3 → 0.4) can break the API and
lists each break under Breaking in the
changelog; a patch
release does not. npm's default ^0.3.0 range already stays on 0.3.x.
Fields inklet reports as a fixed set of words — a state, a mode, a
format, an event's type — are typed as the values the SDK knows plus any
other string. When inklet adds a value, an installed SDK reads it through
instead of failing, so compare against the values you handle and keep a
default branch:
switch (analysis.state) {
case "completed":
case "failed":
return analysis;
default:
return undefined; // queued, running, or something newer: not finished
}The waiting helpers treat a state they do not know as not finished yet.