was-sticker 0.1.1 → 2.0.0

package/README.md

@@ -3,20 +3,23 @@
 [![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.
+Re-brand WhatsApp Lottie stickers (`.was`) and send them through Baileys as a proper `lottieStickerMessage` — so they actually render on mobile.
 
-- ✅ **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`.
+> ⚠️ **What this is and isn't.** WhatsApp signs every animated Lottie sticker with an ES256 JWT (`trust_token`) carrying the SHA-256 of the animation JSON. Any change to the animation invalidates the token and the client silently drops the sticker. This library does **not** let you put your own image inside a Lottie animation. What it lets you do is **re-brand** a genuine WhatsApp Lottie sticker (change the pack name, publisher, emojis, group link) without breaking the signature. The animation itself stays a Meta-original sticker.
+>
+> If you want a sticker with your own artwork, you need WebP animated, not Lottie `.was`. That is not what this package does.
+
+## How it actually works
+
+1. **Source** a `.was` whose `trust_token` is genuine. The library ships a Baileys helper, `captureNextLottieSticker`, that listens for the next animated sticker delivered to your account and saves the encrypted `.was` to disk.
+2. **Customize** only the `overridden_metadata` inside the archive. The animation JSON and the trust_token are preserved byte-for-byte, so the client-side SHA check still passes.
+3. **Send** via `sendLottieSticker`, which wraps your sticker in a `lottieStickerMessage` (FutureProofMessage at field 74). Baileys' regular `sock.sendMessage({ sticker, mimetype })` emits `stickerMessage` (field 26) — Web tolerates it, mobile does not.
 
 ## Install
 
 ```bash
 npm install was-sticker
+npm install @whiskeysockets/baileys      # peer dep, only needed for send/capture
 ```
 
 Requires Node.js ≥ 18.
@@ -24,91 +27,135 @@ Requires Node.js ≥ 18.
 ## Quick start
 
 ```js
-import { buildLottieSticker, bundledTemplate } from 'was-sticker';
-
-const { buffer } = await buildLottieSticker({
-  image: 'face.png',
-  template: bundledTemplate('pulse'),
+import { readFile, writeFile } from 'node:fs/promises';
+import {
+  inspectWAS,
+  customizeMetadata,
+  sendLottieSticker,
+  captureNextLottieSticker,
+} from 'was-sticker';
+
+// 1. Source a .was by waiting for one to arrive.
+const { buffer } = await captureNextLottieSticker(sock, { timeoutMs: 120_000 });
+await writeFile('./pumpkin.was', buffer);
+
+// 2. Inspect it (sanity check).
+console.log(await inspectWAS(buffer));
+// → { animation: { nm: 'WA_Harvest_…', w: 512, h: 512, fps: 60, ... },
+//     trustToken: { kid: '196', alg: 'ES256', claimedSha: '...' },
+//     shaMatches: true, ... }
+
+// 3. Re-brand it.
+const rebranded = await customizeMetadata(buffer, {
+  packId: 'my-bot-pack-v1',
+  packName: 'My Bot Pack',
+  publisher: 'Bot\nMade with was-sticker',
+  accessibilityText: 'A custom animated sticker',
+  emojis: ['💎', '✨'],
 });
-// → 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.
+// 4. Send it on Baileys with the right wrapper.
+await sendLottieSticker(sock, '5511…@s.whatsapp.net', rebranded);
+```
 
 ## 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
-});
-```
+### `extractFromWAS(buffer)`
+
+Parses the ZIP archive. Returns `{ files, jsonPath, animation, trustToken, trustTokenPath, metadata, metadataPath }`.
 
-| 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).          |
+### `inspectWAS(buffer)`
 
-The return value:
+Higher-level summary intended for CLI / debugging output:
 
 ```ts
-{ buffer: Buffer, output?: string, mime: 'application/was' }
+{
+  jsonPath: string,
+  animation: { nm, version, width, height, fps, durationFrames, layers, assets },
+  metadata: object | null,
+  trustToken: { kid, alg, stickerFileType, trustedOrigin, claimedSha } | null,
+  sha256: string,
+  shaMatches: boolean,   // <-- this is the only field that ultimately matters
+  size: number,
+  fileNames: string[],
+}
 ```
 
-## CLI
+If `shaMatches` is `false`, the WhatsApp client will reject the sticker.
 
-```bash
-was-sticker --image face.png --template ./templates/heart --out heart.was
-was-sticker -i face.png -t lottie.json -s image_0
+### `customizeMetadata(buffer, patch, { merge = true })`
+
+Returns a new `.was` buffer with `overridden_metadata` rewritten. Allowed `patch` fields:
+
+| Camel-case input    | Underlying WhatsApp field         |
+| ------------------- | --------------------------------- |
+| `packId`            | `sticker-pack-id`                 |
+| `packName`          | `sticker-pack-name`               |
+| `publisher`         | `sticker-pack-publisher` (newlines OK — the second line typically holds a group link) |
+| `accessibilityText` | `accessibility-text`              |
+| `emojis`            | `emojis` (array of glyphs)        |
+| `isFromUserCreatedPack` | `is-from-user-created-pack` (default `1`) |
+
+`merge: false` rewrites the metadata from scratch instead of merging with what's already there.
+
+The animation JSON and the trust_token are not touched.
+
+### `sendLottieSticker(sock, jid, buffer, opts?)`
+
+Uploads `buffer` via Baileys' `prepareWAMessageMedia`, then relays it as a `lottieStickerMessage`.
+
+```ts
+opts?: {
+  width?: number,
+  height?: number,
+  accessibilityLabel?: string,
+  messageId?: string,
+  quoted?: WAMessage,
+}
 ```
 
-## Baileys integration
+Returns `{ messageId, fileLength }`.
 
-```js
-import { buildLottieSticker } from 'was-sticker';
+### `captureNextLottieSticker(sock, opts?)`
 
-const { buffer } = await buildLottieSticker({
-  image: incomingPhotoBuffer,    // a Buffer you already have in memory
-  template: './templates/heart',
-});
+Resolves with the next incoming Lottie sticker, downloaded and decrypted.
 
-await sock.sendMessage(jid, {
-  sticker: buffer,
-  mimetype: 'application/was',
-});
+```ts
+opts?: {
+  timeoutMs?: number,   // default 60_000; 0 = no timeout
+  from?: string,        // restrict to one JID
+  filter?: (stk, key) => boolean,
+  includeNonLottie?: boolean,  // default false
+}
 ```
 
-## Bring your own template
+Returns `{ buffer, stickerMessage, key, mimetype, isLottie, isAnimated, width, height }`.
+
+## CLI
+
+```bash
+was-sticker inspect <in.was>
+was-sticker customize <in.was> -o <out.was> \
+    --pack-name "My Pack" \
+    --publisher "Me\nGrupo: https://example.com" \
+    --emoji 🎃 --emoji 💎
+```
 
-A `.was` is just a ZIP archive containing a Lottie JSON (and any sibling assets the animation references). To use a custom template:
+`inspect` prints the JSON summary above. `customize` writes the rebranded archive.
 
-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`.
+Sending and capturing are intentionally not in the CLI — both require a connected Baileys socket; do them from a script (see `examples/`).
 
-If your Lottie file references external assets (sibling PNGs, fonts, etc.), keep them in the same folder — they are bundled into the `.was` automatically.
+## Examples
 
-## Roadmap / suggested improvements
+- [`examples/capture.js`](./examples/capture.js) — wait for a forwarded sticker and save it.
+- [`examples/customize-and-send.js`](./examples/customize-and-send.js) — rebrand and send.
 
-These are deliberately *not* in v0.1 to keep the surface area small, but each one would be a natural follow-up:
+## Notes / gotchas
 
-- **`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.
+- **Mobile vs Web parity.** Mobile WhatsApp will silently drop Lottie payloads that arrive as plain `stickerMessage`. Web will render them. Use `sendLottieSticker`, not `sock.sendMessage({ sticker, mimetype: 'application/was' })`.
+- **The pack info shown in Web** comes from WhatsApp's official catalog keyed by the animation's identity, not from your `overridden_metadata`. Mobile reads your metadata. This is a WhatsApp quirk, not a bug.
+- **Use at your own risk.** Sending modified `.was` files through unofficial clients (Baileys is one) violates WhatsApp's Terms of Service and can result in your number being banned. Test on a throwaway account.
 
 ## License
 
-MIT.
+MIT — see [LICENSE](./LICENSE).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "was-sticker",
-  "version": "0.1.1",
-  "description": "Build WhatsApp animated stickers (.was) from images and Lottie templates. Pure JS, no shell dependencies.",
+  "version": "2.0.0",
+  "description": "Re-brand WhatsApp Lottie stickers (.was) and send them via Baileys as a real lottieStickerMessage.",
   "type": "module",
   "main": "./src/index.js",
   "exports": {
@@ -12,7 +12,6 @@
   },
   "files": [
     "src",
-    "templates",
     "README.md",
     "LICENSE"
   ],
@@ -20,7 +19,6 @@
     "node": ">=18"
   },
   "scripts": {
-    "example": "node examples/build.js",
     "test": "node --test test/smoke.test.js"
   },
   "keywords": [
@@ -29,7 +27,8 @@
     "lottie",
     "was",
     "animated-sticker",
-    "baileys"
+    "baileys",
+    "lottieStickerMessage"
   ],
   "author": "thxmxx",
   "license": "MIT",
@@ -43,5 +42,13 @@
   },
   "dependencies": {
     "jszip": "^3.10.1"
+  },
+  "peerDependencies": {
+    "@whiskeysockets/baileys": ">=6.7.0"
+  },
+  "peerDependenciesMeta": {
+    "@whiskeysockets/baileys": {
+      "optional": true
+    }
   }
 }

