@boruto_vk7/stickengine 0.0.5 → 1.0.0

package/LICENSE

@@ -1,15 +1,21 @@
-ISC License
+MIT License
 
-Copyright (c) 2026, Borutovk7 <https://github.com/Borutovk7>
+Copyright (c) 2026 Borutovk7
 
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
+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 SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+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

@@ -1,121 +1,209 @@
-# 🚀 StickEngine
+# @boruto_vk7/stickengine
 
-**StickEngine** é um motor poderoso e leve para criação de figurinhas do WhatsApp (estáticas e animadas) com suporte integrado a filtros de imagem, adição de texto e remoção de fundo. Projetado para funcionar em qualquer lugar, do **Termux** a servidores dedicados.
+Simple **WhatsApp sticker** engine for Node.js.
 
-[![NPM Version](https://img.shields.io/npm/v/@boruto_vk7/stickengine?style=flat-square)](https://www.npmjs.com/package/@boruto_vk7/stickengine)
-[![License](https://img.shields.io/npm/l/@boruto_vk7/stickengine?style=flat-square)](https://github.com/Borutovk7/StickEngine)
+- Static **and animated** WebP stickers  
+- Pack name / author EXIF (WhatsApp metadata)  
+- One-line API: `StickEngine.create()`  
+- **ESM + CommonJS**  
+- GIF / MP4 / WebP / PNG / JPG  
+
+> Requires **ffmpeg** + **ffprobe** on your system.
 
 ---
 
-## ✨ Funcionalidades
+## Install
 
-- 🎞️ **Figurinhas Animadas**: Suporte automático para GIFs e Vídeos (MP4).
-- 🎨 **Filtros Profissionais**: Sépia, Tons de Cinza, Inversão e Desfoque (Blur).
-- ✍️ **Texto Customizado**: Adicione legendas diretamente na figurinha.
-- ✂️ **Remoção de Fundo**: Integração com a API `remove.bg`.
-- 🧹 **Limpeza Automática**: Sistema de gerenciamento de arquivos temporários com o método `.clean()`.
-- 🏷️ **Metadados (Exif)**: Personalize o nome do pacote e o autor sem complicação.
-- 📱 **Termux Friendly**: Sem dependências nativas pesadas como `sharp`.
+```bash
+npm install @boruto_vk7/stickengine
+```
+
+```bash
+# system dependency
+sudo apt install ffmpeg   # Debian/Ubuntu
+# brew install ffmpeg     # macOS
+```
 
 ---
 
-## 🖼️ Exemplos Visuais
+## Quick start (easiest)
 
-| Filtro Séia + Texto | Figurinha Animada (Mockup) |
-| :---: | :---: |
-| ![Sepia Preview](assets/preview_sepia.png) | ![Animated Preview](assets/preview_animated.png) |
+### ESM / TypeScript
 
----
+```ts
+import StickEngine from '@boruto_vk7/stickengine';
 
-## 📦 Instalação
+// path | URL | Buffer
+const sticker = await StickEngine.create('./cat.gif', {
+  metadata: {
+    pack: 'My Pack',
+    author: 'Boruto',
+    emojis: ['😺'],
+  },
+});
 
-```bash
-npm install @boruto_vk7/stickengine
+console.log(sticker.path);    // /tmp/.../sticker_xxx.webp
+console.log(sticker.buffer);  // Buffer — send this to WhatsApp
+console.log(sticker.base64);  // base64 string
+console.log(sticker.animated);// true/false
+```
+
+### CommonJS
+
+```js
+const StickEngine = require('@boruto_vk7/stickengine').default;
+// or: const { StickEngine } = require('@boruto_vk7/stickengine');
+
+const sticker = await StickEngine.create('./photo.jpg', {
+  metadata: { pack: 'Cool Pack', author: 'Me' },
+});
 ```
 
-> **Requisito:** Certifique-se de ter o [FFmpeg](https://ffmpeg.org/) instalado no seu sistema. No Termux: `pkg install ffmpeg`.
+### Buffer only (bots)
+
+```ts
+const buf = await StickEngine.toBuffer(imageBuffer, {
+  metadata: { pack: 'Bot Pack', author: 'Waguri' },
+});
+// send buf as sticker
+```
 
 ---
 
-## 🚀 Como Usar (Exemplos Técnicos)
+## Baileys example
 
-### 1. Criando uma Figurinha Estática Simples
-```javascript
+```ts
 import StickEngine from '@boruto_vk7/stickengine';
 
-const engine = new StickEngine();
-engine.addFile('https://exemplo.com/foto.jpg');
+const sticker = await StickEngine.create(mediaBuffer, {
+  metadata: { pack: 'Waguri', author: 'Bot' },
+});
 
-const results = await engine.start();
-console.log('Caminho do WebP:', results[0].value);
-engine.clean();
+await sock.sendMessage(jid, {
+  sticker: sticker.buffer,
+});
 ```
 
-### 2. Figurinha Animada (GIF ou Vídeo)
-O motor detecta automaticamente a duração e converte para WebP animado.
-```javascript
-const engine = new StickEngine({
-  fps: 20, // Aumenta a fluidez
-  quality: 70 // Otimiza o tamanho para o WhatsApp
+---
+
+## Options
+
+```ts
+await StickEngine.create(input, {
+  metadata: {
+    pack: 'Pack name',
+    author: 'Author',
+    emojis: ['🔥'],
+    id: 'optional-pack-id',
+  },
+  fps: 15,          // animated FPS (default 15)
+  quality: 75,      // animated quality 1–100
+  maxDuration: 6,   // seconds (WhatsApp-friendly)
+  edit: {           // static images only
+    circle: true,
+    sepia: true,
+    brightness: 0.1,
+    text: { content: 'LOL', color: 'WHITE', stroke: true },
+  },
+  // transparent: 'REMOVE_BG_API_KEY', // static only
+  autoClean: false,
+  tempDir: './tmp_stickengine',
 });
+```
+
+| Option | Default | Notes |
+|--------|---------|--------|
+| `metadata.pack` | `StickEngine` | Pack title in WhatsApp |
+| `metadata.author` | `Borutovk7` | Publisher |
+| `fps` | `15` | Animated stickers |
+| `quality` | `75` | Auto-lowers if file > 1MB |
+| `maxDuration` | `6` | Cuts longer videos |
+| `edit` | `false` | Jimp filters (static only) |
+| `transparent` | `false` | remove.bg API key |
+| `autoClean` | `false` | Call `.clean()` yourself if needed |
 
-engine.addFile('./video_engracado.mp4');
-await engine.start();
-engine.clean();
+---
+
+## Result object
+
+```ts
+interface StickResult {
+  path: string;      // absolute .webp path
+  buffer: Buffer;    // file bytes
+  base64: string;    // no data: prefix
+  animated: boolean;
+  width: number;
+  height: number;
+  size: number;      // bytes
+}
 ```
 
-### 3. Aplicando Filtros e Texto
-```javascript
+---
+
+## More features
+
+### Text sticker
+
+```ts
 const engine = new StickEngine({
-  edit: {
-    sepia: true,
-    blur: 5,
-    text: {
-      content: 'MUITO BOM!',
-      alignmentY: 2 // 0: Topo, 1: Meio, 2: Baixo
-    }
-  }
+  metadata: { pack: 'TP', author: 'Me' },
 });
+const sticker = await engine.createTextSticker('TOP!', { color: 'WHITE' });
+```
+
+### Tray icon (96×96)
 
-engine.addFile(bufferDeImagem);
-await engine.start();
-engine.clean();
+```ts
+const engine = new StickEngine();
+const trayPath = await engine.createTrayIcon('./logo.png');
 ```
 
-### 4. Remoção de Fundo (Remove.bg)
-```javascript
-const engine = new StickEngine({
-  transparent: 'SUA_API_KEY_AQUI'
-});
+### Batch queue
+
+```ts
+const engine = new StickEngine({ metadata: { pack: 'Batch', author: 'Me' } });
+engine.add('./a.jpg', './b.gif', buffer);
+const results = await engine.start();
+// results[i].status === 'fulfilled' → results[i].value is the path
+```
+
+### Events
 
-engine.addFile('foto_com_fundo.png');
-await engine.start();
-engine.clean();
+```ts
+engine.on('st.start', ({ index }) => console.log('start', index));
+engine.on('st.info', (info) => console.log(info));
+engine.on('st.data', ({ file, animated }) => console.log(file, animated));
+engine.on('st.error', ({ error }) => console.error(error));
+engine.on('st.done', (result) => console.log(result.size));
 ```
 
 ---
 
-## ⚙️ Opções do Construtor
+## Animated WebP EXIF fix
 
-| Opção | Tipo | Padrão | Descrição |
-| :--- | :--- | :--- | :--- |
-| `metadata` | `Object` | `{ pack: 'StickEngine', author: 'Borutovk7' }` | Nome do pacote e autor. |
-| `edit` | `Object` | `false` | Filtros (`sepia`, `greyscale`, `invert`, `blur`) e `text`. |
-| `transparent` | `String` | `false` | Chave da API `remove.bg` para remover fundo. |
-| `autoClean` | `Boolean` | `true` | Habilita o rastreio de arquivos para limpeza. |
-| `quality` | `Number` | `80` | Qualidade do WebP (1-100). |
-| `fps` | `Number` | `15` | Frames por segundo para animações. |
+Older builds called `img.save()` on **animated** stickers, which throws:
 
----
+```text
+Using `save` for animations is not currently supported. Use `muxAnim` instead
+```
+
+This version:
 
-## 🤝 Contribuições
+1. Detects animation via `hasAnim` / `frameCount` / `frames`
+2. Saves animated WebP with **`muxAnim({ path, exif: true, ... })`**
+3. Falls back to `muxAnim` if `save()` still rejects
+
+Static stickers still use `save()`.
+
+---
 
-Contribuições são sempre bem-vindas! Sinta-se à vontade para abrir uma **Issue** ou enviar um **Pull Request**.
+## Requirements
 
-Desenvolvido por [Borutovk7](https://github.com/Borutovk7) e [Eduh Dev](https://github.com/EduhDev).
+- Node.js **≥ 18**
+- `ffmpeg` + `ffprobe` in `PATH`
 
 ---
 
-## 📄 Licença
+## License
 
-Este projeto está sob a licença [ISC](LICENSE).
+MIT · [Borutovk7](https://github.com/Borutovk7)