Crate caretly 

Client for the Caretly API: render ZPL labels to PDF or PNG.

The crate has an async client, Client (feature async, on by default, for tokio), and a blocking client, blocking::Client (feature blocking). Both take the same RenderOptions, return the same RenderResult and fail with the same Error.

Features

Feature	Default	What it adds
async	yes	Client, the async client for tokio.
rustls-tls	yes	HTTPS through rustls.
blocking	no	blocking::Client, usable without an async runtime.
native-tls	no	HTTPS through the platform’s TLS library.
gzip	no	RenderOptions::compress: gzip the request body.

Without rustls-tls or native-tls the client can only reach http:// URLs.

API key

The key is read from the CARETLY_API_KEY environment variable unless you pass one to the builder. Test keys (zpl_test_…) are free and watermark every label. Self-hosted servers run without keys.

Async example

use caretly::{Client, Format, RenderOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder().api_key("zpl_test_...").build()?;

    let pdf = client.render_pdf("^XA^FO50,50^A0N,40^FDHello^FS^XZ").await?;
    println!("{} page(s), {} label(s) billed", pdf.page_count, pdf.labels_billed.unwrap_or(0));
    pdf.save("label.pdf")?;

    let png = client
        .render("^XA^FO50,50^A0N,40^FDHello^FS^XZ", RenderOptions::new().format(Format::Png).page(1))
        .await?;
    png.save("label.png")?;
    Ok(())
}

Blocking example

use caretly::blocking::Client;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new()?; // reads CARETLY_API_KEY
    let pdf = client.render_pdf("^XA^FO50,50^A0N,40^FDHello^FS^XZ")?;
    pdf.save("label.pdf")?;
    Ok(())
}

Errors and retries

Error statuses map to variants of Error (BadRequest, Authentication, RateLimited, …), each with the status, the server’s message and Retry-After.

A 429, a 503 or a connection error is retried up to max_retries times (default 2), waiting Retry-After when the server sends it and otherwise 0.5 s, 1 s, 2 s, … up to 8 s. When retries are on and you did not set an idempotency key, the client generates one per call, so a retried request is never billed twice.

Modules

blockingblocking

The blocking client, for programs without an async runtime.

Structs

ApiError

Details of an error response from the API.

Clientasync

Asynchronous client for the Caretly API, for use on a tokio runtime.

ClientBuilderasync

Builder for Client, created with Client::builder.

RateLimit

The API key’s rate limit state after this request.

RenderOptions

Options for a render call. Every option left unset is omitted from the request, so the server’s default applies.

RenderResult

A rendered PDF or PNG with the metadata from the response headers.

Enums

Dpmm

Printer resolution in dots per millimetre.

Error

Everything that can go wrong when calling the Caretly API.

Format

The output format.

Constants

MAX_IDEMPOTENCY_KEY_LEN

The longest Idempotency-Key the API accepts.

Type Aliases

BoxError

A boxed error from the HTTP transport, kept opaque so the public API does not depend on the HTTP library’s error type.

Result

A Result whose error is Error.