@kaikybrofc/omnizap-system 2.1.8

package/app/modules/stickerPackModule/stickerPackEngagementRepository.js

@@ -0,0 +1,108 @@
+import { executeQuery, TABLES } from '../../../database/index.js';
+
+const normalizeEngagementRow = (row) => ({
+  pack_id: row?.pack_id || null,
+  open_count: Number(row?.open_count || 0),
+  like_count: Number(row?.like_count || 0),
+  dislike_count: Number(row?.dislike_count || 0),
+  score: Number(row?.like_count || 0) - Number(row?.dislike_count || 0),
+  updated_at: row?.updated_at || null,
+});
+
+const EMPTY_ENGAGEMENT = Object.freeze({
+  open_count: 0,
+  like_count: 0,
+  dislike_count: 0,
+  score: 0,
+  updated_at: null,
+});
+
+export const getEmptyStickerPackEngagement = () => ({ ...EMPTY_ENGAGEMENT });
+
+export async function listStickerPackEngagementByPackIds(packIds, connection = null) {
+  const ids = Array.from(new Set((Array.isArray(packIds) ? packIds : []).filter(Boolean)));
+  if (!ids.length) return new Map();
+
+  const placeholders = ids.map(() => '?').join(', ');
+  const rows = await executeQuery(
+    `SELECT pack_id, open_count, like_count, dislike_count, updated_at
+     FROM ${TABLES.STICKER_PACK_ENGAGEMENT}
+     WHERE pack_id IN (${placeholders})`,
+    ids,
+    connection,
+  );
+
+  const byPackId = new Map();
+  rows.forEach((row) => {
+    const normalized = normalizeEngagementRow(row);
+    if (normalized.pack_id) byPackId.set(normalized.pack_id, normalized);
+  });
+  return byPackId;
+}
+
+export async function getStickerPackEngagementByPackId(packId, connection = null) {
+  if (!packId) return getEmptyStickerPackEngagement();
+  const rows = await executeQuery(
+    `SELECT pack_id, open_count, like_count, dislike_count, updated_at
+     FROM ${TABLES.STICKER_PACK_ENGAGEMENT}
+     WHERE pack_id = ?
+     LIMIT 1`,
+    [packId],
+    connection,
+  );
+
+  if (!rows?.[0]) return getEmptyStickerPackEngagement();
+  return normalizeEngagementRow(rows[0]);
+}
+
+export async function incrementStickerPackOpen(packId, connection = null) {
+  if (!packId) return getEmptyStickerPackEngagement();
+
+  await executeQuery(
+    `INSERT INTO ${TABLES.STICKER_PACK_ENGAGEMENT}
+      (pack_id, open_count, like_count, dislike_count, last_opened_at)
+     VALUES (?, 1, 0, 0, CURRENT_TIMESTAMP)
+     ON DUPLICATE KEY UPDATE
+       open_count = open_count + 1,
+       last_opened_at = CURRENT_TIMESTAMP,
+       updated_at = CURRENT_TIMESTAMP`,
+    [packId],
+    connection,
+  );
+
+  return getStickerPackEngagementByPackId(packId, connection);
+}
+
+export async function incrementStickerPackLike(packId, connection = null) {
+  if (!packId) return getEmptyStickerPackEngagement();
+
+  await executeQuery(
+    `INSERT INTO ${TABLES.STICKER_PACK_ENGAGEMENT}
+      (pack_id, open_count, like_count, dislike_count)
+     VALUES (?, 0, 1, 0)
+     ON DUPLICATE KEY UPDATE
+       like_count = like_count + 1,
+       updated_at = CURRENT_TIMESTAMP`,
+    [packId],
+    connection,
+  );
+
+  return getStickerPackEngagementByPackId(packId, connection);
+}
+
+export async function incrementStickerPackDislike(packId, connection = null) {
+  if (!packId) return getEmptyStickerPackEngagement();
+
+  await executeQuery(
+    `INSERT INTO ${TABLES.STICKER_PACK_ENGAGEMENT}
+      (pack_id, open_count, like_count, dislike_count)
+     VALUES (?, 0, 0, 1)
+     ON DUPLICATE KEY UPDATE
+       dislike_count = dislike_count + 1,
+       updated_at = CURRENT_TIMESTAMP`,
+    [packId],
+    connection,
+  );
+
+  return getStickerPackEngagementByPackId(packId, connection);
+}

