was-sticker 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thxmxx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# was-sticker
+
+[![CI](https://github.com/thxmxx/was-sticker/actions/workflows/ci.yml/badge.svg)](https://github.com/thxmxx/was-sticker/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/was-sticker.svg)](https://www.npmjs.com/package/was-sticker)
+
+Build WhatsApp animated stickers (`.was`) from an image plus a Lottie template — pure JS, no shell `zip` binary required.
+
+- ✅ **Zero shell dependencies** — uses [JSZip](https://stuk.github.io/jszip/), works on Linux, macOS, Windows, Termux.
+- ✅ **Async everywhere** — non-blocking I/O.
+- ✅ **Flexible inputs** — template can be a folder, a JSON file, a `Buffer`, or a parsed object.
+- ✅ **Flexible asset selection** — by index, asset id, or a predicate. Defaults to the first base64 image.
+- ✅ **Returns a `Buffer`** — feed it directly to Baileys without touching disk.
+- ✅ **MIME sniffing** — detects PNG/JPG/WEBP from extension *or* magic bytes.
+- ✅ **CLI included** — `npx was-sticker -i face.png -t ./template -o out.was`.
+
+## Install
+
+```bash
+npm install was-sticker
+```
+
+Requires Node.js ≥ 18.
+
+## Quick start
+
+```js
+import { buildLottieSticker, bundledTemplate } from 'was-sticker';
+
+const { buffer } = await buildLottieSticker({
+  image: 'face.png',
+  template: bundledTemplate('pulse'),
+});
+// → buffer is a ready-to-send `.was` sticker
+```
+
+The package ships with a `pulse` template (1-second scale pulse, 30 fps) so you can produce a sticker out of the box without sourcing a Lottie file.
+
+## API
+
+```js
+import { buildLottieSticker } from 'was-sticker';
+
+const { buffer, output, mime } = await buildLottieSticker({
+  image:    'face.png',                  // path | Buffer | { buffer, path, mime }
+  template: './templates/heart',         // folder | JSON path | Buffer | parsed object
+  output:   './out/heart.was',           // optional — omit to keep it in-memory
+  assetSelector: 0,                      // optional — number | string (id) | (asset) => boolean
+  jsonEntryName: 'animation/anim.json',  // optional — path inside the .was for the JSON
+  extraFiles: { 'meta.json': '{}' },     // optional — additional files to bundle
+});
+```
+
+| Input form          | What it does                                                |
+| ------------------- | ----------------------------------------------------------- |
+| `image: 'face.png'` | Reads file, sniffs MIME from extension and magic bytes.     |
+| `image: buffer`     | Sniffs MIME from magic bytes.                               |
+| `image: { buffer, mime }` | Trust caller-provided MIME.                           |
+| `template: './folder'` | Walks folder; treats `*.json` as the Lottie, bundles the rest. |
+| `template: './lottie.json'` | Reads and parses the single file.                   |
+| `template: object`  | Uses the parsed Lottie (deep-cloned, not mutated).          |
+
+The return value:
+
+```ts
+{ buffer: Buffer, output?: string, mime: 'application/was' }
+```
+
+## CLI
+
+```bash
+was-sticker --image face.png --template ./templates/heart --out heart.was
+was-sticker -i face.png -t lottie.json -s image_0
+```
+
+## Baileys integration
+
+```js
+import { buildLottieSticker } from 'was-sticker';
+
+const { buffer } = await buildLottieSticker({
+  image: incomingPhotoBuffer,    // a Buffer you already have in memory
+  template: './templates/heart',
+});
+
+await sock.sendMessage(jid, {
+  sticker: buffer,
+  mimetype: 'application/was',
+});
+```
+
+## Bring your own template
+
+A `.was` is just a ZIP archive containing a Lottie JSON (and any sibling assets the animation references). To use a custom template:
+
+1. Find or design a Lottie animation that embeds the image you want to replace as a base64 `data:` URI inside its `assets[]` entry.
+2. Drop it into a folder, e.g. `./templates/heart/animation/animation.json`.
+3. Pass that folder as `template`.
+
+If your Lottie file references external assets (sibling PNGs, fonts, etc.), keep them in the same folder — they are bundled into the `.was` automatically.
+
+## Roadmap / suggested improvements
+
+These are deliberately *not* in v0.1 to keep the surface area small, but each one would be a natural follow-up:
+
+- **`sharp` preprocessing hook** — auto-resize to 512×512, convert to WebP, enforce WhatsApp's ~500 KB sticker budget. Keep it as an optional peer dep.
+- **Template registry** — ship a few permissively-licensed Lottie templates (heart, fire, sparkles) so users don't have to source one.
+- **Multi-frame stickers** — accept an array of images, write each into a separate animated layer.
+- **Validation pass** — warn when the produced `.was` exceeds WhatsApp's recommended size, or when frame rate × duration looks off.
+- **TypeScript declarations** — emit `.d.ts` alongside the JSDoc.
+- **Streaming output** — for very large bundles, stream the ZIP to disk instead of buffering.
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "was-sticker",
+  "version": "0.1.0",
+  "description": "Build WhatsApp animated stickers (.was) from images and Lottie templates. Pure JS, no shell dependencies.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "was-sticker": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "example": "node examples/build.js",
+    "test": "node --test test/smoke.test.js"
+  },
+  "keywords": ["whatsapp", "sticker", "lottie", "was", "animated-sticker", "baileys"],
+  "author": "thxmxx",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thxmxx/was-sticker.git"
+  },
+  "homepage": "https://github.com/thxmxx/was-sticker#readme",
+  "bugs": {
+    "url": "https://github.com/thxmxx/was-sticker/issues"
+  },
+  "dependencies": {
+    "jszip": "^3.10.1"
+  }
+}

