@inklethq/sdk

Official server-side JavaScript and TypeScript SDK for Inklet.

The v0.1 release supports PAT authentication, Display and Presentation reads, Content lifecycle operations, and high-level Auto, Manual, and Hardcode Push workflows.

Requirements

• Node.js 20 or newer
• An Inklet personal access token (PAT)
• A trusted server environment

Never expose a PAT in a browser bundle. The SDK rejects browser use before a request is sent.

Install

npm install @inklethq/sdk

Initialize

import{Inklet}from"@inklethq/sdk";constinklet=newInklet({pat: process.env.INKLET_PAT!,});

CommonJS is supported too:

const{ Inklet }=require("@inklethq/sdk");constinklet=newInklet({pat: process.env.INKLET_PAT});

secretKey remains available as a compatibility alias for pat; do not pass both options. Client construction validates configuration without making a network request.

The default service address is https://dev.iminklet.com. A controlled local or test service can be selected with baseUrl.

Displays and Presentations

constpage=awaitinklet.displays.list({limit: 20});constdisplay=awaitinklet.displays.retrieve(page.items[0].id);constqueue=awaitinklet.displays.listQueue(display.id,{from: newDate("2026-08-01T00:00:00Z"),limit: 20,});constcurrent=awaitinklet.displays.current(display.id,{format: "png"});if(current){constpresentation=awaitinklet.presentations.retrieve(current.id,{format: "raw2",});}

displays.current() is read-only and returns null when the Display has no confirmed Presentation.

Push

Asset helpers validate supported content types and the 10 MiB per-binary-asset limit. Binary assets are uploaded directly to temporary storage URLs; the PAT is sent only to Inklet API endpoints.

Auto

Auto Push lets Inklet choose compatible Displays.

constresult=awaitinklet.push.auto({idempotencyKey: "daily-brief-2026-08-12",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"),],});

Manual

Manual Push targets one Display while allowing Inklet to process and lay out the supplied assets.

import{readFile}from"node:fs/promises";constimage=inklet.assets.image({data: awaitreadFile("chart.png"),filename: "chart.png",contentType: "image/png",});constresult=awaitinklet.push.manual({displayId: "display_123",assets: [image,inklet.assets.text("This week's trend")],});

Hardcode

Hardcode Push targets one Display and accepts exactly one PNG or JPEG. Inklet keeps the existing server behavior: it automatically scales the submitted image to the Display output size. The SDK intentionally does not require the source image dimensions to match the panel.

import{readFile}from"node:fs/promises";constresult=awaitinklet.push.hardcode({displayId: "display_123",image: inklet.assets.image({data: awaitreadFile("poster.jpg"),filename: "poster.jpg",contentType: "image/jpeg",}),});

All high-level Push methods return the Content, generated idempotency key, and known Presentation IDs. When idempotencyKey is omitted, the SDK generates one and returns it in the result. For caller-controlled retries, supply and reuse your own key.

Push processing is asynchronous. A successful call commonly returns a processing Content with no Presentation IDs yet. Poll inklet.contents.retrieve(result.contentId) until the Content becomes ready or failed. A ready Content means its Presentation IDs are persisted; an individual Presentation may briefly remain preparing while the render worker finishes the PNG, RAW2, and RAW4 files.

Content lifecycle

The lower-level Content resource is available when an application needs to control individual lifecycle calls:

constcontent=awaitinklet.contents.retrieve("content_123");constcontents=awaitinklet.contents.list({mode: "manual",state: "ready"});constconfirmed=awaitinklet.contents.confirm(content.id);

contents.create() and contents.refreshUploadTickets() are also public, but most applications should use inklet.push.*, which handles upload tickets, one ticket refresh/retry, and confirmation.

Errors

Every SDK error extends InkletError. Backend error codes, status, request ID, and structured details are preserved.

import{AuthenticationFailedError,InkletError,RateLimitError,}from"@inklethq/sdk";try{awaitinklet.displays.list();}catch(error){if(errorinstanceofAuthenticationFailedError){// Replace or reactivate the PAT.}elseif(errorinstanceofRateLimitError){// Retry according to your application policy.}elseif(errorinstanceofInkletError){console.error(error.code,error.requestId,error.details);}}

Authenticated requests refuse absolute URLs and cross-origin redirects. Credentials are redacted from errors, and storage uploads never include the PAT.

Development

npm ci
npm run check
npm run pack:check

npm run check builds ESM and CommonJS output, runs strict TypeScript checks, and executes the test suite.