Skip to navigation

SDKs

The TypeScript and Python packages, how to install them and what a job looks like.
View as Markdown

The SDKs are generated from the API contract. They are pre-1.0: method names can still change before 1.0, so pin the version you use. Both packages are MIT licensed. Anything the SDK does not cover, the HTTP API does.

LanguagePackageInstall
TypeScript@tillcast/sdknpm install @tillcast/sdk
Pythontillcastpip install tillcast

The old npm package named tillcast is empty. It only points to @tillcast/sdk.

The API prints on real paper

A key prints on real printers, and a client built with only a key calls the live API. Keep the key in an environment variable, never in code, and test with the printer you mean to print on. See Which server the SDK calls.

Send a job

import { TillcastClient } from "@tillcast/sdk";
const client = new TillcastClient({ token: process.env.TILLCAST_API_KEY! });
const job = await client.jobs.create({
printer: process.env.TILLCAST_PRINTER_ID!,
"Idempotency-Key": "order-4713-bill",
document: [
{ type: "text", text: "Harbour Cafe", align: "center", bold: true, size: 2 },
{ type: "text", text: "Table 7", align: "center" },
{
type: "table",
columns: ["*", { width: 9, align: "right" }],
rows: [
["Flat white", "3.40"],
{ type: "rule" },
[{ text: "Total", bold: true }, { text: "3.40", bold: true }],
],
},
],
client_reference_id: "order-4713",
});
console.log(job.id, job.status, job.warnings);

An Idempotency-Key makes a retry safe: the same key answers the first job and prints nothing more. See Create a print job for the whole call, Idempotency and Integrate a point of sale.

The document is an array of blocks. To send ReceiptLine text, use the field receiptline instead of document, with a string.

Which server the SDK calls

Both packages call the live API, https://api.tillcast.com, unless you say otherwise, and a job they create prints on a real printer. Tillcast has no test server: there is no sandbox and no staging API.

To send the calls to another address, for example a stand-in server of your own in automated tests, set the base URL when you build the client: baseUrl in TypeScript and base_url in Python. Write the address without /v1, because the SDK adds the path of every call. With /v1 at the end, every call is 404 route_not_found.

import { TillcastClient } from "@tillcast/sdk";
function requireEnv(name: string): string {
const value = process.env[name];
if (!value) throw new Error(`${name} is not set`);
return value;
}
const client = new TillcastClient({
token: requireEnv("TILLCAST_API_KEY"),
baseUrl: requireEnv("TILLCAST_BASE_URL"),
});

A missing base URL is not an error. baseUrl: undefined in TypeScript and base_url=None in Python both mean the live API, so a client in a test that forgot the setting prints on paper. Read the address as above, so that a missing setting stops the program, and set TILLCAST_BASE_URL=https://api.tillcast.com in production. In unit tests, do not build a client at all: pass your code a fake client of your own. Never call the live API from a test or from an agent unless the owner of the key gave you the key and named the printer.

The README of the packages

The README is the first page of a package on npm and PyPI. From version 0.2.1, the README of both packages leads with creating a print job:

  1. How to install the package, where to get an API key and how to build the client with token.
  2. Create a print job: a short receipt as blocks, with a centred title, a table, a rule and a total, and the same receipt as ReceiptLine text in receiptline.
  3. Retry safely: the idempotency key, which is idempotency_key in Python and the property "Idempotency-Key" in TypeScript, and how to see a replay.
  4. Read a job back with jobs.get and its status, and where the printer id comes from.
  5. A refused document: 422 document_invalid, and how to read the param of the error.

The rest of the README is what Fern generates for every SDK: the environments, the async client of Python, retries and timeouts. Versions 0.2.0 and earlier have only that generated README, and its one example is customers.create, which is not a job. The code of a package does not change with its README. The page Create a print job has the same call with cURL and more.

Version 0.2.0 and blocks

The job body changed on 2026-10-16: document was an object, {"type": "receiptline", "content": "..."}, and is now an array of blocks. Version 0.1.1 of both packages sends the object, and the API answers 400 parameter_invalid. Version 0.2.0 and later send the array. Update the package and change the call. See the changelog.

  • TypeScript. type picks the kind of block, and the editor offers the fields of that kind. A field that a kind does not have, a misspelled field and a value of the wrong kind are errors of the compiler. The type of a block is Tillcast.Block: give a document that you build in a variable this type, or the compiler reads type: "text" as a string.
  • Python. The parameters of a request that are objects are dicts (TypedDicts), so write the blocks as plain dicts, as above, and a type checker like pyright checks them. This also holds for print_options: the model classes of 0.1.1, such as PrintOptions(...), are not accepted by a type checker in a request. The type of a block is BlockParams, for a function that returns a document. The answers are still objects: job.id, job.warnings.
  • Neither or both. document and receiptline are both optional in the types, so neither the compiler nor the type checker can see that a call has neither or both. The API answers 422 document_invalid.

Notes

  • The names of the fields are the names of the API (client_reference_id, expires_in, and in a barcode module_width). In Python the header is the argument idempotency_key; in TypeScript it is the property "Idempotency-Key".
  • Errors are exceptions that carry the status and the error body. A 422 is Tillcast.UnprocessableEntityError in TypeScript and UnprocessableEntityError in Python, and its body.error has the code, the param and the request_id. See Errors. The TypeScript error also has a property requestId, but it reads the header x-request-id, and the API sends Request-Id, so it is undefined. Read err.body.error.request_id (the same value) in both languages, or err.rawResponse.headers.get("request-id") in TypeScript. An error with no answer behind it, such as a timeout or a refused connection, has no request id.
  • Both packages retry a request twice, with a growing wait, when Tillcast answers 408, 429 or a 5xx (Python also 409). They wait for the Retry-After of the answer, up to 60 seconds, so a queue_full (Retry-After: 30) can hold one call for about a minute. They do not retry a timeout or a dropped connection, the cases where the job may already exist: send the same request again yourself, with the same Idempotency-Key and body. Set maxRetries (TypeScript) or max_retries (Python) to 0 to turn the waits off. See Retry safely.
  • Both packages call the live API, https://api.tillcast.com, by default. Set baseUrl (TypeScript) or base_url (Python), without /v1, to call another address. See Which server the SDK calls.