package/app/modules/stickerPackModule/stickerPackErrors.js

@@ -0,0 +1,30 @@
+/**
+ * Erro padrão para operações relacionadas a packs de figurinha.
+ */
+export class StickerPackError extends Error {
+  /**
+   * @param {string} code Código semântico do erro.
+   * @param {string} message Mensagem amigável para logs/cliente.
+   * @param {unknown} [details=null] Objeto técnico opcional para diagnóstico.
+   */
+  constructor(code, message, details = null) {
+    super(message);
+    this.name = 'StickerPackError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+/**
+ * Catálogo de códigos de erro usados pelo domínio de sticker pack.
+ */
+export const STICKER_PACK_ERROR_CODES = {
+  INVALID_INPUT: 'INVALID_INPUT',
+  PACK_NOT_FOUND: 'PACK_NOT_FOUND',
+  NOT_ALLOWED: 'NOT_ALLOWED',
+  STICKER_NOT_FOUND: 'STICKER_NOT_FOUND',
+  PACK_LIMIT_REACHED: 'PACK_LIMIT_REACHED',
+  DUPLICATE_STICKER: 'DUPLICATE_STICKER',
+  STORAGE_ERROR: 'STORAGE_ERROR',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+};

package/app/modules/stickerPackModule/stickerPackInteractionEventRepository.js

@@ -0,0 +1,110 @@
+import { executeQuery, TABLES } from '../../../database/index.js';
+
+const clamp = (value, fallback, min, max) => {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) return fallback;
+  return Math.max(min, Math.min(max, Math.floor(numeric)));
+};
+
+const normalizeInteraction = (value) => {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (['open', 'like', 'dislike'].includes(normalized)) return normalized;
+  return null;
+};
+
+const sanitizeKey = (value, maxLength = 120) => {
+  const normalized = String(value || '')
+    .trim()
+    .replace(/\s+/g, ' ')
+    .slice(0, maxLength);
+  return normalized || null;
+};
+
+export async function createStickerPackInteractionEvent(
+  { packId, interaction, actorKey = null, sessionKey = null, source = null },
+  connection = null,
+) {
+  const normalizedInteraction = normalizeInteraction(interaction);
+  if (!packId || !normalizedInteraction) return false;
+
+  await executeQuery(
+    `INSERT INTO ${TABLES.STICKER_PACK_INTERACTION_EVENT}
+      (pack_id, interaction, actor_key, session_key, source)
+     VALUES (?, ?, ?, ?, ?)`,
+    [packId, normalizedInteraction, sanitizeKey(actorKey), sanitizeKey(sessionKey), sanitizeKey(source, 32)],
+    connection,
+  );
+  return true;
+}
+
+export async function listStickerPackInteractionStatsByPackIds(
+  packIds,
+  { horizonHours = 24, baselineDays = 7 } = {},
+  connection = null,
+) {
+  const ids = Array.from(new Set((Array.isArray(packIds) ? packIds : []).filter(Boolean)));
+  if (!ids.length) return new Map();
+
+  const safeHorizonHours = clamp(horizonHours, 24, 1, 240);
+  const safeBaselineDays = clamp(baselineDays, 7, 2, 60);
+  const placeholders = ids.map(() => '?').join(', ');
+
+  const rows = await executeQuery(
+    `SELECT
+       pack_id,
+       SUM(CASE WHEN interaction = 'open' AND created_at >= (UTC_TIMESTAMP() - INTERVAL ${safeHorizonHours} HOUR) THEN 1 ELSE 0 END) AS open_horizon,
+       SUM(CASE WHEN interaction = 'open' AND created_at >= (UTC_TIMESTAMP() - INTERVAL ${safeBaselineDays} DAY) THEN 1 ELSE 0 END) AS open_baseline,
+       SUM(CASE WHEN interaction = 'like' AND created_at >= (UTC_TIMESTAMP() - INTERVAL ${safeHorizonHours} HOUR) THEN 1 ELSE 0 END) AS like_horizon,
+       SUM(CASE WHEN interaction = 'like' AND created_at >= (UTC_TIMESTAMP() - INTERVAL ${safeBaselineDays} DAY) THEN 1 ELSE 0 END) AS like_baseline,
+       SUM(CASE WHEN interaction = 'dislike' AND created_at >= (UTC_TIMESTAMP() - INTERVAL ${safeHorizonHours} HOUR) THEN 1 ELSE 0 END) AS dislike_horizon,
+       SUM(CASE WHEN interaction = 'dislike' AND created_at >= (UTC_TIMESTAMP() - INTERVAL ${safeBaselineDays} DAY) THEN 1 ELSE 0 END) AS dislike_baseline
+     FROM ${TABLES.STICKER_PACK_INTERACTION_EVENT}
+     WHERE pack_id IN (${placeholders})
+     GROUP BY pack_id`,
+    ids,
+    connection,
+  );
+
+  const byPackId = new Map();
+  for (const row of rows) {
+    byPackId.set(row.pack_id, {
+      pack_id: row.pack_id,
+      open_horizon: Number(row.open_horizon || 0),
+      open_baseline: Number(row.open_baseline || 0),
+      like_horizon: Number(row.like_horizon || 0),
+      like_baseline: Number(row.like_baseline || 0),
+      dislike_horizon: Number(row.dislike_horizon || 0),
+      dislike_baseline: Number(row.dislike_baseline || 0),
+    });
+  }
+  return byPackId;
+}
+
+export async function listViewerRecentPackIds(
+  viewerKey,
+  { days = 30, limit = 120 } = {},
+  connection = null,
+) {
+  const normalizedViewer = sanitizeKey(viewerKey);
+  if (!normalizedViewer) return [];
+
+  const safeDays = clamp(days, 30, 1, 180);
+  const safeLimit = clamp(limit, 120, 5, 500);
+  const rows = await executeQuery(
+    `SELECT pack_id, COUNT(*) AS interactions, MAX(created_at) AS last_interaction_at
+     FROM ${TABLES.STICKER_PACK_INTERACTION_EVENT}
+     WHERE actor_key = ?
+       AND created_at >= (UTC_TIMESTAMP() - INTERVAL ${safeDays} DAY)
+     GROUP BY pack_id
+     ORDER BY interactions DESC, last_interaction_at DESC
+     LIMIT ${safeLimit}`,
+    [normalizedViewer],
+    connection,
+  );
+
+  return rows.map((row) => ({
+    pack_id: row.pack_id,
+    interactions: Number(row.interactions || 0),
+    last_interaction_at: row.last_interaction_at || null,
+  }));
+}

package/app/modules/stickerPackModule/stickerPackItemRepository.js

@@ -0,0 +1,440 @@
+import { executeQuery, TABLES } from '../../../database/index.js';
+
+/**
+ * Faz parse resiliente de JSON vindo do banco.
+ *
+ * @param {unknown} value Valor bruto.
+ * @param {unknown} [fallback=null] Valor fallback em caso de erro.
+ * @returns {unknown} Valor convertido ou fallback.
+ */
+const parseJson = (value, fallback = null) => {
+  if (value === null || value === undefined) return fallback;
+  if (typeof value === 'object') return value;
+  if (Buffer.isBuffer(value)) {
+    try {
+      return JSON.parse(value.toString('utf8'));
+    } catch {
+      return fallback;
+    }
+  }
+
+  if (typeof value === 'string') {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return fallback;
+    }
+  }
+
+  return fallback;
+};
+
+/**
+ * Normaliza um item do pack com dados opcionais de asset.
+ *
+ * @param {Record<string, unknown>|null|undefined} row Linha crua retornada da query.
+ * @returns {object|null} Item normalizado.
+ */
+const normalizeItemRow = (row) => {
+  if (!row) return null;
+
+  return {
+    id: row.id,
+    pack_id: row.pack_id,
+    sticker_id: row.sticker_id,
+    position: Number(row.position || 0),
+    emojis: parseJson(row.emojis, []),
+    accessibility_label: row.accessibility_label || null,
+    created_at: row.created_at,
+    asset: row.asset_id
+      ? {
+          id: row.asset_id,
+          owner_jid: row.asset_owner_jid,
+          sha256: row.asset_sha256,
+          mimetype: row.asset_mimetype,
+          is_animated: row.asset_is_animated === 1 || row.asset_is_animated === true,
+          width: row.asset_width !== null && row.asset_width !== undefined ? Number(row.asset_width) : null,
+          height: row.asset_height !== null && row.asset_height !== undefined ? Number(row.asset_height) : null,
+          size_bytes:
+            row.asset_size_bytes !== null && row.asset_size_bytes !== undefined ? Number(row.asset_size_bytes) : 0,
+          storage_path: row.asset_storage_path,
+          created_at: row.asset_created_at,
+        }
+      : null,
+  };
+};
+
+/**
+ * Lista itens de um pack em ordem de posição.
+ *
+ * @param {string} packId ID do pack.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<object[]>} Itens do pack.
+ */
+export async function listStickerPackItems(packId, connection = null) {
+  const rows = await executeQuery(
+    `SELECT
+       i.*,
+       a.id AS asset_id,
+       a.owner_jid AS asset_owner_jid,
+       a.sha256 AS asset_sha256,
+       a.mimetype AS asset_mimetype,
+       a.is_animated AS asset_is_animated,
+       a.width AS asset_width,
+       a.height AS asset_height,
+       a.size_bytes AS asset_size_bytes,
+       a.storage_path AS asset_storage_path,
+       a.created_at AS asset_created_at
+     FROM ${TABLES.STICKER_PACK_ITEM} i
+     LEFT JOIN ${TABLES.STICKER_ASSET} a ON a.id = i.sticker_id
+     WHERE i.pack_id = ?
+     ORDER BY i.position ASC`,
+    [packId],
+    connection,
+  );
+
+  return rows.map((row) => normalizeItemRow(row));
+}
+
+/**
+ * Lista itens de múltiplos packs em uma única consulta.
+ *
+ * @param {string[]} packIds IDs dos packs.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null]
+ * @returns {Promise<object[]>}
+ */
+export async function listStickerPackItemsByPackIds(packIds, connection = null) {
+  if (!Array.isArray(packIds) || packIds.length === 0) return [];
+  const uniquePackIds = Array.from(new Set(packIds.filter(Boolean)));
+  if (!uniquePackIds.length) return [];
+
+  const placeholders = uniquePackIds.map(() => '?').join(', ');
+  const rows = await executeQuery(
+    `SELECT
+       i.*,
+       a.id AS asset_id,
+       a.owner_jid AS asset_owner_jid,
+       a.sha256 AS asset_sha256,
+       a.mimetype AS asset_mimetype,
+       a.is_animated AS asset_is_animated,
+       a.width AS asset_width,
+       a.height AS asset_height,
+       a.size_bytes AS asset_size_bytes,
+       a.storage_path AS asset_storage_path,
+       a.created_at AS asset_created_at
+     FROM ${TABLES.STICKER_PACK_ITEM} i
+     LEFT JOIN ${TABLES.STICKER_ASSET} a ON a.id = i.sticker_id
+     WHERE i.pack_id IN (${placeholders})
+     ORDER BY i.pack_id ASC, i.position ASC`,
+    uniquePackIds,
+    connection,
+  );
+
+  return rows.map((row) => normalizeItemRow(row));
+}
+
+/**
+ * Busca item do pack pelo sticker_id.
+ *
+ * @param {string} packId ID do pack.
+ * @param {string} stickerId ID do asset/sticker.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<object|null>} Item encontrado.
+ */
+export async function getStickerPackItemByStickerId(packId, stickerId, connection = null) {
+  const rows = await executeQuery(
+    `SELECT i.* FROM ${TABLES.STICKER_PACK_ITEM} i
+     WHERE i.pack_id = ? AND i.sticker_id = ?
+     LIMIT 1`,
+    [packId, stickerId],
+    connection,
+  );
+
+  return normalizeItemRow(rows?.[0] || null);
+}
+
+/**
+ * Busca item pela posição ordinal no pack.
+ *
+ * @param {string} packId ID do pack.
+ * @param {number} position Posição do item.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<object|null>} Item encontrado.
+ */
+export async function getStickerPackItemByPosition(packId, position, connection = null) {
+  const rows = await executeQuery(
+    `SELECT i.* FROM ${TABLES.STICKER_PACK_ITEM} i
+     WHERE i.pack_id = ? AND i.position = ?
+     LIMIT 1`,
+    [packId, position],
+    connection,
+  );
+
+  return normalizeItemRow(rows?.[0] || null);
+}
+
+/**
+ * Conta quantos itens existem em um pack.
+ *
+ * @param {string} packId ID do pack.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<number>} Total de itens.
+ */
+export async function countStickerPackItems(packId, connection = null) {
+  const rows = await executeQuery(
+    `SELECT COUNT(*) AS total FROM ${TABLES.STICKER_PACK_ITEM} WHERE pack_id = ?`,
+    [packId],
+    connection,
+  );
+
+  return Number(rows?.[0]?.total || 0);
+}
+
+/**
+ * Conta quantas referências um sticker possui em todos os packs.
+ *
+ * @param {string} stickerId ID do sticker/asset.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<number>} Total de referências em packs.
+ */
+export async function countStickerPackItemRefsByStickerId(stickerId, connection = null) {
+  const rows = await executeQuery(
+    `SELECT COUNT(*) AS total FROM ${TABLES.STICKER_PACK_ITEM} WHERE sticker_id = ?`,
+    [stickerId],
+    connection,
+  );
+
+  return Number(rows?.[0]?.total || 0);
+}
+
+/**
+ * Obtém a maior posição atualmente usada no pack.
+ *
+ * @param {string} packId ID do pack.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<number>} Maior posição encontrada.
+ */
+export async function getMaxStickerPackPosition(packId, connection = null) {
+  const rows = await executeQuery(
+    `SELECT MAX(position) AS max_position FROM ${TABLES.STICKER_PACK_ITEM} WHERE pack_id = ?`,
+    [packId],
+    connection,
+  );
+
+  const maxValue = rows?.[0]?.max_position;
+  return maxValue !== null && maxValue !== undefined ? Number(maxValue) : 0;
+}
+
+/**
+ * Cria um novo item dentro de um pack.
+ *
+ * @param {object} item Dados do item.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<object|null>} Item criado.
+ */
+export async function createStickerPackItem(item, connection = null) {
+  await executeQuery(
+    `INSERT INTO ${TABLES.STICKER_PACK_ITEM}
+      (id, pack_id, sticker_id, position, emojis, accessibility_label)
+     VALUES (?, ?, ?, ?, ?, ?)`,
+    [
+      item.id,
+      item.pack_id,
+      item.sticker_id,
+      item.position,
+      item.emojis ? JSON.stringify(item.emojis) : JSON.stringify([]),
+      item.accessibility_label ?? null,
+    ],
+    connection,
+  );
+
+  return getStickerPackItemByStickerId(item.pack_id, item.sticker_id, connection);
+}
+
+/**
+ * Atualiza metadados do item (emojis/acessibilidade).
+ *
+ * @param {string} packId ID do pack.
+ * @param {string} stickerId ID do sticker.
+ * @param {Record<string, unknown>} fields Campos alteráveis.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<object|null>} Item atualizado.
+ */
+export async function updateStickerPackItemMetadata(packId, stickerId, fields, connection = null) {
+  const clauses = [];
+  const params = [];
+
+  if ('emojis' in fields) {
+    clauses.push('emojis = ?');
+    params.push(fields.emojis ? JSON.stringify(fields.emojis) : JSON.stringify([]));
+  }
+
+  if ('accessibility_label' in fields) {
+    clauses.push('accessibility_label = ?');
+    params.push(fields.accessibility_label ?? null);
+  }
+
+  if (!clauses.length) {
+    return getStickerPackItemByStickerId(packId, stickerId, connection);
+  }
+
+  await executeQuery(
+    `UPDATE ${TABLES.STICKER_PACK_ITEM}
+     SET ${clauses.join(', ')}
+     WHERE pack_id = ? AND sticker_id = ?`,
+    [...params, packId, stickerId],
+    connection,
+  );
+
+  return getStickerPackItemByStickerId(packId, stickerId, connection);
+}
+
+/**
+ * Remove item por sticker_id e retorna o item removido.
+ *
+ * @param {string} packId ID do pack.
+ * @param {string} stickerId ID do sticker.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<object|null>} Item removido.
+ */
+export async function removeStickerPackItemByStickerId(packId, stickerId, connection = null) {
+  const item = await getStickerPackItemByStickerId(packId, stickerId, connection);
+  if (!item) return null;
+
+  await executeQuery(
+    `DELETE FROM ${TABLES.STICKER_PACK_ITEM}
+     WHERE pack_id = ? AND sticker_id = ?`,
+    [packId, stickerId],
+    connection,
+  );
+
+  return item;
+}
+
+/**
+ * Remove item por posição e retorna o item removido.
+ *
+ * @param {string} packId ID do pack.
+ * @param {number} position Posição do item.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<object|null>} Item removido.
+ */
+export async function removeStickerPackItemByPosition(packId, position, connection = null) {
+  const item = await getStickerPackItemByPosition(packId, position, connection);
+  if (!item) return null;
+
+  await executeQuery(
+    `DELETE FROM ${TABLES.STICKER_PACK_ITEM}
+     WHERE pack_id = ? AND position = ?`,
+    [packId, position],
+    connection,
+  );
+
+  return item;
+}
+
+/**
+ * Remove todos os itens de um pack.
+ *
+ * @param {string} packId ID do pack.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<number>} Quantidade de linhas removidas.
+ */
+export async function removeStickerPackItemsByPackId(packId, connection = null) {
+  const result = await executeQuery(
+    `DELETE FROM ${TABLES.STICKER_PACK_ITEM}
+     WHERE pack_id = ?`,
+    [packId],
+    connection,
+  );
+
+  return Number(result?.affectedRows || 0);
+}
+
+/**
+ * Reordena automaticamente os itens após remover uma posição.
+ *
+ * @param {string} packId ID do pack.
+ * @param {number} removedPosition Posição removida.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<void>}
+ */
+export async function shiftStickerPackPositionsAfter(packId, removedPosition, connection = null) {
+  const SHIFT_OFFSET = 10000;
+
+  // Fase 1: move posições para uma faixa temporária, evitando colisão no índice único (pack_id, position).
+  await executeQuery(
+    `UPDATE ${TABLES.STICKER_PACK_ITEM}
+     SET position = position + ?
+     WHERE pack_id = ? AND position > ?`,
+    [SHIFT_OFFSET, packId, removedPosition],
+    connection,
+  );
+
+  // Fase 2: normaliza removendo o offset e deslocando 1 posição para preencher o "gap" do item removido.
+  await executeQuery(
+    `UPDATE ${TABLES.STICKER_PACK_ITEM}
+     SET position = position - ?
+     WHERE pack_id = ? AND position > ?`,
+    [SHIFT_OFFSET + 1, packId, removedPosition + SHIFT_OFFSET],
+    connection,
+  );
+}
+
+/**
+ * Aplica uma nova ordem explícita para os stickers do pack.
+ *
+ * @param {string} packId ID do pack.
+ * @param {string[]} orderedStickerIds IDs na ordem desejada.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<void>}
+ */
+export async function bulkUpdateStickerPackPositions(packId, orderedStickerIds, connection = null) {
+  if (!Array.isArray(orderedStickerIds) || orderedStickerIds.length === 0) return;
+
+  await executeQuery(
+    `UPDATE ${TABLES.STICKER_PACK_ITEM}
+     SET position = position + 10000
+     WHERE pack_id = ?`,
+    [packId],
+    connection,
+  );
+
+  for (let index = 0; index < orderedStickerIds.length; index += 1) {
+    const stickerId = orderedStickerIds[index];
+    await executeQuery(
+      `UPDATE ${TABLES.STICKER_PACK_ITEM}
+       SET position = ?
+       WHERE pack_id = ? AND sticker_id = ?`,
+      [index + 1, packId, stickerId],
+      connection,
+    );
+  }
+}
+
+/**
+ * Clona todos os itens de um pack para outro.
+ *
+ * @param {string} sourcePackId Pack de origem.
+ * @param {string} targetPackId Pack de destino.
+ * @param {import('mysql2/promise').PoolConnection|null} [connection=null] Conexão transacional opcional.
+ * @returns {Promise<void>}
+ */
+export async function cloneStickerPackItems(sourcePackId, targetPackId, connection = null) {
+  const items = await listStickerPackItems(sourcePackId, connection);
+  for (const item of items) {
+    await executeQuery(
+      `INSERT INTO ${TABLES.STICKER_PACK_ITEM}
+        (id, pack_id, sticker_id, position, emojis, accessibility_label)
+       VALUES (UUID(), ?, ?, ?, ?, ?)`,
+      [
+        targetPackId,
+        item.sticker_id,
+        item.position,
+        item.emojis ? JSON.stringify(item.emojis) : JSON.stringify([]),
+        item.accessibility_label ?? null,
+      ],
+      connection,
+    );
+  }
+}