@kaikybrofc/omnizap-system 2.1.8

package/README.md

@@ -0,0 +1,431 @@
+<img width="1318" height="352" alt="OmniZap banner" src="https://github.com/user-attachments/assets/d44835e7-021a-4c67-a0e7-5b858d51eb91" />
+
+![Node.js](https://img.shields.io/badge/Node.js-18%2B-3C873A?logo=node.js&logoColor=white)
+![JavaScript](https://img.shields.io/badge/JavaScript-ES2022-F7DF1E?logo=javascript&logoColor=000)
+![MySQL](https://img.shields.io/badge/MySQL-8%2B-4479A1?logo=mysql&logoColor=white)
+![Baileys](https://img.shields.io/badge/Baileys-WhatsApp%20SDK-25D366?logo=whatsapp&logoColor=white)
+![PM2](https://img.shields.io/badge/PM2-Process%20Manager-2B037A?logo=pm2&logoColor=white)
+![OpenAI](https://img.shields.io/badge/OpenAI-SDK-111111?logo=openai&logoColor=white)
+![License](https://img.shields.io/badge/License-MIT-0B6E4F?logo=opensourceinitiative&logoColor=white)
+
+O **OmniZap System** é uma plataforma de automação para WhatsApp usando **Node.js + Baileys**, com foco em:
+
+- comando por chat (grupos e privado)
+- persistência em MySQL
+- automações administrativas
+- mídia/figurinhas com packs persistentes
+- observabilidade (Prometheus/Grafana/Loki)
+
+**Versão atual:** `2.1.3`
+
+## Links oficiais do projeto
+
+- Site principal: https://omnizap.shop/
+- Catálogo web de stickers: https://omnizap.shop/stickers/
+- API Docs: https://omnizap.shop/api-docs/
+- Termos de uso: https://omnizap.shop/termos-de-uso/
+- Licença: https://omnizap.shop/licenca/
+
+## Recursos principais
+
+- Gerenciamento de grupos (admin, boas-vindas, despedida, anti-link, captcha).
+- Prefixo de comando por grupo.
+- Comandos de mídia (`play`, `playvid`, stickers e conversões).
+- Sticker packs persistentes com CRUD e envio com fallback.
+- Recursos de IA (`cat`, `catimg`, `catprompt`) com OpenAI.
+- Estatísticas (`ranking`, `rankingglobal`, `semmsg`, `user perfil`).
+- Suporte a LID/JID com reconciliação automática (`lid_map`).
+- Métricas e logs estruturados para operação em produção.
+
+## Pré-requisitos
+
+- Node.js 18+ recomendado.
+- MySQL 8+.
+- FFmpeg instalado e acessível no `PATH`.
+- PM2 (opcional): `npm i -g pm2`.
+- Docker Compose (opcional, para stack de observabilidade).
+
+## Instalação rápida
+
+1. Clone o repositório:
+
+```bash
+git clone https://github.com/Kaikygr/omnizap-system.git
+cd omnizap-system
+```
+
+2. Instale dependências:
+
+```bash
+npm install
+```
+
+3. Crie o `.env` a partir do exemplo:
+
+```bash
+cp .env.example .env
+```
+
+4. Ajuste as variáveis mínimas obrigatórias no `.env` (o restante já vem com defaults no `.env.example`):
+
+```env
+DB_HOST=localhost
+DB_USER=seu_usuario
+DB_PASSWORD=sua_senha
+DB_NAME=omnizap
+USER_ADMIN=seu_jid@s.whatsapp.net
+IMAGE_MENU=https://example.com/menu.png
+```
+
+Para recursos de IA (`cat`, `catimg`, `catprompt`), configure também:
+
+```env
+OPENAI_API_KEY=sua_chave
+```
+
+5. Inicialize banco e tabelas:
+
+```bash
+npm run db:init
+```
+
+6. Inicie o bot:
+
+```bash
+npm run start
+```
+
+7. Escaneie o QR Code no terminal.
+
+## Observações importantes de ambiente
+
+- `DB_NAME` recebe sufixo automaticamente:
+  - `NODE_ENV=development` => `_dev`
+  - `NODE_ENV=production` => `_prod`
+  - Se já terminar com `_dev` ou `_prod`, o nome é preservado.
+- `COMMAND_PREFIX` pode ser global e também por grupo (via comandos admin).
+- `LID_BACKFILL_ON_START=true` habilita backfill de `lid_map` no boot.
+- `LID_BACKFILL_BATCH` padrão do serviço: `50000`.
+
+## Referência de variáveis (`.env.example`)
+
+O `.env.example` foi atualizado para cobrir todas as variáveis atualmente referenciadas no código e no `docker-compose.yml`.
+
+Principais blocos do arquivo:
+
+- Core do bot (prefixo, admin, imagem de menu, logs e Baileys).
+- Banco MySQL (conexão, fila de escrita, monitor de query lenta).
+- Métricas/observabilidade do app (`METRICS_*`, `DB_QUERY_ALERT_THRESHOLDS`, social metrics).
+- OpenAI (chat, imagem, TTS, timeout e retry).
+- Mídia (`play`, TikTok, FFmpeg/FFprobe).
+- Sticker packs (storage, limites, auto-coleta, catálogo web).
+- XP e RPG Pokémon (economia, PvP, raids, social XP, canvas).
+- Stack de observabilidade no Docker (Prometheus, Grafana, Loki, Promtail e exporters).
+
+Variáveis legadas foram mantidas por compatibilidade (`QUOTE_API_URL`, `WAIFU_API_*`, `STORE_PATH`), mas não participam do fluxo principal atual.
+
+## Scripts npm
+
+- `npm run start`: inicia o app (`node index.js`).
+- `npm run dev`: alias de start.
+- `npm run db:init`: cria/valida schema e executa migrations.
+- `npm run pm2:prod`: sobe com PM2 usando `ecosystem.prod.config.cjs`.
+- `npm run deploy`: deploy automático de `public/` com cache-bust, backup, validação e reload do Nginx.
+- `npm run deploy:dry-run`: simula o deploy sem publicar/recarregar serviços.
+- `npm run release`: bump de versão `patch` + deploy + publish do package (com auto commit/push git).
+- `npm run release:minor`: bump `minor` + deploy + publish do package.
+- `npm run release:major`: bump `major` + deploy + publish do package.
+- `npm run test`: executa testes Node (`node --test`).
+- `npm run lint`: lint com ESLint.
+- `npm run lint:fix`: lint com correções automáticas.
+
+## Deploy automático (Nginx + cache-bust)
+
+Comando padrão:
+
+```bash
+npm run deploy
+```
+
+Variáveis úteis:
+
+- `DEPLOY_TARGET_DIR` (default: `/var/www/omnizap`)
+- `DEPLOY_NGINX_SERVICE` (default: `nginx`)
+- `DEPLOY_PM2_APP_NAME` (default: `omnizap-system-production`)
+- `DEPLOY_RESTART_PM2` (default: `1`)
+- `DEPLOY_CREATE_BACKUP` (default: `1`)
+- `DEPLOY_VERIFY_URL` (default: `https://omnizap.shop/`)
+- `DEPLOY_GITHUB_NOTIFY` (default: `1`) - cria/atualiza deployment no GitHub
+- `DEPLOY_GITHUB_ENVIRONMENT` (default: `production`)
+- `DEPLOY_GITHUB_REPO` (opcional, ex.: `kaikybrofc/omnizap-system`)
+- `DEPLOY_GITHUB_TOKEN` (opcional; se vazio usa `GITHUB_TOKEN`/`GH_TOKEN`)
+- `DEPLOY_PACKAGE_STEP` (default: `0`) - executa etapa de package durante o deploy
+- `DEPLOY_PACKAGE_INSTALL` (default: `1`) - instala dependências (`npm ci --omit=dev`)
+- `DEPLOY_PACKAGE_TEST` (default: `0`) - executa `npm test`
+- `DEPLOY_PACKAGE_PACK` (default: `0`) - gera artefato `npm pack`
+- `DEPLOY_PACKAGE_ARTIFACTS_DIR` (default: `.artifacts`) - pasta dos artefatos do pack
+- `DEPLOY_PACKAGE_PUBLISH` (default: `0`) - publica em registry npm
+- `DEPLOY_PACKAGE_REGISTRY` (default: `https://npm.pkg.github.com`)
+- `DEPLOY_PACKAGE_TOKEN` (opcional; fallback automático por tipo de registry)
+- `DEPLOY_PACKAGE_OTP` (opcional) - OTP para publish quando 2FA interativo for exigido
+- `DEPLOY_PACKAGE_SCOPE_OWNER` (opcional) - owner esperado do scope para publish (ex.: `kaikybrofc` ou sua org)
+- `DEPLOY_PACKAGE_TAG` (default: `latest`)
+- `DEPLOY_PACKAGE_PUBLISH_SKIP_IF_EXISTS` (default: `1`) - evita erro se versão já existir
+- `DEPLOY_PACKAGE_PUBLISH_SECONDARY` (default: `0`) - habilita publish secundário (dual publish)
+- `DEPLOY_PACKAGE_SECONDARY_REGISTRY` (default: `https://registry.npmjs.org`)
+- `DEPLOY_PACKAGE_SECONDARY_TOKEN` (opcional; fallback: `NPM_TOKEN`/`NODE_AUTH_TOKEN`/demais tokens)
+- `DEPLOY_PACKAGE_SECONDARY_OTP` (opcional) - OTP do npmjs para publish com 2FA
+- `DEPLOY_PACKAGE_SECONDARY_TAG` (default: `latest`)
+- `DEPLOY_PACKAGE_SECONDARY_ACCESS` (default: `public`) - usado para pacote escopado no npmjs
+- `DEPLOY_PACKAGE_SECONDARY_PUBLISH_SKIP_IF_EXISTS` (default: mesmo valor de `DEPLOY_PACKAGE_PUBLISH_SKIP_IF_EXISTS`)
+- `DEPLOY_PACKAGE_SECONDARY_TOKEN_KEYS` (opcional) - ordem customizada de fallback de tokens
+
+Para `npm.pkg.github.com`, prefira token do GitHub (`DEPLOY_GITHUB_TOKEN` ou `GITHUB_TOKEN`); `NPM_TOKEN` comum pode não autenticar no registry do GitHub.
+Para `npm.pkg.github.com`, o nome do pacote deve ser escopado com owner existente (`@owner/pacote`), por exemplo `@kaikybrofc/omnizap-system`.
+Para `registry.npmjs.org`, use token do npmjs (não token do GitHub). Se sua conta exigir 2FA para publish, use token granular com bypass 2FA habilitado ou informe OTP via `DEPLOY_PACKAGE_SECONDARY_OTP`.
+
+Exemplo sem restart do PM2:
+
+```bash
+DEPLOY_RESTART_PM2=0 npm run deploy
+```
+
+Exemplo com marcação explícita no GitHub:
+
+```bash
+DEPLOY_GITHUB_NOTIFY=1 DEPLOY_GITHUB_ENVIRONMENT=production npm run deploy
+```
+
+Exemplo com etapa package completa:
+
+```bash
+DEPLOY_PACKAGE_STEP=1 DEPLOY_PACKAGE_TEST=1 DEPLOY_PACKAGE_PACK=1 npm run deploy
+```
+
+Exemplo publicando no GitHub Packages:
+
+```bash
+DEPLOY_PACKAGE_STEP=1 DEPLOY_PACKAGE_PUBLISH=1 DEPLOY_PACKAGE_TOKEN=seu_token npm run deploy
+```
+
+Exemplo de dual publish (GitHub Packages + npmjs):
+
+```bash
+DEPLOY_PACKAGE_STEP=1 \
+DEPLOY_PACKAGE_PUBLISH=1 \
+DEPLOY_PACKAGE_PUBLISH_SECONDARY=1 \
+DEPLOY_PACKAGE_SECONDARY_TOKEN=seu_token_npmjs \
+npm run deploy
+```
+
+Comando único de release (patch + deploy + publish):
+
+```bash
+npm run release
+```
+
+`npm run release` agora executa publish primário + secundário por padrão (você pode desativar com `DEPLOY_PACKAGE_PUBLISH_SECONDARY=0`).
+
+Variáveis do fluxo de release (git):
+
+- `RELEASE_GIT_AUTO_COMMIT` (default: `1`) - commit automático se houver alterações pendentes
+- `RELEASE_GIT_AUTO_PUSH` (default: `1`) - push automático dos commits gerados
+- `RELEASE_GIT_REMOTE` (default: `origin`)
+- `RELEASE_GIT_BRANCH` (opcional; vazio usa branch atual)
+- `RELEASE_GIT_PRE_COMMIT_MESSAGE` (default: `chore(release): auto-commit before release`)
+- `RELEASE_GIT_COMMIT_VERSION` (default: `1`) - commita alteração da versão após sucesso
+- `RELEASE_GIT_VERSION_COMMIT_PREFIX` (default: `chore(release): v`)
+
+## Execução com PM2
+
+Após conectar o QR uma primeira vez em modo normal:
+
+```bash
+npm run pm2:prod
+```
+
+Comandos úteis:
+
+```bash
+pm2 status
+pm2 logs
+pm2 restart omnizap-system-production
+```
+
+> O QR Code não é exibido no fluxo do PM2. Conecte primeiro no modo normal.
+
+## Comandos principais
+
+Use `menu` para ver os comandos por categoria. Exemplos:
+
+- `<prefix>menu`
+- `<prefix>menu figurinhas`
+- `<prefix>menu midia`
+- `<prefix>menu ia`
+- `<prefix>menu stats`
+- `<prefix>menuadm`
+
+Comandos mais usados:
+
+- `<prefix>sticker` / `<prefix>s`
+- `<prefix>stickertext` / `<prefix>st` / `<prefix>stw` / `<prefix>stb`
+- `<prefix>toimg` / `<prefix>tovideo`
+- `<prefix>play <busca|url>`
+- `<prefix>playvid <busca|url>`
+- `<prefix>tiktok <url>`
+- `<prefix>quote`
+- `<prefix>cat`, `<prefix>catimg`, `<prefix>catprompt`
+- `<prefix>ranking`, `<prefix>rankingglobal`, `<prefix>semmsg`
+- `<prefix>user perfil`
+
+## Sticker packs persistentes
+
+Exemplos de fluxo:
+
+```text
+<prefix>pack create "Meu Pack"
+<prefix>pack add <pack>
+<prefix>pack list
+<prefix>pack info <pack>
+<prefix>pack send <pack>
+<prefix>pack publish <pack> <private|public|unlisted>
+<prefix>pack delete <pack>
+```
+
+Notas:
+
+- Edição de pack é restrita ao dono (`owner_jid`).
+- O envio tenta sticker pack nativo e faz fallback automático quando necessário.
+- O sistema captura “última figurinha” para simplificar `add` e `setcover`.
+
+### Catálogo web de packs
+
+O servidor HTTP de observabilidade também expõe um catálogo web simples para os packs publicados:
+
+- Página web: `http://localhost:9102/stickers`
+- API: `http://localhost:9102/api/sticker-packs`
+- Endpoint de métricas permanece em: `http://localhost:9102/metrics`
+
+Em produção (instância oficial):
+
+- Página web: `https://omnizap.shop/stickers/`
+- API: `https://omnizap.shop/api/sticker-packs`
+- API Docs: `https://omnizap.shop/api-docs/`
+
+Principais rotas da API:
+
+- `GET /api/sticker-packs?q=&visibility=public|unlisted|all&limit=&offset=`
+- `GET /api/sticker-packs/orphan-stickers?q=&limit=&offset=` (figurinhas salvas sem pack)
+- `GET /api/sticker-packs/:packKey`
+- `GET /api/sticker-packs/:packKey/stickers/:stickerId.webp`
+- `GET /api/sticker-packs/data-files?q=&limit=&offset=` (lista imagens da pasta `data`)
+- `GET /data/<caminho-da-imagem>` (acesso direto ao arquivo de imagem)
+
+## Suporte a LID/JID
+
+O WhatsApp pode alternar IDs entre `@lid` e `@s.whatsapp.net`.  
+O OmniZap resolve isso com um `sender_id` canônico para manter métricas/rankings consistentes.
+
+- Tabela dedicada: `lid_map`.
+- Cache em memória com TTL.
+- Reconciliação automática quando o JID real aparece.
+- Backfill opcional no startup.
+
+## Classificação de imagens (CLIP / MobileCLIP)
+
+Para categorizar packs e stickers solos (ex.: anime/game/real/cartoon/nsfw), foi adicionado um microserviço Python:
+
+- Caminho: `ml/clip_classifier`
+- Stack: `FastAPI + MobileCLIP (OpenCLIP) + PyTorch`
+- Endpoint: `POST /classify` (upload de imagem)
+
+Documentação e execução:
+
+```bash
+cd ml/clip_classifier
+cat README.md
+```
+
+## Observabilidade (Prometheus + Grafana + Loki)
+
+O projeto inclui `docker-compose.yml` com:
+
+- Prometheus
+- Grafana
+- Loki
+- Promtail
+- MySQL Exporter
+- Node Exporter
+
+Subir stack:
+
+```bash
+docker compose up -d
+```
+
+Setup recomendado de métricas MySQL:
+
+```bash
+sudo mysql < observability/mysql-setup.sql
+```
+
+Acessos padrão:
+
+- Grafana: `http://localhost:3003`
+- Prometheus: `http://localhost:9090`
+- Loki: `http://localhost:3100`
+- Métricas do app: `http://localhost:9102/metrics`
+
+Arquivos úteis:
+
+- `observability/prometheus.yml`
+- `observability/alert-rules.yml`
+- `observability/grafana/dashboards/omnizap-overview.json`
+- `observability/grafana/dashboards/omnizap-mysql.json`
+
+## Troubleshooting
+
+**QR não aparece no PM2**
+
+- Inicie com `npm run start`, conecte o QR e depois volte para PM2.
+- Se necessário, limpe sessão salva e reconecte.
+
+**Erro de conexão MySQL**
+
+- Verifique `DB_HOST`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`.
+- Confirme se o usuário possui permissão de leitura/escrita.
+
+**FFmpeg não encontrado**
+
+- Instale FFmpeg no sistema ou configure `FFMPEG_PATH`/`FFPROBE_PATH`.
+
+**Comando `play` falhando**
+
+- Verifique se o serviço configurado em `YTDLS_BASE_URL`/`YT_DLS_BASE_URL` está ativo.
+
+**Comando `tiktok` falhando**
+
+- Verifique se sua API local está ativa em `TIKTOK_EXTRACT_BASE_URL` + `TIKTOK_EXTRACT_PATH` (ex.: `http://127.0.0.1:8000/extract`).
+
+## Tecnologias
+
+- Node.js
+- MySQL (`mysql2`)
+- Baileys (`@whiskeysockets/baileys`)
+- OpenAI SDK
+- Axios
+- Canvas
+- PM2
+- Prometheus / Grafana / Loki
+
+## Contribuições
+
+1. Faça um fork.
+2. Crie uma branch: `git checkout -b feature/minha-feature`.
+3. Commit: `git commit -m "feat: minha feature"`.
+4. Push: `git push origin feature/minha-feature`.
+5. Abra um Pull Request.
+
+## Licença
+
+Licença MIT. Veja [`LICENSE`](LICENSE).

package/RELEASE-v2.1.2.md

@@ -0,0 +1,83 @@
+# v2.1.3
+
+Atualiza a versão para `2.1.3` e consolida o ciclo de entregas desde a `v2.1.2`.
+
+Período do ciclo: `2026-02-26` a `2026-02-27`  
+Comparação base: `v2.1.2..HEAD`  
+Escopo: **39 commits** e **71 arquivos alterados**
+
+## Destaques
+
+- Plataforma web de stickers expandida de ponta a ponta: criação de packs no browser, upload de mídia (imagem/vídeo), fluxo de publicação e dashboard de criador.
+- Marketplace e descoberta evoluídos: categorias, sorting, ranking de criadores, métricas globais, cards/UX mobile e melhorias de navegação.
+- SEO e indexação: `sitemap`, ajustes de páginas SEO por pack e controles de exposição NSFW no catálogo.
+- Classificação inteligente e curadoria automática reforçadas: pipeline CLIP/MobileCLIP/OpenCLIP, fila de reprocessamento, clustering semântico e otimizações do auto-pack por tags.
+- Admin panel consolidado com moderação: gestão de bans e role de moderador, com persistência de sessão Google Web.
+- Backend mais robusto: limpeza segura de órfãos, proteção de mutações, idempotência em uploads/publicação e novos caches para stats/sumários.
+- Runtime e resiliência: reconexão de socket aprimorada, tratamento de rejeições transitórias e ajustes de agendamento em background.
+- Banco e deploy: novas migrations para classificação/engajamento/workers/admin, e ajuste no nome do banco com sufixo por ambiente.
+
+## Banco de dados e migrations
+
+Este ciclo adiciona migrations estruturais importantes:
+
+- `20260226_0011_sticker_asset_classification.sql`
+- `20260226_0012_sticker_pack_engagement.sql`
+- `20260226_0013_sticker_marketplace_intelligence.sql`
+- `20260226_0014_sticker_pack_publish_flow.sql`
+- `20260226_0014_sticker_worker_queues.sql`
+- `20260226_0015_sticker_auto_pack_curation_integrity.sql`
+- `20260226_0016_sticker_web_google_auth_persistence.sql`
+- `20260226_0017_sticker_web_admin_ban.sql`
+- `20260226_0018_sticker_web_admin_moderator.sql`
+- `20260227_0019_sticker_classification_v2_signals.sql`
+- `20260227_0020_semantic_theme_clusters.sql`
+
+## Commits incluídos (v2.1.2..HEAD)
+
+- `b46a33f` Improve background scheduling, add cached stats and UI/status enhancements
+- `c43decb` Enable semantic clustering and improve auto-pack scheduler
+- `91f2950` Enhance socket reconnection and prioritize complete sticker packs
+- `64f8e73` Improve classification and auto-pack optimization
+- `d11d78b` Appends environment-based suffix to DB name
+- `b8ede5f` Add advanced auto-pack optimization and CLIP classification pipeline
+- `32e169f` Add SEO, sitemap and NSFW gating to sticker catalog
+- `7271a9b` Adds web links for sticker packs and sets auto-packs to unlisted
+- `7cd1151` Ignore transient rejections and force process exit
+- `5072a0e` Add admin moderator role and revamp admin panel UI
+- `84c08dd` Add admin panel and ban management
+- `27b387b` Persist Google web sessions and add client-side Google auth cache
+- `6c07feb` Improve mobile category-chip touch and scroll behavior
+- `c3ca0ea` Improve auto-pack-by-tags curation and pack metadata
+- `3f6c258` Fix mobile discover tabs behavior
+- `831c279` Adds marketplace global stats API and panel
+- `08fdafe` Add catalog sorting, creators ranking and pack UI improvements
+- `082ba82` Add safe pack management, orphan asset cleanup, and UX/network robustness
+- `d928227` Improve marketplace discovery UX
+- `97fe5f4` Bumps stickers app asset version
+- `d2d1843` Adds sticker upload API and improves creator dashboard UX
+- `be5506b` Adds creator pack management endpoints and dashboard UI
+- `589f671` Add creator profile with Google sign-in
+- `122c1e8` Switches CLIP classifier to MobileCLIP/OpenCLIP
+- `7385d30` Allow spaces in pack names and add tag typeahead
+- `2c5589c` Stops trimming input on field change
+- `067b6f9` Add web pack publish flow with Google auth and idempotent uploads
+- `6953768` Allow image/video uploads with WebP conversion
+- `b33c1b8` Add web pack creation and sticker upload UI/API
+- `2b23441` Add reprocess queue, cohesion scoring and ranking
+- `6342d2b` Add marketplace stats endpoint and homepage preview
+- `55cf8b7` Batch-scans and deduplicates catalog listings
+- `7819fe6` Adds automatic sticker pack curation by tags
+- `8ed61bc` Improve API docs and dynamic sidebar/UI for stickers
+- `d0fd86d` Adds support contact API and enhances sticker catalog UI
+- `c5cb106` Improves pack cards and mobile header UX
+- `3da0375` Adds categories filtering and pack engagement tracking
+- `d9bb604` Adds CLIP-based sticker classification
+- `fffc205` Enhances catalog and API docs UI
+
+## Notas de atualização
+
+- `package.json` atualizado para `2.1.3`.
+- `README.md` atualizado para refletir a versão atual.
+- Recomendado reiniciar o processo de produção após deploy (`pm2 restart ... --update-env`).
+- Atenção para comportamento de nome de banco por ambiente (`DB_NAME` com sufixo `_dev`/`_prod` quando aplicável).

package/app/config/adminIdentity.js

@@ -0,0 +1,87 @@
+import { encodeJid, getJidUser, isSameJidUser, normalizeJid } from './baileysConfig.js';
+import { extractUserIdInfo, resolveUserId, resolveUserIdCached } from '../services/lidMapService.js';
+
+const ADMIN_ENV_KEY = 'USER_ADMIN';
+
+const normalizePhoneDigits = (value) => String(value || '').replace(/\D+/g, '');
+
+export const getAdminRawValue = () => String(process.env[ADMIN_ENV_KEY] || '').trim();
+
+export const getAdminJid = () => {
+  const raw = getAdminRawValue();
+  if (!raw) return null;
+
+  let candidate = '';
+  if (raw.includes('@')) {
+    candidate = normalizeJid(raw) || raw;
+  } else {
+    const digits = normalizePhoneDigits(raw);
+    if (!digits) return null;
+    candidate = normalizeJid(encodeJid(digits, 's.whatsapp.net')) || '';
+  }
+
+  if (!candidate) return null;
+
+  const resolvedCached = resolveUserIdCached(extractUserIdInfo(candidate));
+  const normalizedResolved = normalizeJid(resolvedCached || candidate);
+  return normalizedResolved || candidate;
+};
+
+export const getAdminPhone = () => {
+  const adminJid = getAdminJid();
+  if (!adminJid) return null;
+
+  const user = getJidUser(adminJid);
+  if (user) return user;
+
+  const digits = normalizePhoneDigits(adminJid);
+  return digits || null;
+};
+
+export const resolveAdminJid = async () => {
+  const cached = getAdminJid();
+  if (!cached) return null;
+
+  try {
+    const resolved = await resolveUserId(extractUserIdInfo(cached));
+    return normalizeJid(resolved || cached) || cached;
+  } catch {
+    return cached;
+  }
+};
+
+export const isAdminSender = (senderJid) => {
+  const adminJid = getAdminJid();
+  if (!adminJid || !senderJid) return false;
+
+  const normalizedSender = normalizeJid(senderJid);
+  if (!normalizedSender) return false;
+
+  return isSameJidUser(normalizedSender, adminJid) || normalizedSender === adminJid;
+};
+
+export const isAdminSenderAsync = async (senderIdentity) => {
+  const senderInfo = extractUserIdInfo(senderIdentity);
+  if (!senderInfo.raw && !senderInfo.jid && !senderInfo.lid && !senderInfo.participantAlt) return false;
+
+  const normalizedSender = normalizeJid(senderInfo.jid || senderInfo.raw || '');
+  const cachedSender = resolveUserIdCached(senderInfo);
+  const normalizedCachedSender = normalizeJid(cachedSender || '');
+  const resolvedSender = await resolveUserId(senderInfo).catch(() => null);
+  const normalizedResolvedSender = normalizeJid(resolvedSender || '');
+  const senderCandidates = new Set(
+    [normalizedSender, normalizedCachedSender, normalizedResolvedSender].filter(Boolean),
+  );
+  if (!senderCandidates.size) return false;
+
+  const adminJid = (await resolveAdminJid()) || getAdminJid();
+  if (!adminJid) return false;
+  const normalizedAdmin = normalizeJid(adminJid) || adminJid;
+
+  for (const senderCandidate of senderCandidates) {
+    if (isSameJidUser(senderCandidate, normalizedAdmin) || senderCandidate === normalizedAdmin) {
+      return true;
+    }
+  }
+  return false;
+};