package/src/capture.js

@@ -0,0 +1,118 @@
+/**
+ * Listen for the next incoming Lottie sticker and return its decrypted buffer.
+ * Useful for sourcing genuine `.was` files (with Meta-signed trust_tokens) that
+ * you can then customize with `customizeMetadata`.
+ *
+ * WhatsApp routes Lottie stickers via `lottieStickerMessage` (FutureProofMessage
+ * at field 74) — Baileys' default `downloadMediaMessage` doesn't handle that
+ * variant. This helper walks the message tree, finds the inner stickerMessage,
+ * and uses the lower-level `downloadContentFromMessage` to decrypt.
+ */
+
+async function loadBaileys() {
+  try {
+    return await import('@whiskeysockets/baileys');
+  } catch {
+    throw new Error(
+      'captureNextLottieSticker requires "@whiskeysockets/baileys" — install it as a peer dependency.',
+    );
+  }
+}
+
+function findStickerMessage(msg) {
+  if (!msg || typeof msg !== 'object') return null;
+  if (msg.stickerMessage) return msg.stickerMessage;
+  for (const v of Object.values(msg)) {
+    if (v && typeof v === 'object') {
+      const inner = findStickerMessage(v);
+      if (inner) return inner;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve when the next sticker (Lottie or otherwise) matching `filter` arrives.
+ *
+ * @param {object} sock — connected Baileys socket
+ * @param {{
+ *   timeoutMs?: number,                       // default 60_000; 0 = no timeout
+ *   from?: string,                            // restrict to a specific JID
+ *   filter?: (stickerMessage, key) => boolean // custom predicate
+ *   includeNonLottie?: boolean,               // default false — only Lottie/.was
+ * }} [opts]
+ * @returns {Promise<{
+ *   buffer: Buffer,
+ *   stickerMessage: object,
+ *   key: { remoteJid: string, id: string, fromMe: boolean },
+ *   mimetype: string,
+ *   isLottie: boolean,
+ *   isAnimated: boolean,
+ *   width: number,
+ *   height: number,
+ * }>}
+ */
+export function captureNextLottieSticker(sock, opts = {}) {
+  if (!sock || typeof sock.ev?.on !== 'function') {
+    throw new Error('captureNextLottieSticker: first argument must be a Baileys socket.');
+  }
+  const { timeoutMs = 60_000, from, filter, includeNonLottie = false } = opts;
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let timer = null;
+
+    const onUpsert = async ({ messages }) => {
+      if (settled) return;
+      for (const m of messages) {
+        if (settled) break;
+        if (!m.message) continue;
+        if (from && m.key.remoteJid !== from) continue;
+
+        const stk = findStickerMessage(m.message);
+        if (!stk) continue;
+        if (!includeNonLottie && !stk.isLottie) continue;
+        if (filter && !filter(stk, m.key)) continue;
+
+        try {
+          const { downloadContentFromMessage } = await loadBaileys();
+          const stream = await downloadContentFromMessage(stk, 'sticker');
+          const chunks = [];
+          for await (const c of stream) chunks.push(c);
+          const buffer = Buffer.concat(chunks);
+
+          settled = true;
+          if (timer) clearTimeout(timer);
+          sock.ev.off('messages.upsert', onUpsert);
+          resolve({
+            buffer,
+            stickerMessage: stk,
+            key: m.key,
+            mimetype: stk.mimetype ?? null,
+            isLottie: !!stk.isLottie,
+            isAnimated: !!stk.isAnimated,
+            width: stk.width ?? 0,
+            height: stk.height ?? 0,
+          });
+        } catch (err) {
+          settled = true;
+          if (timer) clearTimeout(timer);
+          sock.ev.off('messages.upsert', onUpsert);
+          reject(err);
+        }
+        return;
+      }
+    };
+
+    sock.ev.on('messages.upsert', onUpsert);
+
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        sock.ev.off('messages.upsert', onUpsert);
+        reject(new Error(`captureNextLottieSticker: timed out after ${timeoutMs}ms.`));
+      }, timeoutMs);
+    }
+  });
+}