package/src/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { resolve } from 'node:path';
+
+import { buildLottieSticker } from './index.js';
+
+const USAGE = `was-sticker — build WhatsApp animated stickers from a Lottie template.
+
+Usage:
+  was-sticker --image <path> --template <path> [--out sticker.was]
+              [--selector <id|index>] [--json-entry <path-in-archive>]
+
+Options:
+  -i, --image     Image file (PNG, JPG, WEBP).                    [required]
+  -t, --template  Lottie folder, JSON file, or pre-parsed JSON.   [required]
+  -o, --out       Output .was path. Default: ./sticker.was
+  -s, --selector  Asset id (string) or 0-based index.
+      --json-entry  Path of the Lottie JSON inside the .was.
+  -h, --help      Show this help.
+
+Examples:
+  was-sticker -i face.png -t ./templates/heart -o heart.was
+  was-sticker -i face.png -t lottie.json -s image_0
+`;
+
+function fail(msg, code = 1) {
+  process.stderr.write(`${msg}\n`);
+  process.exit(code);
+}
+
+const { values } = parseArgs({
+  options: {
+    image:      { type: 'string', short: 'i' },
+    template:   { type: 'string', short: 't' },
+    out:        { type: 'string', short: 'o' },
+    selector:   { type: 'string', short: 's' },
+    'json-entry': { type: 'string' },
+    help:       { type: 'boolean', short: 'h' },
+  },
+  allowPositionals: false,
+});
+
+if (values.help) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+
+if (!values.image || !values.template) {
+  process.stderr.write(USAGE);
+  fail('\nMissing required --image or --template.');
+}
+
+const output = resolve(values.out ?? './sticker.was');
+
+const selector =
+  values.selector == null
+    ? undefined
+    : /^\d+$/.test(values.selector)
+      ? Number(values.selector)
+      : values.selector;
+
+try {
+  const { output: written, buffer } = await buildLottieSticker({
+    image: values.image,
+    template: values.template,
+    output,
+    assetSelector: selector,
+    jsonEntryName: values['json-entry'],
+  });
+  process.stdout.write(`${written}  (${buffer.length.toLocaleString()} bytes)\n`);
+} catch (err) {
+  fail(`Error: ${err.message}`);
+}

package/src/index.js

