@zencomms/media

Image compression utilities for ZenComms — shrinks images to fit MMS carrier byte caps (default 1 MB) using iterative quality reduction via sharp.

Install

pnpm add @zencomms/media

Usage

import { compressForMms } from '@zencomms/media';
import { readFileSync } from 'node:fs';

const input = readFileSync('photo.jpg');
const result = await compressForMms(input);

if (result.ok) {
  const { buffer, format, width, height, bytesBefore, bytesAfter } = result.value;
  console.log(`Compressed ${bytesBefore} → ${bytesAfter} bytes as ${format} (${width}x${height})`);
} else {
  console.error(result.error.code, result.error.message);
}

Optional second argument accepts CompressOpts:

await compressForMms(input, {
  maxBytes: 600_000,   // default: 1_048_576 (1 MB)
  maxWidth: 1200,      // default: 1600
  maxHeight: 1200,     // default: 1600
  targetFormat: 'webp', // 'jpeg' | 'webp' — default: 'jpeg'
  minQuality: 50,      // default: 40 — floor for iterative quality descent
});

Error codes

| Code | Status | Description | |---|---|---| | MEDIA_EMPTY_INPUT | 400 | Input buffer is empty or falsy | | MEDIA_UNSUPPORTED_FORMAT | 415 | Source format not in allowlist (jpeg/png/webp/tiff/gif/avif/heif) or animated | | MEDIA_DECODE_FAILED | 422 | sharp could not decode or encode the image | | MEDIA_UNCOMPRESSIBLE | 422 | Image could not be compressed below maxBytes at minQuality | | MEDIA_INVALID_OPTIONS | 500 | Invalid CompressOpts values (e.g. maxBytes <= 0) |

Peer dependencies

Requires @zencomms/core (Result type) and sharp (bundled as a direct dependency — no separate install needed).

License

MIT — see LICENSE.