@omnizap-system/omnizap 2.5.12

package/app/modules/stickerPackModule/AGENT.md

@@ -0,0 +1,215 @@
+# StickerPackModule Agent Guide
+
+Este arquivo e destinado a agentes de IA para gerar respostas no contexto dos comandos deste modulo.
+
+## Fonte de Verdade
+
+- arquivo_base: `app/modules/stickerPackModule/commandConfig.json`
+- schema_version: `2.0.0`
+- module_enabled: `true`
+- generated_at: `2026-03-11T02:35:17.177Z`
+
+## Escopo do Modulo
+
+- module: `stickerPackModule`
+- source_files:
+- stickerPackCommandHandlers.js
+- total_commands: `1`
+- total_enabled_commands: `1`
+
+## Defaults Schema v2
+
+- inheritance_mode: deep_merge_with_command_overrides
+- compatibility_mode: legacy_and_v2_fields
+- legacy_field_aliases:
+- descricao: description
+- metodos_de_uso: usage
+- permissao_necessaria: permission
+- local_de_uso: contexts
+- informacoes_coletadas: collected_data
+- pre_condicoes: requirements
+- dependencias_externas: dependencies
+- efeitos_colaterais: side_effects
+- observabilidade: observability
+- privacidade: privacy
+- limite_uso_por_plano: plan_limits
+- argumentos: arguments
+- acesso: access
+- defaults.command:
+- enabled: true
+- category: figurinhas
+- version: 1.0.0
+- stability: stable
+- deprecated: false
+- replaced_by: null
+- risk_level: medium
+- defaults.requirements (legacy view):
+- requer_grupo: nao
+- requer_admin: nao
+- requer_admin_principal: nao
+- requer_google_login: sim
+- requer_nsfw: nao
+- requer_midia: nao
+- requer_mensagem_respondida: nao
+
+## Protocolo de Resposta para IA
+
+- Passo 1: identificar comando pelo token apos o prefixo.
+- Passo 2: resolver alias para nome canonico usando campo `aliases`.
+- Passo 3: validar `enabled`, `pre_condicoes`, permissao e local de uso.
+- Passo 4: se houver erro de uso, responder com `mensagens_uso` (quando existir) ou `metodos_de_uso`.
+- Passo 5: seguir `respostas_padrao` como fallback de texto.
+- Passo 6: considerar `informacoes_coletadas`, `privacidade` e `observabilidade` ao elaborar resposta.
+
+## Regras de Seguranca para IA
+
+- A IA orienta, mas nao executa acao administrativa automaticamente.
+- Nao inventar comandos, subcomandos ou permissao fora do JSON.
+- Sempre informar onde pode usar (grupo/privado) e quem pode usar.
+- Em duvida de permissao, responder com orientacao conservadora.
+
+## Catalogo de Comandos
+
+### pacote
+
+- id: stickerpack.pacote
+- aliases: packs, pacotes, pack
+- enabled: true
+- categoria: figurinhas
+- descricao: Gerencia packs de figurinhas (criar, listar, adicionar, enviar).
+- permissao_necessaria: usuario comum
+- version: 1.0.0
+- stability: stable
+- deprecated: nao
+- risk_level: low
+- local_de_uso:
+- privado
+- grupo
+- metodos_de_uso:
+- <prefix>pacote help
+- <prefix>pacote create meupack
+- <prefix>pacote list
+- <prefix>pacote add <pacote>
+- <prefix>pacote send <pacote>
+- mensagens_uso (variantes):
+- default:
+- <prefix>pacote help
+- <prefix>pacote create meupack
+- <prefix>pacote list
+- <prefix>pacote add <pacote>
+- <prefix>pacote send <pacote>
+- subcomandos:
+- help
+- create
+- list
+- info
+- add
+- setcover
+- setdesc
+- setpublisher
+- send
+- rename
+- remove
+- delete
+- reorder
+- argumentos:
+- subcomando | tipo: string | obrigatorio | validacao: ação de gerenciamento de pack | default: null | posicao: 0
+- parametros | tipo: array | opcional | validacao: dependente do subcomando | default: null | posicao: 1
+- pre_condicoes:
+- requer_grupo: nao
+- requer_admin: nao
+- requer_admin_principal: nao
+- requer_google_login: sim
+- requer_nsfw: nao
+- requer_midia: nao
+- requer_mensagem_respondida: nao
+- rate_limit:
+- max: 20
+- janela_ms: 60000
+- escopo: usuario
+- acesso:
+- somente_premium: nao
+- planos_permitidos: comum, premium
+- limite_uso_por_plano:
+- comum: max=12, janela_ms=300000, escopo=usuario
+- premium: max=45, janela_ms=300000, escopo=usuario
+- informacoes_coletadas:
+- identificador do chat (remoteJid)
+- identificador do remetente (senderJid)
+- texto do comando e argumentos
+- contexto da mensagem (citacao e mencoes, quando existir)
+- subcomando e argumentos do pack
+- figurinha da mensagem atual/citada (para add/setcover)
+- estado de rate limit por usuario
+- dados de packs do usuario no armazenamento interno
+- dependencias_externas:
+- banco de dados de packs
+- armazenamento de assets de figurinha
+- efeitos_colaterais:
+- cria/atualiza packs no banco
+- pode armazenar/remover assets de figurinha
+- respostas_padrao:
+- success: Comando executado com sucesso.
+- usage_error: Formato de uso inválido. Consulte metodos_de_uso.
+- permission_error: Permissão insuficiente para executar este comando.
+- sucesso: Comando executado com sucesso.
+- erro_uso: Formato de uso inválido. Consulte metodos_de_uso.
+- erro_permissao: Permissão insuficiente para executar este comando.
+- mensagens_sistema:
+- (nao informado)
+- limites_operacionais:
+- (nao informado)
+- opcoes:
+- toggle_on_off_status.type: toggle
+- toggle_on_off_status.allowed_actions: on, off, status
+- toggle_on_off_status.action_argument: acao
+- add_remove_list.type: list_management
+- add_remove_list.allowed_actions: add, remove, list
+- add_remove_list.action_argument: acao
+- approve_reject.type: moderation_decision
+- approve_reject.allowed_actions: approve, reject
+- approve_reject.action_argument: acao
+- approve_reject.requires_targets: true
+- set_status_reset.type: configuration_window
+- set_status_reset.allowed_actions: set, status, reset
+- set_status_reset.action_argument: valor
+- observabilidade:
+- event_name: command.executed
+- analytics_event: whatsapp_command_pack
+- tags_log: whatsapp, command, stickerPackModule, pack
+- nivel_log: info
+- privacidade:
+- dados_sensiveis:
+- sender_identifier
+- retencao: standard_app_logs
+- base_legal: service_execution_and_legitimate_interest
+- docs:
+- summary: Gerencia packs de figurinhas (criar, listar, adicionar, enviar).
+- usage_examples: <prefix>pacote help, <prefix>pacote create meupack, <prefix>pacote list, <prefix>pacote add <pacote>, <prefix>pacote send <pacote>
+- usage_variants.default: <prefix>pacote help, <prefix>pacote create meupack, <prefix>pacote list, <prefix>pacote add <pacote>, <prefix>pacote send <pacote>
+- behavior:
+- type: list_management
+- allowed_actions: add, remove, list
+- action_argument: acao
+- limits:
+- usage_description: rate limit por janela e limite de itens por pack
+- rate_limit.max: 20
+- rate_limit.janela_ms: 60000
+- rate_limit.escopo: usuario
+- access.somente_premium: false
+- access.planos_permitidos: comum, premium
+- plan_limits.comum.max: 12
+- plan_limits.comum.janela_ms: 300000
+- plan_limits.comum.escopo: usuario
+- plan_limits.premium.max: 45
+- plan_limits.premium.janela_ms: 300000
+- plan_limits.premium.escopo: usuario
+- discovery:
+- keywords: pacote, packs, figurinhas, privado, grupo
+- faq_queries: como usar pacote, o que faz pacote, comando pacote
+- user_phrasings: quero usar pacote, me ajuda com pacote, gerencia packs de figurinhas
+- suggestion_priority: 100
+- handler:
+- file: stickerPackCommandHandlers.js
+- method: handlePackCommand
+- command_case: pacote