@@ -0,0 +1,235 @@
+import { readFile, writeFile, mkdir, stat, readdir } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import JSZip from 'jszip';
+
+import {
+  SUPPORTED_MIMES,
+  detectMimeFromBuffer,
+  detectMimeFromExtension,
+} from './mime.js';
+
+const TEMPLATES_DIR = fileURLToPath(new URL('../templates/', import.meta.url));
+const BUNDLED_TEMPLATE_NAMES = Object.freeze(['pulse']);
+
+/**
+ * Resolve the absolute path of a Lottie template bundled with this package.
+ * @param {'pulse'} [name='pulse']
+ * @returns {string} absolute path to the template's JSON file
+ */
+export function bundledTemplate(name = 'pulse') {
+  if (!BUNDLED_TEMPLATE_NAMES.includes(name)) {
+    throw new Error(
+      `Unknown bundled template "${name}". Available: ${BUNDLED_TEMPLATE_NAMES.join(', ')}.`,
+    );
+  }
+  return join(TEMPLATES_DIR, name, 'animation.json');
+}
+
+const DEFAULT_JSON_ENTRY = 'animation/animation.json';
+
+const toDataUri = (buffer, mime) =>
+  `data:${mime};base64,${buffer.toString('base64')}`;
+
+async function resolveImage(image) {
+  if (image == null) throw new Error('image is required.');
+
+  let buffer;
+  let mime;
+  let path;
+
+  if (typeof image === 'string') {
+    path = image;
+  } else if (Buffer.isBuffer(image)) {
+    buffer = image;
+  } else if (typeof image === 'object') {
+    ({ buffer, mime, path } = image);
+  } else {
+    throw new Error('image must be a string path, Buffer, or { buffer | path, mime? }.');
+  }
+
+  if (!buffer) {
+    if (!path) throw new Error('image must include `buffer` or `path`.');
+    buffer = await readFile(path);
+  }
+
+  mime ??= detectMimeFromExtension(path) ?? detectMimeFromBuffer(buffer);
+  if (!mime) {
+    throw new Error(
+      `Unable to detect image mime. Supported: ${SUPPORTED_MIMES.join(', ')}.`,
+    );
+  }
+  if (!SUPPORTED_MIMES.includes(mime)) {
+    throw new Error(`Unsupported mime "${mime}". Use one of: ${SUPPORTED_MIMES.join(', ')}.`);
+  }
+
+  return { buffer, mime };
+}
+
+async function walkFiles(root) {
+  const out = [];
+  async function visit(dir) {
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) await visit(full);
+      else if (entry.isFile()) out.push(full);
+    }
+  }
+  await visit(root);
+  return out.map((abs) => ({ abs, rel: relative(root, abs).split(sep).join('/') }));
+}
+
+async function resolveTemplate(template, jsonEntryName) {
+  if (template == null) {
+    throw new Error('template is required (folder path, JSON file path, Buffer, or parsed object).');
+  }
+
+  if (typeof template === 'string') {
+    const info = await stat(template);
+    if (info.isDirectory()) {
+      const files = await walkFiles(template);
+      const candidate =
+        files.find((f) => f.rel === jsonEntryName) ??
+        files.find((f) => f.rel.toLowerCase().endsWith('.json'));
+      if (!candidate) {
+        throw new Error(`No JSON file found in template folder "${template}".`);
+      }
+      const lottie = JSON.parse(await readFile(candidate.abs, 'utf8'));
+      const extras = await Promise.all(
+        files
+          .filter((f) => f.abs !== candidate.abs)
+          .map(async (f) => [f.rel, await readFile(f.abs)]),
+      );
+      return {
+        lottie,
+        jsonEntryName: candidate.rel,
+        extraFiles: Object.fromEntries(extras),
+      };
+    }
+    return {
+      lottie: JSON.parse(await readFile(template, 'utf8')),
+      jsonEntryName: jsonEntryName ?? DEFAULT_JSON_ENTRY,
+      extraFiles: {},
+    };
+  }
+
+  if (Buffer.isBuffer(template)) {
+    return {
+      lottie: JSON.parse(template.toString('utf8')),
+      jsonEntryName: jsonEntryName ?? DEFAULT_JSON_ENTRY,
+      extraFiles: {},
+    };
+  }
+
+  if (typeof template === 'object') {
+    return {
+      lottie: structuredClone(template),
+      jsonEntryName: jsonEntryName ?? DEFAULT_JSON_ENTRY,
+      extraFiles: {},
+    };
+  }
+
+  throw new Error('template must be a path, Buffer, or parsed Lottie object.');
+}
+
+function findImageAsset(lottie, selector) {
+  if (!lottie || !Array.isArray(lottie.assets) || lottie.assets.length === 0) {
+    throw new Error('Lottie template has no `assets` array.');
+  }
+
+  const isImageAsset = (a) => typeof a?.p === 'string' && a.p.startsWith('data:image/');
+
+  if (selector == null) {
+    const found = lottie.assets.find(isImageAsset);
+    if (!found) {
+      throw new Error(
+        'No embedded base64 image asset found. Pass assetSelector to target a specific asset.',
+      );
+    }
+    return found;
+  }
+
+  if (typeof selector === 'number') {
+    const found = lottie.assets[selector];
+    if (!found) throw new Error(`No asset at index ${selector}.`);
+    return found;
+  }
+
+  if (typeof selector === 'string') {
+    const found = lottie.assets.find((a) => a?.id === selector);
+    if (!found) throw new Error(`No asset with id "${selector}".`);
+    return found;
+  }
+
+  if (typeof selector === 'function') {
+    const found = lottie.assets.find(selector);
+    if (!found) throw new Error('assetSelector did not match any asset.');
+    return found;
+  }
+
+  throw new Error('assetSelector must be a number, string, function, or undefined.');
+}
+
+/**
+ * Build a WhatsApp animated sticker (`.was`) from an image and a Lottie template.
+ *
+ * @param {object} options
+ * @param {string | Buffer | { buffer?: Buffer, path?: string, mime?: string }} options.image
+ *   Image source. Either a file path, a raw Buffer, or an object with `buffer`/`path` and optional `mime`.
+ * @param {string | Buffer | object} options.template
+ *   Template source: a folder path, a JSON file path, a raw Buffer, or a parsed Lottie object.
+ * @param {string} [options.output]
+ *   If provided, the built `.was` is written here. The directory is created if missing.
+ * @param {number | string | ((asset: object) => boolean)} [options.assetSelector]
+ *   Which asset to swap. By default, the first asset with an embedded base64 image.
+ * @param {string} [options.jsonEntryName]
+ *   Path of the Lottie JSON inside the resulting archive. Defaults to the template's own path,
+ *   or "animation/animation.json" when the template is a single JSON.
+ * @param {Record<string, Buffer | string>} [options.extraFiles]
+ *   Additional files to include in the archive (merged on top of folder-template files).
+ * @returns {Promise<{ buffer: Buffer, output?: string, mime: 'application/was' }>}
+ */
+export async function buildLottieSticker({
+  image,
+  template,
+  output,
+  assetSelector,
+  jsonEntryName,
+  extraFiles,
+} = {}) {
+  const [{ buffer: imageBuffer, mime }, resolved] = await Promise.all([
+    resolveImage(image),
+    resolveTemplate(template, jsonEntryName),
+  ]);
+
+  const asset = findImageAsset(resolved.lottie, assetSelector);
+  asset.p = toDataUri(imageBuffer, mime);
+  if ('u' in asset) asset.u = '';
+
+  const zip = new JSZip();
+  for (const [name, contents] of Object.entries(resolved.extraFiles)) {
+    zip.file(name, contents);
+  }
+  zip.file(resolved.jsonEntryName, JSON.stringify(resolved.lottie));
+  if (extraFiles) {
+    for (const [name, contents] of Object.entries(extraFiles)) {
+      zip.file(name, contents);
+    }
+  }
+
+  const wasBuffer = await zip.generateAsync({
+    type: 'nodebuffer',
+    compression: 'DEFLATE',
+    compressionOptions: { level: 6 },
+  });
+
+  if (output) {
+    await mkdir(dirname(resolve(output)), { recursive: true });
+    await writeFile(output, wasBuffer);
+  }
+
+  return { buffer: wasBuffer, output, mime: 'application/was' };
+}
+
+export { SUPPORTED_MIMES, detectMimeFromBuffer, detectMimeFromExtension };
+export { BUNDLED_TEMPLATE_NAMES };

