TypeScript SDK

npm install https://smolmac.com/sdk/smolmac-api-0.1.0.tgz

import { Smol } from "@smolmac/api";

const apiKey = process.env.SMOL_API_KEY;
if (!apiKey) throw new Error("SMOL_API_KEY is not set");

const smol = new Smol({ apiKey });

import { readFile, writeFile } from "node:fs/promises";

const photo = await readFile("photo.jpg");

// Compress. Options are the same object as everywhere else in the API.
const out = await smol.compress(photo, {
  filename: "photo.jpg",
  image: { format: "avif", quality: 60, resize: { width: 1200 } },
});
await writeFile(out.filename ?? "photo.avif", out.data);
console.log(out.result.savings_percent, out.billed);

// Convert to another format.
const webp = await smol.convert(photo, "webp", { filename: "photo.jpg" });

// Remove metadata without re-encoding.
const clean = await smol.stripMetadata(photo, { filename: "photo.jpg" });

const { job, data } = await smol.run("convert", await readFile("report.docx"), {
  filename: "report.docx",
  options: { convert: { to: "pdf" } },
});
await writeFile("report.pdf", data);
console.log(job.id, job.result?.output_size);

import { randomUUID } from "node:crypto";

// 1. Upload. Returns the upload id.
const uploadId = await smol.uploads.upload(await readFile("scans.pdf"), "scans.pdf");

// 2. Create the job. The second argument is optional.
const created = await smol.jobs.create(
  {
    operation: "compress",
    input: { upload: uploadId },
    options: { pdf: { quality: "small" } },
    retention_seconds: 600,
    metadata: { document_id: "doc_1234" },
  },
  { idempotencyKey: randomUUID() },
);

// 3. Wait for a final status.
const job = await smol.jobs.wait(created.id, { timeoutMs: 10 * 60_000 });
if (job.status !== "succeeded") throw new Error(`${job.error?.code}: ${job.error?.message}`);

// 4. Download, then delete the files on our side without waiting for them to expire.
const data = await smol.jobs.download(job);
await smol.jobs.delete(job.id);

const uploadId = await smol.uploads.upload(await readFile("talk.mov"), "talk.mov");

const job = await smol.jobs.create({
  operation: "compress",
  input: { upload: uploadId },
  options: { video: { codec: "h264", resolution: "1920" } },
  webhook_url: "https://example.com/smol/webhook",
});

await smol.presets.put("web-hero", { image: { format: "avif", quality: 60, resize: { width: 1600 } } });

// On a direct request. Options sent with the request override the preset field by field.
const hero = await smol.compress(photo, { preset: "web-hero", filename: "photo.jpg" });
const sharper = await smol.compress(photo, { preset: "web-hero", image: { quality: 80 } });

// On a job.
const { data } = await smol.run("compress", photo, { preset: "web-hero", filename: "photo.jpg" });

// The current month so far.
const month = await smol.usage();
console.log(month.totals.requests, month.totals.amount_usd);

// A range of days, in UTC. Both ends are included.
const range = await smol.usage({ from: "2026-10-01", to: "2026-10-07" });
for (const day of range.daily) console.log(day.day, day.meters);

const estimate = await smol.estimate({
  operation: "compress",
  filename: "talk.mov",
  size: 262_144_000,
  duration_seconds: 150, // needed for audio and video
  width: 1920,
  height: 1080,
  options: { video: { codec: "h264" } },
});
console.log(estimate.lane, estimate.meter, estimate.quantity, estimate.amount_usd, estimate.notes);

import express from "express";

const app = express();

app.post("/smol/webhook", express.text({ type: "application/json" }), async (req, res) => {
  let event;
  try {
    event = await smol.webhooks.verify(req.body, req.get("Smol-Signature") ?? null, process.env.SMOL_WEBHOOK_SECRET ?? "");
  } catch {
    return res.status(400).send("invalid signature");
  }

  if (event.type === "job.succeeded") {
    // Queue the work, then answer.
    console.log(event.data.job.id, event.data.job.result?.download_url);
  }
  res.status(204).end();
});

const endpoint = await smol.webhookEndpoints.create("https://example.com/smol/webhook");
console.log(endpoint.id, endpoint.secret); // the secret is shown only here

// Send a signed ping and see what your endpoint answered.
const test = await smol.webhookEndpoints.test(endpoint.id);
console.log(test.delivered, test.status, test.duration_ms);

await smol.webhookEndpoints.update(endpoint.id, { enabled: false }); // pause
await smol.webhookEndpoints.update(endpoint.id, { enabled: true }); // resume

const rotated = await smol.webhookEndpoints.rotateSecret(endpoint.id);
console.log(rotated.secret); // the new secret, shown only here

import { SmolError } from "@smolmac/api";

try {
  await smol.compress(photo, { image: { quality: 120 } });
} catch (error) {
  if (error instanceof SmolError) {
    console.error(error.status, error.code, error.param, error.message, error.requestId);
  } else {
    throw error; // a network failure, after the retries
  }
}

const smol = new Smol({
  apiKey,
  fetch: (input, init) => fetch(input, { ...init, signal: AbortSignal.timeout(150_000) }),
});