package/app/modules/stickerPackModule/autoPackCollectorRuntime.js

@@ -0,0 +1,20 @@
+import logger from '#logger';
+import { createAutoPackCollector } from './autoPackCollectorService.js';
+import stickerPackService from './stickerPackServiceRuntime.js';
+import { saveStickerAssetFromBuffer } from './stickerStorageService.js';
+
+/**
+ * Instância singleton do coletor automático de figurinhas.
+ */
+const autoPackCollector = createAutoPackCollector({
+  logger,
+  stickerPackService,
+  saveStickerAssetFromBuffer,
+});
+
+/**
+ * Atalho para adicionar figurinhas ao pack automático do usuário.
+ */
+export const addStickerToAutoPack = autoPackCollector.addStickerToAutoPack;
+
+export default autoPackCollector;

package/app/modules/stickerPackModule/autoPackCollectorService.js

@@ -0,0 +1,357 @@
+import { STICKER_PACK_ERROR_CODES, StickerPackError } from './stickerPackErrors.js';
+import { sanitizeText } from './stickerPackUtils.js';
+
+/**
+ * Serviço responsável por direcionar figurinhas recém-criadas para packs automáticos.
+ */
+const DEFAULT_AUTO_PACK_NAME = process.env.STICKER_PACK_AUTO_PACK_NAME || 'pack';
+const AUTO_PACK_TARGET_VISIBILITY = 'unlisted';
+const AUTO_COLLECT_ENABLED = process.env.STICKER_PACK_AUTO_COLLECT_ENABLED !== 'false';
+const AUTO_PACK_NAME_MAX_LENGTH = 120;
+const AUTO_PACK_DESCRIPTION_MARKER = '[auto-pack:collector]';
+const AUTO_PACK_DESCRIPTION_TEXT = 'Coleção automática de figurinhas criadas pelo usuário.';
+const normalizeVisibility = (value) =>
+  String(value || '')
+    .trim()
+    .toLowerCase();
+
+/**
+ * Escapa texto para uso seguro em RegExp.
+ *
+ * @param {unknown} value Valor de entrada.
+ * @returns {string} Valor escapado.
+ */
+const escapeRegex = (value) => String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * Remove acentos para facilitar normalização de nomes.
+ *
+ * @param {unknown} value Valor de entrada.
+ * @returns {string} Texto sem diacríticos.
+ */
+const removeDiacritics = (value) =>
+  String(value || '')
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '');
+
+/**
+ * Gera nome de pack automático válido no padrão aceito.
+ *
+ * @param {unknown} value Nome base.
+ * @param {{ fallback?: string, maxLength?: number }} [options] Configurações de fallback/tamanho.
+ * @returns {string} Nome normalizado.
+ */
+const normalizeAutoPackName = (value, { fallback = 'pack', maxLength = AUTO_PACK_NAME_MAX_LENGTH } = {}) => {
+  const sanitized = sanitizeText(value, maxLength, { allowEmpty: true }) || '';
+  const normalized = removeDiacritics(sanitized)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '')
+    .slice(0, maxLength);
+
+  return normalized || fallback;
+};
+
+const buildAutoPackDescription = () => `${AUTO_PACK_DESCRIPTION_TEXT} ${AUTO_PACK_DESCRIPTION_MARKER}`.trim();
+
+const isThemeCurationAutoPack = (pack) => {
+  if (!pack || typeof pack !== 'object') return false;
+  const description = String(pack.description || '').toLowerCase();
+  if (description.includes('[auto-theme:') || description.includes('[auto-tag:')) return true;
+  if (
+    String(pack.name || '')
+      .trim()
+      .toLowerCase()
+      .startsWith('[auto]')
+  )
+    return true;
+  return Boolean(String(pack.pack_theme_key || '').trim());
+};
+
+const isAutoCollectorPack = (pack) => {
+  if (!pack || typeof pack !== 'object') return false;
+  if (isThemeCurationAutoPack(pack)) return false;
+
+  const description = String(pack.description || '').toLowerCase();
+  if (description.includes(AUTO_PACK_DESCRIPTION_MARKER)) return true;
+  if (description.includes('coleção automática de figurinhas criadas pelo usuário.')) return true;
+
+  const normalizedName = normalizeAutoPackName(pack.name, {
+    fallback: '',
+    maxLength: AUTO_PACK_NAME_MAX_LENGTH,
+  });
+  if (!normalizedName) return false;
+
+  const base = normalizeAutoPackName(DEFAULT_AUTO_PACK_NAME, {
+    fallback: 'pack',
+    maxLength: AUTO_PACK_NAME_MAX_LENGTH,
+  });
+  const matcher = new RegExp(`^${escapeRegex(base.toLowerCase())}\\d+$`, 'i');
+  const looksLikeLegacyCollector = matcher.test(normalizedName);
+  if (looksLikeLegacyCollector) return true;
+
+  return pack.is_auto_pack === true || Number(pack.is_auto_pack || 0) === 1;
+};
+
+const isUserManagedPackCandidate = (pack) => {
+  if (!pack || typeof pack !== 'object') return false;
+  if (isThemeCurationAutoPack(pack)) return false;
+  if (isAutoCollectorPack(pack)) return false;
+  return Number(pack.is_auto_pack || 0) !== 1;
+};
+
+/**
+ * Monta candidato incremental para nome de pack automático.
+ *
+ * @param {string} base Base do nome.
+ * @param {number} index Índice incremental.
+ * @returns {string} Nome candidato.
+ */
+const buildAutoPackCandidate = (base, index) => {
+  const suffix = String(index);
+  const maxBaseLength = Math.max(1, AUTO_PACK_NAME_MAX_LENGTH - suffix.length);
+  const trimmedBase = normalizeAutoPackName(base, { fallback: 'pack', maxLength: maxBaseLength });
+  return `${trimmedBase}${suffix}`;
+};
+
+/**
+ * Define o próximo nome disponível para auto packs.
+ *
+ * @param {Array<{name?: string}>} packs Packs já existentes.
+ * @returns {string} Nome único sugerido.
+ */
+const makeAutoPackName = (packs) => {
+  const base = normalizeAutoPackName(DEFAULT_AUTO_PACK_NAME, {
+    fallback: 'pack',
+    maxLength: AUTO_PACK_NAME_MAX_LENGTH,
+  });
+  const normalizedBase = base.toLowerCase();
+  const existingNames = packs
+    .map((pack) => normalizeAutoPackName(pack?.name, { fallback: '', maxLength: AUTO_PACK_NAME_MAX_LENGTH }))
+    .filter(Boolean)
+    .map((name) => name.toLowerCase());
+  const existingSet = new Set(existingNames);
+  const usedIndexes = new Set();
+  const matcher = new RegExp(`^${escapeRegex(normalizedBase)}(\\d+)?$`, 'i');
+
+  for (const name of existingNames) {
+    const match = name.match(matcher);
+    if (!match) continue;
+
+    if (!match[1]) {
+      usedIndexes.add(1);
+      continue;
+    }
+
+    const parsedIndex = Number(match[1]);
+    if (Number.isInteger(parsedIndex) && parsedIndex > 0) {
+      usedIndexes.add(parsedIndex);
+    }
+  }
+
+  let index = 1;
+  while (index < 10_000) {
+    const candidate = buildAutoPackCandidate(base, index);
+    if (!usedIndexes.has(index) && !existingSet.has(candidate.toLowerCase())) {
+      return candidate;
+    }
+    index += 1;
+  }
+
+  const fallbackIndex = Math.max(1, packs.length + 1);
+  return buildAutoPackCandidate(base, fallbackIndex);
+};
+
+/**
+ * Cria coletor automático de figurinhas para packs.
+ *
+ * @param {{
+ *   enabled?: boolean,
+ *   logger?: { info?: Function, warn?: Function, error?: Function, debug?: Function },
+ *   stickerPackService?: object,
+ *   saveStickerAssetFromBuffer?: Function,
+ * }} [options] Dependências/configurações de runtime.
+ * @returns {{ addStickerToAutoPack: Function }} API do coletor.
+ */
+export function createAutoPackCollector(options = {}) {
+  const deps = {
+    logger: {
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    },
+    stickerPackService: null,
+    saveStickerAssetFromBuffer: null,
+    ...options,
+  };
+
+  const isEnabled = options.enabled ?? AUTO_COLLECT_ENABLED;
+
+  if (isEnabled) {
+    if (!deps.stickerPackService || typeof deps.stickerPackService.listPacks !== 'function') {
+      throw new Error('createAutoPackCollector: stickerPackService inválido.');
+    }
+
+    if (typeof deps.saveStickerAssetFromBuffer !== 'function') {
+      throw new Error('createAutoPackCollector: saveStickerAssetFromBuffer é obrigatório.');
+    }
+  }
+
+  const ensureAutoPackVisibility = async ({ ownerJid, pack }) => {
+    if (!pack) return pack;
+
+    if (normalizeVisibility(pack.visibility) === AUTO_PACK_TARGET_VISIBILITY) {
+      return pack;
+    }
+
+    if (typeof deps.stickerPackService.setPackVisibility !== 'function') {
+      return { ...pack, visibility: AUTO_PACK_TARGET_VISIBILITY };
+    }
+
+    try {
+      const updated = await deps.stickerPackService.setPackVisibility({
+        ownerJid,
+        identifier: pack.id || pack.pack_key,
+        visibility: AUTO_PACK_TARGET_VISIBILITY,
+      });
+
+      deps.logger.info('Visibilidade do pack automático ajustada para unlisted.', {
+        action: 'sticker_pack_auto_collect_visibility_adjusted',
+        owner_jid: ownerJid,
+        pack_id: updated?.id || pack.id || null,
+      });
+
+      return updated || { ...pack, visibility: AUTO_PACK_TARGET_VISIBILITY };
+    } catch (error) {
+      deps.logger.warn('Falha ao ajustar visibilidade do pack automático.', {
+        action: 'sticker_pack_auto_collect_visibility_adjust_failed',
+        owner_jid: ownerJid,
+        pack_id: pack.id || null,
+        error: error?.message,
+      });
+      return pack;
+    }
+  };
+
+  const ensureTargetPack = async ({ ownerJid, senderName }) => {
+    const packs = await deps.stickerPackService.listPacks({ ownerJid, limit: 30 });
+    if (packs.length > 0) {
+      // Prioriza pack gerenciado pelo usuário (pack atual/manual).
+      const userManagedPacks = packs.filter((entry) => isUserManagedPackCandidate(entry));
+      if (userManagedPacks.length > 0) {
+        return {
+          pack: userManagedPacks[0],
+          packs,
+        };
+      }
+
+      const managedAutoPacks = packs.filter((entry) => isAutoCollectorPack(entry));
+      const preferredPack = managedAutoPacks.find((entry) => normalizeVisibility(entry?.visibility) === AUTO_PACK_TARGET_VISIBILITY) || managedAutoPacks[0] || null;
+
+      if (preferredPack) {
+        const ensuredPack = await ensureAutoPackVisibility({ ownerJid, pack: preferredPack });
+        return {
+          pack: ensuredPack,
+          packs,
+        };
+      }
+    }
+
+    const created = await deps.stickerPackService.createPack({
+      ownerJid,
+      name: makeAutoPackName([]),
+      publisher: sanitizeText(senderName, 120, { allowEmpty: true }) || 'OmniZap',
+      description: buildAutoPackDescription(),
+      visibility: AUTO_PACK_TARGET_VISIBILITY,
+      isAutoPack: true,
+    });
+
+    return {
+      pack: created,
+      packs: [created],
+    };
+  };
+
+  const addStickerToAutoPack = async ({ ownerJid, senderName, stickerBuffer }) => {
+    if (!isEnabled) {
+      return { status: 'skipped', reason: 'disabled' };
+    }
+
+    if (!Buffer.isBuffer(stickerBuffer) || !stickerBuffer.length) {
+      return { status: 'skipped', reason: 'invalid_buffer' };
+    }
+
+    const asset = await deps.saveStickerAssetFromBuffer({
+      ownerJid,
+      buffer: stickerBuffer,
+      mimetype: 'image/webp',
+    });
+
+    const { pack: targetPack, packs } = await ensureTargetPack({ ownerJid, senderName });
+
+    try {
+      const updated = await deps.stickerPackService.addStickerToPack({
+        ownerJid,
+        identifier: targetPack.id,
+        asset,
+      });
+
+      deps.logger.info('Figurinha adicionada automaticamente ao pack.', {
+        action: 'sticker_pack_auto_collect',
+        owner_jid: ownerJid,
+        pack_id: updated.id,
+        sticker_id: asset.id,
+      });
+
+      return {
+        status: 'added',
+        pack: updated,
+        asset,
+      };
+    } catch (error) {
+      if (error instanceof StickerPackError && error.code === STICKER_PACK_ERROR_CODES.DUPLICATE_STICKER) {
+        return {
+          status: 'duplicate',
+          pack: targetPack,
+          asset,
+        };
+      }
+
+      if (error instanceof StickerPackError && error.code === STICKER_PACK_ERROR_CODES.PACK_LIMIT_REACHED) {
+        const created = await deps.stickerPackService.createPack({
+          ownerJid,
+          name: makeAutoPackName(packs),
+          publisher: sanitizeText(senderName, 120, { allowEmpty: true }) || targetPack.publisher || 'OmniZap',
+          description: buildAutoPackDescription(),
+          visibility: AUTO_PACK_TARGET_VISIBILITY,
+          isAutoPack: true,
+        });
+
+        const updated = await deps.stickerPackService.addStickerToPack({
+          ownerJid,
+          identifier: created.id,
+          asset,
+        });
+
+        deps.logger.info('Figurinha adicionada ao novo pack automático após limite.', {
+          action: 'sticker_pack_auto_collect_rollover',
+          owner_jid: ownerJid,
+          pack_id: updated.id,
+          sticker_id: asset.id,
+        });
+
+        return {
+          status: 'added',
+          pack: updated,
+          asset,
+        };
+      }
+
+      throw error;
+    }
+  };
+
+  return {
+    addStickerToAutoPack,
+  };
+}