@boruto_vk7/stickengine 0.0.6 → 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,130 +1,209 @@
-# 🚀 StickEngine
+# @boruto_vk7/stickengine
 
-O **StickEngine** é um motor de alta performance para criação de figurinhas do WhatsApp, projetado para ser simples para iniciantes e extremamente poderoso para desenvolvedores avançados.
+Simple **WhatsApp sticker** engine for Node.js.
+
+- 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.
 
 ---
 
-## 📦 1. Começando (Básico)
+## Install
 
-### Instalação
 ```bash
 npm install @boruto_vk7/stickengine
 ```
-> **Requisito**: Tenha o `ffmpeg` instalado no seu sistema.
-
-### Suporte Híbrido
-O módulo funciona tanto com **ESM** quanto **CommonJS**:
-- **ESM**: `import StickEngine from '@boruto_vk7/stickengine';`
-- **CJS**: `const StickEngine = require('@boruto_vk7/stickengine').default;`
 
-### Sua Primeira Figurinha
-Gere uma figurinha com apenas 3 linhas de código:
-```javascript
-const engine = new StickEngine();
-engine.addFile('./foto.jpg'); // Adiciona a imagem
-const results = await engine.start(); // Inicia o processamento
-console.log('Sticker salvo em:', results[0].value);
+```bash
+# system dependency
+sudo apt install ffmpeg   # Debian/Ubuntu
+# brew install ffmpeg     # macOS
 ```
 
 ---
 
-## 🛠️ 2. Personalizando (Intermediário)
+## Quick start (easiest)
 
-### Adicionando Nome e Autor (Metadados)
-Personalize as informações que aparecem quando alguém clica na figurinha no WhatsApp.
-```javascript
-const engine = new StickEngine({
+### ESM / TypeScript
+
+```ts
+import StickEngine from '@boruto_vk7/stickengine';
+
+// path | URL | Buffer
+const sticker = await StickEngine.create('./cat.gif', {
   metadata: {
-    pack: 'Meu Pack Incrível',
-    author: 'Borutovk7'
-  }
+    pack: 'My Pack',
+    author: 'Boruto',
+    emojis: ['😺'],
+  },
+});
+
+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' },
 });
 ```
 
-### Figurinhas Animadas (GIF e Vídeo)
-O motor detecta automaticamente se o arquivo é animado. Ele corta para 6 segundos e garante que o arquivo tenha menos de 1MB.
-```javascript
-engine.addFile('./video_engracado.mp4');
-engine.addFile('./dancinha.gif');
-await engine.start();
+### Buffer only (bots)
+
+```ts
+const buf = await StickEngine.toBuffer(imageBuffer, {
+  metadata: { pack: 'Bot Pack', author: 'Waguri' },
+});
+// send buf as sticker
 ```
 
 ---
 
-## 🎨 3. Efeitos Especiais (Avançado)
+## Baileys example
 
-### Recorte Circular e Filtros
-Transforme imagens quadradas em círculos e aplique filtros profissionais.
-```javascript
-const engine = new StickEngine({
-  edit: {
-    circle: true,     // Recorte circular
-    sepia: true,      // Filtro antigo
-    brightness: 0.2   // Aumenta o brilho
-  }
+```ts
+import StickEngine from '@boruto_vk7/stickengine';
+
+const sticker = await StickEngine.create(mediaBuffer, {
+  metadata: { pack: 'Waguri', author: 'Bot' },
+});
+
+await sock.sendMessage(jid, {
+  sticker: sticker.buffer,
 });
 ```
 
-### Legendas com Borda (Meme Style)
-Adicione texto que pode ser lido em qualquer fundo graças ao contorno (stroke).
-```javascript
-const engine = new StickEngine({
-  edit: {
-    text: {
-      content: 'QUEBRADO!',
-      color: 'WHITE',
-      stroke: true // Adiciona borda preta ao texto branco
-    }
-  }
+---
+
+## 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 |
+
+---
+
+## 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
+}
+```
+
 ---
 
-## 💎 4. Funções Profissionais (Expert)
+## More features
 
-### Texto para Figurinha (TP)
-Gere figurinhas de frases do zero, sem precisar de uma imagem de base.
-```javascript
-const path = await engine.createTextSticker("ESSA É TOP!", { 
-  color: 'WHITE',
-  background: 0x00000000 // Transparente
+### Text sticker
+
+```ts
+const engine = new StickEngine({
+  metadata: { pack: 'TP', author: 'Me' },
 });
+const sticker = await engine.createTextSticker('TOP!', { color: 'WHITE' });
 ```
 
-### Criando Ícone do Pacote (Tray Icon)
-Gere o ícone de bandeja (96x96) necessário para pacotes oficiais.
-```javascript
+### Tray icon (96×96)
+
+```ts
+const engine = new StickEngine();
 const trayPath = await engine.createTrayIcon('./logo.png');
 ```
 
-### Auto-Dimensionamento Inteligente
-O motor reduz automaticamente a qualidade e o FPS se a figurinha animada passar de 1MB, garantindo que ela sempre seja enviada com sucesso.
+### 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
+
+```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));
+```
 
 ---
 
-## 📑 5. Referência Técnica Completa
+## Animated WebP EXIF fix
+
+Older builds called `img.save()` on **animated** stickers, which throws:
+
+```text
+Using `save` for animations is not currently supported. Use `muxAnim` instead
+```
+
+This version:
+
+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()`.
+
+---
 
-### Opções do Construtor (`StickEngineOptions`)
-| Propriedade | Tipo | Padrão | Descrição |
-| :--- | :--- | :--- | :--- |
-| `quality` | `Number` | `80` | Qualidade do WebP (1-100). |
-| `fps` | `Number` | `15` | Frames por segundo para animados. |
-| `autoClean` | `Boolean` | `true` | Apaga temporários automaticamente. |
+## Requirements
 
-### Opções de Edição (`JimpOptions`)
-| Opção | Descrição |
-| :--- | :--- |
-| `circle` | Ativa o recorte circular. |
-| `brightness` | Ajusta o brilho (-1 a 1). |
-| `contrast` | Ajusta o contraste (-1 a 1). |
-| `blur` | Aplica desfoque. |
-| `text.stroke` | Adiciona contorno ao texto. |
+- Node.js **≥ 18**
+- `ffmpeg` + `ffprobe` in `PATH`
 
 ---
 
-## 🤝 Créditos
-Desenvolvido por **Borutovk7**.
+## License
 
-## 📄 Licença
-ISC
+MIT · [Borutovk7](https://github.com/Borutovk7)