package/src/cli.js

@@ -1,26 +1,27 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
-import { resolve } from 'node:path';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
 
-import { buildLottieSticker } from './index.js';
+import { inspectWAS } from './extract.js';
+import { customizeMetadata } from './customize.js';
 
-const USAGE = `was-sticker — build WhatsApp animated stickers from a Lottie template.
+const USAGE = `was-sticker — inspect and re-brand WhatsApp Lottie stickers (.was).
 
 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
+  was-sticker inspect <in.was>
+  was-sticker customize <in.was> -o <out.was>
+                                 [--pack-id ID] [--pack-name NAME]
+                                 [--publisher PUBLISHER] [--accessibility-text TEXT]
+                                 [--emoji EMOJI ... | --emojis "🎃,🎉,💎"]
+                                 [--no-merge]
+
+Subcommands:
+  inspect      Show the Lottie metadata, trust-token claims, and SHA match.
+  customize    Rewrite only the overridden_metadata; emits a new .was.
+
+For sending and capturing .was files, use the JS API:
+    import { sendLottieSticker, captureNextLottieSticker } from 'was-sticker';
 `;
 
 function fail(msg, code = 1) {
@@ -28,46 +29,74 @@ function fail(msg, code = 1) {
   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) {
+const [, , sub, ...rest] = process.argv;
+
+if (!sub || sub === '-h' || sub === '--help') {
   process.stdout.write(USAGE);
-  process.exit(0);
+  process.exit(sub ? 0 : 1);
+}
+
+async function readInput(positional) {
+  if (!positional) fail('Missing <in.was>.');
+  return readFile(resolve(positional));
+}
+
+async function writeOutput(path, buffer) {
+  const abs = resolve(path);
+  await mkdir(dirname(abs), { recursive: true });
+  await writeFile(abs, buffer);
+  return abs;
 }
 
-if (!values.image || !values.template) {
-  process.stderr.write(USAGE);
-  fail('\nMissing required --image or --template.');
+if (sub === 'inspect') {
+  const buffer = await readInput(rest[0]);
+  const info = await inspectWAS(buffer);
+  process.stdout.write(JSON.stringify(info, null, 2) + '\n');
+  process.exit(0);
 }
 
-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'],
+if (sub === 'customize') {
+  const { values, positionals } = parseArgs({
+    args: rest,
+    allowPositionals: true,
+    options: {
+      out: { type: 'string', short: 'o' },
+      'pack-id':            { type: 'string' },
+      'pack-name':          { type: 'string' },
+      publisher:            { type: 'string' },
+      'accessibility-text': { type: 'string' },
+      emoji:                { type: 'string', multiple: true },
+      emojis:               { type: 'string' },
+      'no-merge':           { type: 'boolean' },
+      help:                 { type: 'boolean', short: 'h' },
+    },
   });
-  process.stdout.write(`${written}  (${buffer.length.toLocaleString()} bytes)\n`);
-} catch (err) {
-  fail(`Error: ${err.message}`);
+
+  if (values.help) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+  if (!positionals[0]) fail('Missing <in.was>.');
+  if (!values.out)     fail('Missing --out / -o.');
+
+  const buffer = await readInput(positionals[0]);
+
+  const emojis = values.emoji?.length
+    ? values.emoji
+    : values.emojis?.split(',').map((s) => s.trim()).filter(Boolean);
+
+  const patch = {
+    ...(values['pack-id']            && { packId:            values['pack-id'] }),
+    ...(values['pack-name']          && { packName:          values['pack-name'] }),
+    ...(values.publisher             && { publisher:         values.publisher }),
+    ...(values['accessibility-text'] && { accessibilityText: values['accessibility-text'] }),
+    ...(emojis                       && { emojis }),
+  };
+
+  const out = await customizeMetadata(buffer, patch, { merge: !values['no-merge'] });
+  const path = await writeOutput(values.out, out);
+  process.stdout.write(`${path}  (${out.length.toLocaleString()} bytes)\n`);
+  process.exit(0);
 }
+
+fail(`Unknown subcommand "${sub}".\n\n${USAGE}`);

package/src/customize.js

@@ -0,0 +1,72 @@
+import JSZip from 'jszip';
+import { extractFromWAS } from './extract.js';
+
+const ALLOWED_FIELDS = Object.freeze({
+  packId:               'sticker-pack-id',
+  packName:             'sticker-pack-name',
+  publisher:            'sticker-pack-publisher',
+  accessibilityText:    'accessibility-text',
+  emojis:               'emojis',
+  isFromUserCreatedPack: 'is-from-user-created-pack',
+});
+
+function patchToWaMetadata(patch) {
+  if (patch == null || typeof patch !== 'object') {
+    throw new Error('customizeMetadata: patch must be an object.');
+  }
+  const out = {};
+  for (const [camelKey, waKey] of Object.entries(ALLOWED_FIELDS)) {
+    if (patch[camelKey] !== undefined) out[waKey] = patch[camelKey];
+  }
+  // Pass through any "wa-style" keys verbatim (escape hatch for advanced users).
+  for (const k of Object.keys(patch)) {
+    if (Object.values(ALLOWED_FIELDS).includes(k)) out[k] = patch[k];
+  }
+  return out;
+}
+
+/**
+ * Returns a new `.was` buffer with the overridden_metadata replaced or merged.
+ *
+ * The animation JSON and its trust_token are preserved byte-for-byte so the
+ * client-side SHA check still passes.
+ *
+ * @param {Buffer|Uint8Array} buffer
+ * @param {{
+ *   packId?: string,
+ *   packName?: string,
+ *   publisher?: string,
+ *   accessibilityText?: string,
+ *   emojis?: string[],
+ *   isFromUserCreatedPack?: 0 | 1,
+ * }} patch
+ * @param {{ merge?: boolean }} [opts] — when true (default), unspecified fields
+ *   are kept from the existing metadata; when false, the metadata is rewritten
+ *   from scratch using only the patch.
+ * @returns {Promise<Buffer>}
+ */
+export async function customizeMetadata(buffer, patch, opts = {}) {
+  const { merge = true } = opts;
+  const { files, jsonPath, metadata } = await extractFromWAS(buffer);
+
+  const waPatch = patchToWaMetadata(patch);
+  const next = merge ? { ...(metadata ?? {}), ...waPatch } : { ...waPatch };
+
+  // is-from-user-created-pack is expected by WhatsApp on custom packs — default to 1.
+  if (next['is-from-user-created-pack'] === undefined) {
+    next['is-from-user-created-pack'] = 1;
+  }
+
+  const metadataPath = `${jsonPath}.overridden_metadata`;
+  files[metadataPath] = Buffer.from(JSON.stringify(next), 'utf8');
+
+  const zip = new JSZip();
+  for (const [name, contents] of Object.entries(files)) {
+    zip.file(name, contents);
+  }
+  return zip.generateAsync({
+    type: 'nodebuffer',
+    compression: 'DEFLATE',
+    compressionOptions: { level: 6 },
+  });
+}

package/src/extract.js

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto';
+import JSZip from 'jszip';
+
+/**
+ * Decode the payload of a JWT trust_token (no signature verification — that's
+ * the WhatsApp client's job; we only inspect the claims).
+ */
+function decodeTrustToken(token) {
+  if (typeof token !== 'string') return null;
+  const [headerB64, payloadB64, sigB64] = token.split('.');
+  if (!headerB64 || !payloadB64 || !sigB64) return null;
+  const fromB64 = (s) => Buffer.from(s + '='.repeat((4 - (s.length % 4)) % 4), 'base64');
+  const header  = JSON.parse(fromB64(headerB64).toString('utf8'));
+  const payload = JSON.parse(fromB64(payloadB64).toString('utf8'));
+  // payload.sticker_file_sha256 is base64url-encoded SHA-256
+  const claimedShaHex = payload.sticker_file_sha256
+    ? fromB64(payload.sticker_file_sha256).toString('hex')
+    : null;
+  return { header, payload, claimedShaHex, raw: token };
+}
+
+/**
+ * Parse a `.was` archive.
+ *
+ * @param {Buffer|Uint8Array} buffer
+ * @returns {Promise<{
+ *   files: Record<string, Buffer>,
+ *   jsonPath: string,
+ *   animation: object,
+ *   trustToken: ReturnType<typeof decodeTrustToken> | null,
+ *   trustTokenPath: string | null,
+ *   metadata: object | null,
+ *   metadataPath: string | null,
+ * }>}
+ */
+export async function extractFromWAS(buffer) {
+  if (!buffer || (!Buffer.isBuffer(buffer) && !(buffer instanceof Uint8Array))) {
+    throw new Error('extractFromWAS: buffer is required.');
+  }
+  const zip = await JSZip.loadAsync(buffer);
+
+  const files = {};
+  await Promise.all(
+    Object.values(zip.files)
+      .filter((f) => !f.dir)
+      .map(async (f) => { files[f.name] = await f.async('nodebuffer'); }),
+  );
+
+  // Pick the primary Lottie JSON: prefer `animation.json`, else first non-metadata JSON.
+  const jsonNames = Object.keys(files).filter(
+    (n) => n.toLowerCase().endsWith('.json') &&
+           !n.endsWith('.overridden_metadata') &&
+           !n.endsWith('.trust_token'),
+  );
+  if (jsonNames.length === 0) {
+    throw new Error('No Lottie JSON found in archive.');
+  }
+  const jsonPath = jsonNames.find((n) => n.endsWith('animation.json')) ?? jsonNames[0];
+
+  let animation;
+  try {
+    animation = JSON.parse(files[jsonPath].toString('utf8'));
+  } catch (err) {
+    throw new Error(`Could not parse "${jsonPath}" as JSON: ${err.message}`);
+  }
+
+  const trustTokenPath = `${jsonPath}.trust_token`;
+  const trustToken = files[trustTokenPath]
+    ? decodeTrustToken(files[trustTokenPath].toString('utf8').trim())
+    : null;
+
+  const metadataPath = `${jsonPath}.overridden_metadata`;
+  let metadata = null;
+  if (files[metadataPath]) {
+    try { metadata = JSON.parse(files[metadataPath].toString('utf8')); }
+    catch { /* leave metadata null if it's not parseable */ }
+  }
+
+  return { files, jsonPath, animation, trustToken, trustTokenPath, metadata, metadataPath };
+}
+
+/**
+ * Human-friendly summary of a `.was` — useful for CLI inspection.
+ */
+export async function inspectWAS(buffer) {
+  const { jsonPath, animation, trustToken, metadata, files } = await extractFromWAS(buffer);
+
+  const jsonBytes = files[jsonPath];
+  const actualSha = createHash('sha256').update(jsonBytes).digest('hex');
+  const claimedSha = trustToken?.claimedShaHex ?? null;
+
+  return {
+    jsonPath,
+    animation: {
+      nm: animation.nm ?? null,
+      version: animation.v ?? null,
+      width: animation.w ?? null,
+      height: animation.h ?? null,
+      fps: animation.fr ?? null,
+      durationFrames: (animation.op ?? 0) - (animation.ip ?? 0),
+      layers: Array.isArray(animation.layers) ? animation.layers.length : 0,
+      assets: Array.isArray(animation.assets) ? animation.assets.length : 0,
+    },
+    metadata,
+    trustToken: trustToken && {
+      kid: trustToken.header?.kid ?? null,
+      alg: trustToken.header?.alg ?? null,
+      stickerFileType: trustToken.payload?.sticker_file_type ?? null,
+      trustedOrigin: trustToken.payload?.sticker_file_trusted_origin ?? null,
+      claimedSha,
+    },
+    sha256: actualSha,
+    shaMatches: claimedSha !== null && claimedSha === actualSha,
+    size: jsonBytes.length,
+    fileNames: Object.keys(files),
+  };
+}

package/src/index.js

@@ -1,235 +1,22 @@
-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.
+ * was-sticker — re-brand a Meta WhatsApp Lottie sticker (`.was`) and ship it
+ * through Baileys as a real `lottieStickerMessage` so it renders on mobile.
  *
- * @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' }>}
+ * Tech notes captured during the v2 rewrite:
+ *
+ *  - The animation JSON inside a `.was` is signed by Meta. A JWT ES256
+ *    `trust_token` (kid=196) carries the SHA-256 of the JSON. Any byte change
+ *    to the JSON invalidates the token → the WhatsApp client silently drops
+ *    the sticker. We never touch the animation; only `overridden_metadata`
+ *    (pack name, publisher, emojis, group link) is fair game.
+ *  - Baileys' `sock.sendMessage({ sticker, mimetype: 'application/was' })`
+ *    emits `stickerMessage` (proto field 26). WhatsApp Web renders that;
+ *    mobile WhatsApp does NOT. Mobile requires `lottieStickerMessage`
+ *    (FutureProofMessage at field 74) wrapping a `stickerMessage`. The
+ *    `sendLottieSticker` helper does that for you.
  */
-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 };
+export { extractFromWAS, inspectWAS } from './extract.js';
+export { customizeMetadata } from './customize.js';
+export { sendLottieSticker } from './send.js';
+export { captureNextLottieSticker } from './capture.js';

package/src/send.js

@@ -0,0 +1,76 @@
+/**
+ * Send a `.was` Lottie sticker as a real `lottieStickerMessage` (FutureProofMessage
+ * at field 74). Required for mobile WhatsApp clients to render it — they silently
+ * drop Lottie payloads sent inside a plain `stickerMessage` (field 26), which is
+ * what Baileys' `sock.sendMessage({ sticker, mimetype })` emits.
+ */
+
+async function loadBaileys() {
+  // Imported lazily so the lib doesn't hard-require Baileys for users who only
+  // do extract/customize. Baileys is declared as an optional peer dependency.
+  try {
+    return await import('@whiskeysockets/baileys');
+  } catch (err) {
+    throw new Error(
+      'sendLottieSticker requires "@whiskeysockets/baileys" — install it as a peer dependency.',
+    );
+  }
+}
+
+/**
+ * Relay a `.was` buffer as a Lottie sticker on the given Baileys socket.
+ *
+ * @param {object} sock — a connected Baileys socket
+ * @param {string} jid — recipient JID (e.g. `5511…@s.whatsapp.net` or `…@g.us`)
+ * @param {Buffer|Uint8Array} buffer — `.was` archive bytes
+ * @param {{
+ *   width?: number,
+ *   height?: number,
+ *   accessibilityLabel?: string,
+ *   messageId?: string,
+ *   quoted?: object,
+ * }} [opts]
+ * @returns {Promise<{ messageId: string, fileLength: number }>}
+ */
+export async function sendLottieSticker(sock, jid, buffer, opts = {}) {
+  if (!sock || typeof sock.relayMessage !== 'function') {
+    throw new Error('sendLottieSticker: first argument must be a Baileys socket.');
+  }
+  if (typeof jid !== 'string' || !jid.includes('@')) {
+    throw new Error('sendLottieSticker: jid must be a JID string.');
+  }
+
+  const baileys = await loadBaileys();
+  const { prepareWAMessageMedia, generateWAMessageFromContent, generateMessageIDV2 } = baileys;
+
+  // 1. Upload — gives us url/directPath/mediaKey/fileSha256/etc.
+  const prepared = await prepareWAMessageMedia(
+    { sticker: Buffer.isBuffer(buffer) ? buffer : Buffer.from(buffer), mimetype: 'application/was' },
+    { upload: sock.waUploadToServer, mediaTypeOverride: 'sticker' },
+  );
+  const inner = prepared.stickerMessage;
+  if (!inner) throw new Error('prepareWAMessageMedia did not return a stickerMessage.');
+
+  inner.mimetype = 'application/was';
+  inner.isAnimated = true;
+  inner.isLottie = true;
+  if (opts.width)               inner.width = opts.width;
+  if (opts.height)              inner.height = opts.height;
+  if (opts.accessibilityLabel)  inner.accessibilityLabel = opts.accessibilityLabel;
+
+  // 2. Wrap in lottieStickerMessage (FutureProofMessage → Message → stickerMessage).
+  const content = {
+    lottieStickerMessage: { message: { stickerMessage: inner } },
+  };
+
+  // 3. Build the WAMessage and relay it.
+  const messageId = opts.messageId ?? generateMessageIDV2();
+  const waMsg = generateWAMessageFromContent(jid, content, {
+    userJid: sock.user?.id,
+    messageId,
+    quoted: opts.quoted,
+  });
+  await sock.relayMessage(jid, waMsg.message, { messageId });
+
+  return { messageId, fileLength: Number(inner.fileLength ?? buffer.length ?? 0) };
+}

package/src/mime.js

@@ -1,33 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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":[]}