@boruto_vk7/stickengine 1.1.1 → 2.0.0

package/README.md

@@ -1,300 +1,233 @@
-# StickEngine
+<p align="center">
+  <img src="./logo.png" width="400" alt="Lagos Solutions"/>
+</p>
+
+<h1 align="center">StickEngine - Lagos Solutions</h1>
+<p align="center">
+  <strong>Motor profissional de figurinhas para WhatsApp</strong><br>
+  Estático e animado, com EXIF, marca d'água e suporte total ESM + CJS + TypeScript
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/@boruto_vk7/stickengine?style=flat-square&color=7c3aed" alt="npm version"/>
+  <img src="https://img.shields.io/node/v/@boruto_vk7/stickengine?style=flat-square&color=7c3aed" alt="node version"/>
+  <img src="https://img.shields.io/badge/License-MIT-7c3aed?style=flat-square" alt="license"/>
+  <img src="https://img.shields.io/badge/Lagos-Solutions-7c3aed?style=flat-square" alt="lagos"/>
+</p>
 
-**Professional WhatsApp sticker engine for Node.js.**
-
-Build production-ready **static and animated** stickers with correct EXIF pack metadata, transparent framing (no black bars), and a one-line API.
+---
 
-[![npm](https://img.shields.io/npm/v/@boruto_vk7/stickengine.svg)](https://www.npmjs.com/package/@boruto_vk7/stickengine)
-[![Node](https://img.shields.io/node/v/@boruto_vk7/stickengine.svg)](https://nodejs.org)
-[![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](./LICENSE)
+## 🚀 Instalação
 
 ```bash
 npm install @boruto_vk7/stickengine
 ```
 
----
-
-## Why StickEngine
-
-Most sticker helpers break on the details that matter in real bots:
-
-| Problem in typical libs | StickEngine |
-|-------------------------|-------------|
-| Black bars on portrait/landscape media | **True transparent pad** (`format=rgba` → `pad=…:black@0`) |
-| Animated WebP EXIF crashes (`save` vs `muxAnim`) | **Compatible with node-webpmux v1 + v3** |
-| Oversized animated stickers rejected by WA | **Auto quality/FPS shrink under ~1MB** |
-| Awkward queue-only APIs | **`StickEngine.create()` → `{ buffer, path, base64 }`** |
-| ESM *or* CJS only | **Dual package (import + require)** |
-
-Built for Baileys, Evolution, Venom, whatsapp-web.js and any stack that sends a WebP buffer.
+FFmpeg já incluso via `@ffmpeg-installer/ffmpeg`. Não precisa instalar manualmente.
 
 ---
 
-## Requirements
+## ✨ Funcionalidades
 
-- **Node.js ≥ 18**
-- **ffmpeg** + **ffprobe** available in `PATH`  
-  (or install `@ffmpeg-installer/ffmpeg` + `@ffprobe-installer/ffprobe` and set paths via `fluent-ffmpeg`)
-
-```bash
-# Debian / Ubuntu
-sudo apt install ffmpeg
-
-# macOS
-brew install ffmpeg
-```
+- ✅ **Todos os tipos de entrada:** Buffer, caminho local, URL https, data URI base64, base64 puro
+- ✅ **Todos os tipos de figurinha:** JPG, PNG, WEBP estático, GIF animado, MP4, WEBM
+- ✅ **5 modos de enquadramento:** `natural` (padrão WA), `cover`, `contain`, `fill`, `none`
+- ✅ **EXIF com pack e autor:** Compatível com node-webpmux v1 e v3
+- ✅ **Auto shrink:** Figurinhas animadas sempre abaixo de 1MB
+- ✅ **Dirtemp custom:** `Dirtemp`, `tempDir`, `dirTemp` - qualquer alias funciona
+- ✅ **Marca d'água:** `watermark: true/false` ou texto customizado
+- ✅ **Compatível:** ESM `import`, CJS `require()`, TypeScript `NodeNext` e `CommonJS`
+- ✅ **APIs antigas:** `sendImageAsSticker`, `imageToWebp`, `writeExifImg` ainda funcionam
 
 ---
 
-## Quick start
+## 📦 Uso Rápido
 
 ### ESM / TypeScript
-
-```ts
+```javascript
 import StickEngine from '@boruto_vk7/stickengine';
 
-const sticker = await StickEngine.create('./photo.jpg', {
+const sticker = await StickEngine.create('./foto.jpg', {
+  Dirtemp: './temp',
+  watermark: true,
   metadata: {
-    pack: 'StickEngine',
+    pack: 'Lagos Solutions',
     author: 'Borutovk7',
-    emojis: ['✨'],
-  },
+    emojis: ['🔥']
+  }
 });
 
-// WhatsApp-ready WebP
 await sock.sendMessage(jid, { sticker: sticker.buffer });
 ```
 
 ### CommonJS
-
-```js
-const StickEngine = require('@boruto_vk7/stickengine').default;
-
-const sticker = await StickEngine.create(buffer, {
-  metadata: { pack: 'My Pack', author: 'Bot' },
+```javascript
+const StickEngine = require('@boruto_vk7/stickengine');
+
+const buffer = await StickEngine.toBuffer('./video.mp4', {
+  Dirtemp: '/tmp/meus-stickers',
+  watermark: false,
+  fit: 'natural',
+  metadata: { pack: 'Meu Pack', author: 'Bot' }
 });
 ```
 
-### Even shorter
+### Com marca d'água
 
-```ts
-const buf = await StickEngine.toBuffer(media, {
-  metadata: { pack: 'Waguri', author: 'Evolution' },
+```javascript
+await StickEngine.create('./imagem.png', {
+  Dirtemp: './temp',
+  watermark: true,
+  metadata: { pack: 'Lagos', author: 'Solutions' }
 });
-```
-
-Accepts **file path**, **http(s) URL**, or **Buffer**.
-
----
-
-## Sticker framing (`fit`)
-
-By default StickEngine uses **`fit: 'cover'`** — the media **fills the full 512×512 square** (center-crop), so stickers look like normal WhatsApp stickers instead of a small image floating in empty space.
 
-```ts
-await StickEngine.create(input, {
-  fit: 'cover',   // default — full sticker square (crop edges if needed)
-  // fit: 'contain', // whole image + transparent margins (no black bars)
-  // fit: 'fill',    // stretch (distorts)
-  // fit: 'none',    // only shrink if larger than 512; no pad
+await StickEngine.create('./imagem.png', {
+  watermark: 'MEU TEXTO CUSTOM',
+  metadata: { pack: 'Pack', author: 'Author' }
 });
-```
-
-| `fit` | Look |
-|-------|------|
-| `cover` (default) | Edge-to-edge sticker, may crop top/bottom or sides |
-| `contain` | Full image visible, transparent padding (never black) |
-| `fill` | Stretched to square |
-| `none` | Original aspect, max 512 on the long side |
 
-`contain` always pads with **true alpha** (`format=rgba` + `pad=…:black@0`) — never opaque black bars.
-
----
+await StickEngine.create('./imagem.png', {
+  watermark: { text: 'LAGOS', position: 'center', margin: 20 },
+  metadata: { pack: 'Pack', author: 'Author' }
+});
 
-## Result object
-
-```ts
-interface StickResult {
-  path: string;       // absolute path to .webp
-  buffer: Buffer;     // send this to WhatsApp
-  base64: string;     // raw base64 (no data: prefix)
-  animated: boolean;
-  width: number;
-  height: number;
-  size: number;       // bytes
-}
+await StickEngine.create('./imagem.png', {
+  watermark: false,
+  metadata: { pack: 'Sem marca', author: 'Bot' }
+});
 ```
 
 ---
 
-## Options
+## 🎨 Modos de Enquadramento
 
-```ts
-await StickEngine.create(input, {
-  metadata: {
-    pack: 'Pack name shown in WhatsApp',
-    author: 'Publisher name',
-    emojis: ['🔥', '✨'],
-    id: 'optional-stable-pack-id',
-  },
-
-  fit: 'cover',       // cover | contain | fill | none
-  fps: 15,            // animated FPS
-  quality: 80,        // 1–100 (auto-reduced if anim > 1MB)
-  maxDuration: 6,     // seconds (WA-friendly)
-
-  edit: {
-    // static images only
-    circle: true,
-    greyscale: false,
-    sepia: false,
-    blur: 0,
-    brightness: 0,    // -1 … 1
-    contrast: 0,      // -1 … 1
-    text: {
-      content: 'TOP',
-      color: 'WHITE',
-      stroke: true,   // outlined caption
-    },
-  },
-
-  // transparent: 'REMOVE_BG_API_KEY', // static only (remove.bg)
-  autoClean: false,
-  tempDir: './tmp_stickengine',
-});
+```javascript
+await StickEngine.create(input, { fit: 'natural' });
 ```
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `metadata.pack` | `StickEngine` | Sticker pack title |
-| `metadata.author` | `Borutovk7` | Pack publisher |
-| `fit` | `cover` | Canvas fit — `cover` fills the sticker square |
-| `fps` | `15` | Animated frame rate |
-| `quality` | `80` | WebP quality; auto-lowers for large animations |
-| `maxDuration` | `6` | Trim long videos/GIFs |
-| `edit` | `false` | Jimp filters (static only) |
-| `transparent` | `false` | remove.bg API key / key list |
-| `autoClean` | `false` | Set `true` only if you manage file lifetime yourself |
+| Fit | Resultado |
+|-----|-----------|
+| `natural` (padrão) | Mantém proporção, lado maior = 512px - visual real do WhatsApp |
+| `cover` | Força 512x512 quadrado com corte central |
+| `contain` | Encaixa dentro de 512x512 com fundo transparente |
+| `fill` | Estica para 512x512 |
+| `none` | Só diminui se maior que 512, nunca aumenta |
 
 ---
 
-## Animated stickers & EXIF
+## 📁 Dirtemp Personalizado
 
-WhatsApp animated stickers are **animated WebP** with EXIF pack metadata.
+Aceita qualquer alias:
 
-StickEngine:
+```javascript
+new StickEngine({ Dirtemp: './minha-pasta' })
+new StickEngine({ tempDir: './minha-pasta' })
+new StickEngine({ dirTemp: './minha-pasta' })
+new StickEngine({ DirTemp: './minha-pasta' })
+```
 
-1. Detects GIF / MP4 / animated WebP  
-2. Encodes with `libwebp` (loop, alpha, duration cap)  
-3. Shrinks quality/FPS until size is under ~1MB  
-4. Writes EXIF using the correct **node-webpmux** path for your installed version  
-   - never crashes with `Using save for animations…`  
-   - falls back across v1 `muxAnim` and v3 `save({ frames })`
+Padrão: `os.tmpdir()/stickengine`
 
 ---
 
-## Baileys
-
-```ts
-import StickEngine from '@boruto_vk7/stickengine';
+## 💧 Marca d'água
 
-export async function sendSticker(sock: any, jid: string, media: Buffer) {
-  const { buffer } = await StickEngine.create(media, {
-    metadata: {
-      pack: 'Waguri Evolution',
-      author: 'Borutovk7',
-      emojis: ['💜'],
-    },
-    fit: 'cover',
-  });
-
-  await sock.sendMessage(jid, { sticker: buffer });
-}
+```javascript
+{ watermark: true }
+{ watermark: false }
+{ watermark: 'Texto Custom' }
+{ watermark: { text: 'Lagos', position: 'bottom-right' } }
+{ marcaDagua: true }
+{ marca_agua: true }
 ```
 
+Posições: `bottom-right`, `bottom-left`, `top-right`, `top-left`, `center`
+
 ---
 
-## More APIs
+## 🔄 Compatibilidade com código antigo
 
-### Instance pipeline
+### rename.js antigo
+```javascript
+const { sendImageAsSticker, sendVideoAsSticker } = require('@boruto_vk7/stickengine');
 
-```ts
-const engine = new StickEngine({
-  metadata: { pack: 'Studio', author: 'You' },
-  fit: 'cover',
+await sendImageAsSticker(conn, jid, './foto.jpg', quoted, {
+  packname: 'Meu Pack',
+  author: 'Bot',
+  categories: ['🔥']
 });
-
-const sticker = await engine.build('./clip.mp4');
-engine.clean(); // optional temp cleanup
-```
-
-### Batch queue
-
-```ts
-const engine = new StickEngine({ metadata: { pack: 'Batch', author: 'Bot' } });
-engine.add('./a.jpg', './b.gif', buffer);
-const results = await engine.start();
-// PromiseSettledResult<string>[] → value = path when fulfilled
 ```
 
-### Text sticker
+### exif.js antigo
+```javascript
+const { imageToWebp, writeExifImg } = require('@boruto_vk7/stickengine');
 
-```ts
-const engine = new StickEngine();
-const sticker = await engine.createTextSticker('ARISE', { color: 'WHITE' });
+const webpBuffer = await imageToWebp(buffer);
+const path = await writeExifImg(buffer, { packname: 'Pack', author: 'Author' });
 ```
 
-### Tray icon (96×96)
-
-```ts
-const trayPath = await engine.createTrayIcon('./logo.png');
-```
-
-### Events
-
-```ts
-engine.on('st.start', ({ index }) => {});
-engine.on('st.info', (info) => {});
-engine.on('st.data', ({ file, animated }) => {});
-engine.on('st.done', (result) => {});
-engine.on('st.error', ({ error }) => {});
-```
+Todos os inputs antigos funcionam:
+- `Buffer`
+- `data:image/png;base64,...`
+- `https://exemplo.com/foto.jpg`
+- `./caminho/local.jpg`
+- `base64 puro`
 
 ---
 
-## API surface
+## 📊 Tipos de Figurinha Testados
 
-| Method | Description |
-|--------|-------------|
-| `StickEngine.create(input, opts?)` | One-shot → `StickResult` |
-| `StickEngine.toBuffer(input, opts?)` | One-shot → `Buffer` |
-| `StickEngine.toBase64String(input, opts?)` | One-shot → base64 |
-| `engine.build(input)` | Instance one-shot |
-| `engine.addFile` / `engine.add` / `engine.start` | Batch queue |
-| `engine.createTextSticker(text, opts?)` | Text → sticker |
-| `engine.createTrayIcon(input)` | Pack tray WebP |
-| `engine.clean()` | Delete tracked temps |
-| `getBuffer(url)` | Download helper |
+- ✅ PNG estático 512x512
+- ✅ JPG 800x600
+- ✅ Retrato 1080x1920 -> 288x512 natural
+- ✅ Paisagem 1920x1080 -> 512x288 natural
+- ✅ PNG transparente
+- ✅ Buffer direto
+- ✅ Path local
+- ✅ Data URI base64
+- ✅ Base64 puro sem prefixo
+- ✅ URL remota com fallback emror.jpg
 
 ---
 
-## Project standards
+## ⚙️ Opções Completas
 
-- TypeScript source, dual **ESM + CJS** emit  
-- Strict typing for options and results  
-- Zero config for the happy path  
-- Designed for long-running bot processes  
+```javascript
+await StickEngine.create(input, {
+  Dirtemp: './temp',
+  tempDir: './temp',
+  watermark: true,
+  fit: 'natural',
+  fps: 15,
+  quality: 80,
+  maxDuration: 6,
+  metadata: {
+    pack: 'Lagos Solutions',
+    author: 'Borutovk7',
+    emojis: ['✨', '🔥'],
+    id: 'meu-pack-id'
+  }
+});
+```
 
 ---
 
-## Author
+## 🧪 Testes
 
-**Borutovk7** — creator of StickEngine.
+```bash
+npm run build
+node test_all_stickers.mjs
+```
 
-If you ship stickers at scale, this is the engine you want under the hood.
+Todos os testes passaram com FFmpeg incluso.
 
 ---
 
-## License
+## 📄 Licença
+
+MIT - Lagos Solutions
 
-MIT © Borutovk7
+<p align="center">
+  <strong>SOLUÇÕES INTELIGENTES. RESULTADOS REAIS.</strong><br>
+  <img src="./logo.png" width="200" alt="Lagos Solutions"/>
+</p>