package/src/mime.js

@@ -0,0 +1,33 @@
+import { extname } from 'node:path';
+
+const MIME_BY_EXT = Object.freeze({
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+});
+
+const MAGIC = [
+  { mime: 'image/png',  bytes: [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a] },
+  { mime: 'image/jpeg', bytes: [0xff, 0xd8, 0xff] },
+  { mime: 'image/webp', bytes: [0x52, 0x49, 0x46, 0x46], suffixAt: 8, suffix: [0x57, 0x45, 0x42, 0x50] },
+];
+
+export const SUPPORTED_MIMES = Object.freeze([...new Set(Object.values(MIME_BY_EXT))]);
+
+export function detectMimeFromExtension(filePath) {
+  if (!filePath) return null;
+  return MIME_BY_EXT[extname(String(filePath)).toLowerCase()] ?? null;
+}
+
+export function detectMimeFromBuffer(buffer) {
+  if (!Buffer.isBuffer(buffer) || buffer.length < 12) return null;
+
+  for (const { mime, bytes, suffixAt, suffix } of MAGIC) {
+    const headOk = bytes.every((b, i) => buffer[i] === b);
+    if (!headOk) continue;
+    if (suffix && !suffix.every((b, i) => buffer[suffixAt + i] === b)) continue;
+    return mime;
+  }
+  return null;
+}

package/templates/pulse/animation.json

@@ -0,0 +1 @@
+{"v":"5.7.1","fr":30,"ip":0,"op":30,"w":512,"h":512,"nm":"pulse","ddd":0,"assets":[{"id":"image_0","w":512,"h":512,"u":"","p":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNgYGD4DwABBAEAfbLI3wAAAABJRU5ErkJggg=="}],"layers":[{"ddd":0,"ind":1,"ty":2,"nm":"image","refId":"image_0","sr":1,"ks":{"o":{"a":0,"k":100},"r":{"a":0,"k":0},"p":{"a":0,"k":[256,256,0]},"a":{"a":0,"k":[256,256,0]},"s":{"a":1,"k":[{"i":{"x":[0.5,0.5,0.5],"y":[1,1,1]},"o":{"x":[0.5,0.5,0.5],"y":[0,0,0]},"t":0,"s":[100,100,100]},{"i":{"x":[0.5,0.5,0.5],"y":[1,1,1]},"o":{"x":[0.5,0.5,0.5],"y":[0,0,0]},"t":15,"s":[115,115,100]},{"t":30,"s":[100,100,100]}]}},"ao":0,"ip":0,"op":30,"st":0,"bm":0}],"markers":[]}