@omnizap-system/omnizap 2.5.12

package/app/services/auth/googleWebLinkService.js

@@ -0,0 +1,80 @@
+import { executeQuery, TABLES } from '../../../database/index.js';
+import { normalizeJid } from '../../config/index.js';
+import { toWhatsAppPhoneDigits } from './whatsappLoginLinkService.js';
+
+const parseEnvInt = (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 GOOGLE_LINK_CHECK_CACHE_TTL_MS = parseEnvInt(process.env.WHATSAPP_GOOGLE_LINK_CHECK_CACHE_TTL_MS, 60_000, 1_000, 10 * 60_000);
+const googleLinkCheckCache = new Map();
+let googleLinkTableMissingLogged = false;
+
+const normalizeCacheKey = ({ ownerJid = '', ownerPhone = '' }) => {
+  const normalizedOwnerJid = normalizeJid(ownerJid) || '';
+  const normalizedOwnerPhone = toWhatsAppPhoneDigits(ownerPhone || ownerJid) || '';
+  return `${normalizedOwnerJid}|${normalizedOwnerPhone}`;
+};
+
+const getCachedGoogleLinkStatus = (cacheKey) => {
+  const cached = googleLinkCheckCache.get(cacheKey);
+  if (!cached) return null;
+  if (Number(cached.expiresAt || 0) <= Date.now()) {
+    googleLinkCheckCache.delete(cacheKey);
+    return null;
+  }
+  return Boolean(cached.linked);
+};
+
+const setCachedGoogleLinkStatus = (cacheKey, linked) => {
+  googleLinkCheckCache.set(cacheKey, {
+    linked: Boolean(linked),
+    expiresAt: Date.now() + GOOGLE_LINK_CHECK_CACHE_TTL_MS,
+  });
+};
+
+export const isWhatsAppUserLinkedToGoogleWebAccount = async ({ ownerJid = '', ownerPhone = '' } = {}) => {
+  const normalizedOwnerJid = normalizeJid(ownerJid) || '';
+  const normalizedOwnerPhone = toWhatsAppPhoneDigits(ownerPhone || ownerJid) || '';
+  if (!normalizedOwnerJid && !normalizedOwnerPhone) return false;
+
+  const cacheKey = normalizeCacheKey({
+    ownerJid: normalizedOwnerJid,
+    ownerPhone: normalizedOwnerPhone,
+  });
+  const cached = getCachedGoogleLinkStatus(cacheKey);
+  if (cached !== null) return cached;
+
+  const whereClauses = [];
+  const params = [];
+  if (normalizedOwnerJid) {
+    whereClauses.push('owner_jid = ?');
+    params.push(normalizedOwnerJid);
+  }
+  if (normalizedOwnerPhone) {
+    whereClauses.push('owner_phone = ?');
+    params.push(normalizedOwnerPhone);
+  }
+
+  const rows = await executeQuery(
+    `SELECT google_sub
+       FROM ${TABLES.STICKER_WEB_GOOGLE_USER}
+      WHERE ${whereClauses.join(' OR ')}
+      LIMIT 1`,
+    params,
+  ).catch((error) => {
+    if (error?.code === 'ER_NO_SUCH_TABLE') {
+      if (!googleLinkTableMissingLogged) {
+        googleLinkTableMissingLogged = true;
+      }
+      return [];
+    }
+    throw error;
+  });
+
+  const linked = Array.isArray(rows) && rows.length > 0;
+  setCachedGoogleLinkStatus(cacheKey, linked);
+  return linked;
+};

package/app/services/auth/whatsappLoginLinkService.js

@@ -0,0 +1,230 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { URL } from 'node:url';
+import { getJidServer, getJidUser, normalizeJid } from '../../config/index.js';
+
+const WHATSAPP_USER_SERVERS = new Set(['s.whatsapp.net', 'c.us', 'hosted']);
+const DEFAULT_LOGIN_BASE_URL = 'https://omnizap.shop';
+const SIGNING_SECRET = String(process.env.WHATSAPP_LOGIN_LINK_SECRET || '').trim();
+const SIGNED_LINKS_ENABLED = Boolean(SIGNING_SECRET);
+const REQUIRE_SIGNATURE = parseEnvBool(process.env.WHATSAPP_LOGIN_REQUIRE_SIGNATURE, SIGNED_LINKS_ENABLED);
+const LOGIN_TTL_SECONDS = Math.max(60, Number(process.env.WHATSAPP_LOGIN_LINK_TTL_SECONDS) || 15 * 60);
+const LOGIN_PATH = normalizeLoginPath(process.env.WHATSAPP_LOGIN_PATH || '/login/');
+
+function parseEnvBool(value, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const normalized = String(value).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) return false;
+  return fallback;
+}
+
+function normalizePhoneDigits(value) {
+  return String(value || '').replace(/\D+/g, '');
+}
+
+function normalizeLoginPath(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return '/login/';
+  const withLeadingSlash = raw.startsWith('/') ? raw : `/${raw}`;
+  return withLeadingSlash.endsWith('/') ? withLeadingSlash : `${withLeadingSlash}/`;
+}
+
+function sanitizeTimestamp(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return 0;
+  return Math.floor(parsed);
+}
+
+function buildSignaturePayload(phoneDigits, tsSeconds) {
+  return `${phoneDigits}.${tsSeconds}`;
+}
+
+function buildHintSignature(phoneDigits, tsSeconds) {
+  if (!SIGNED_LINKS_ENABLED) return '';
+  return createHmac('sha256', SIGNING_SECRET).update(buildSignaturePayload(phoneDigits, tsSeconds)).digest('hex');
+}
+
+function safeHexCompare(left, right) {
+  const leftHex = String(left || '')
+    .trim()
+    .toLowerCase();
+  const rightHex = String(right || '')
+    .trim()
+    .toLowerCase();
+  if (!leftHex || !rightHex || leftHex.length !== rightHex.length) return false;
+
+  try {
+    const leftBuffer = Buffer.from(leftHex, 'hex');
+    const rightBuffer = Buffer.from(rightHex, 'hex');
+    if (!leftBuffer.length || leftBuffer.length !== rightBuffer.length) return false;
+    return timingSafeEqual(leftBuffer, rightBuffer);
+  } catch {
+    return false;
+  }
+}
+
+function resolveLoginBaseUrl(explicitBaseUrl = '') {
+  const candidates = [explicitBaseUrl, process.env.WHATSAPP_LOGIN_BASE_URL, process.env.SITE_ORIGIN, process.env.PUBLIC_WEB_BASE_URL, DEFAULT_LOGIN_BASE_URL];
+
+  for (const candidate of candidates) {
+    const raw = String(candidate || '').trim();
+    if (!raw) continue;
+    try {
+      const url = new URL(raw);
+      return `${url.origin}`;
+    } catch (error) {
+      void error;
+    }
+  }
+
+  return DEFAULT_LOGIN_BASE_URL;
+}
+
+export const toWhatsAppPhoneDigits = (value) => {
+  const raw = String(value || '').trim();
+  if (!raw) return '';
+
+  if (raw.includes('@')) {
+    const normalizedJid = normalizeJid(raw);
+    const server = getJidServer(normalizedJid);
+    if (!WHATSAPP_USER_SERVERS.has(server)) return '';
+    const jidUser = String(getJidUser(normalizedJid) || '').split(':')[0];
+    const digits = normalizePhoneDigits(jidUser);
+    return digits.length >= 10 && digits.length <= 15 ? digits : '';
+  }
+
+  const digits = normalizePhoneDigits(raw);
+  return digits.length >= 10 && digits.length <= 15 ? digits : '';
+};
+
+export const toWhatsAppOwnerJid = (value) => {
+  const digits = toWhatsAppPhoneDigits(value);
+  if (!digits) return '';
+  return normalizeJid(`${digits}@s.whatsapp.net`) || '';
+};
+
+export const buildWhatsAppLoginHint = (value, { nowMs = Date.now() } = {}) => {
+  const phoneDigits = toWhatsAppPhoneDigits(value);
+  if (!phoneDigits) return null;
+
+  const tsSeconds = Math.floor(nowMs / 1000);
+  const hint = {
+    wa: phoneDigits,
+    wa_ts: String(tsSeconds),
+  };
+
+  const signature = buildHintSignature(phoneDigits, tsSeconds);
+  if (signature) hint.wa_sig = signature;
+
+  return hint;
+};
+
+export const buildWhatsAppGoogleLoginUrl = ({ userId, baseUrl } = {}) => {
+  const hint = buildWhatsAppLoginHint(userId);
+  if (!hint) return '';
+
+  const root = resolveLoginBaseUrl(baseUrl);
+  const url = new URL(LOGIN_PATH, root);
+  url.searchParams.set('wa', hint.wa);
+  url.searchParams.set('wa_ts', hint.wa_ts);
+  if (hint.wa_sig) url.searchParams.set('wa_sig', hint.wa_sig);
+  return url.toString();
+};
+
+export const extractWhatsAppLoginHint = (payload = {}) => {
+  const source = payload && typeof payload === 'object' ? payload : {};
+  const nested = source.whatsapp_login && typeof source.whatsapp_login === 'object' ? source.whatsapp_login : {};
+  return {
+    wa: String(source.wa ?? source.whatsapp_phone ?? source.owner_phone ?? nested.wa ?? nested.phone ?? '').trim(),
+    wa_ts: String(source.wa_ts ?? source.whatsapp_ts ?? source.owner_phone_ts ?? nested.wa_ts ?? nested.ts ?? '').trim(),
+    wa_sig: String(source.wa_sig ?? source.whatsapp_sig ?? source.owner_phone_sig ?? nested.wa_sig ?? nested.sig ?? '').trim(),
+  };
+};
+
+export const resolveWhatsAppOwnerJidFromLoginPayload = (payload, { nowMs = Date.now() } = {}) => {
+  const hint = extractWhatsAppLoginHint(payload);
+  const hasPayload = Boolean(hint.wa || hint.wa_ts || hint.wa_sig);
+  if (!hasPayload) {
+    return {
+      hasPayload: false,
+      ownerJid: '',
+      verified: false,
+      signed: false,
+      reason: '',
+    };
+  }
+
+  const phoneDigits = toWhatsAppPhoneDigits(hint.wa);
+  const ownerJid = toWhatsAppOwnerJid(phoneDigits);
+  if (!ownerJid) {
+    return {
+      hasPayload: true,
+      ownerJid: '',
+      verified: false,
+      signed: false,
+      reason: 'invalid_phone',
+    };
+  }
+
+  if (!SIGNED_LINKS_ENABLED) {
+    return {
+      hasPayload: true,
+      ownerJid,
+      verified: false,
+      signed: false,
+      reason: '',
+    };
+  }
+
+  const tsSeconds = sanitizeTimestamp(hint.wa_ts);
+  const hasSignature = Boolean(hint.wa_sig);
+
+  if (!tsSeconds || !hasSignature) {
+    if (REQUIRE_SIGNATURE) {
+      return {
+        hasPayload: true,
+        ownerJid: '',
+        verified: false,
+        signed: false,
+        reason: 'missing_signature',
+      };
+    }
+    return {
+      hasPayload: true,
+      ownerJid,
+      verified: false,
+      signed: false,
+      reason: '',
+    };
+  }
+
+  const nowSeconds = Math.floor(nowMs / 1000);
+  if (Math.abs(nowSeconds - tsSeconds) > LOGIN_TTL_SECONDS) {
+    return {
+      hasPayload: true,
+      ownerJid: '',
+      verified: false,
+      signed: true,
+      reason: 'expired',
+    };
+  }
+
+  const expectedSignature = buildHintSignature(phoneDigits, tsSeconds);
+  if (!safeHexCompare(expectedSignature, hint.wa_sig)) {
+    return {
+      hasPayload: true,
+      ownerJid: '',
+      verified: false,
+      signed: true,
+      reason: 'invalid_signature',
+    };
+  }
+
+  return {
+    hasPayload: true,
+    ownerJid,
+    verified: true,
+    signed: true,
+    reason: '',
+  };
+};

package/app/services/external/pokeApiService.js

@@ -0,0 +1,398 @@
+import axios from 'axios';
+import logger from '#logger';
+import { recordPokeApiCacheHit } from '../../observability/metrics.js';
+
+const BASE_URL = 'https://pokeapi.co/api/v2';
+const MIN_CACHE_TTL_MS = 6 * 60 * 60 * 1000;
+const CACHE_TTL_MS = Math.max(MIN_CACHE_TTL_MS, Number(process.env.POKEAPI_CACHE_TTL_MS) || MIN_CACHE_TTL_MS);
+const REQUEST_TIMEOUT_MS = Math.max(3_000, Number(process.env.POKEAPI_TIMEOUT_MS) || 10_000);
+const REQUEST_RETRY_ATTEMPTS = Math.max(0, Number(process.env.POKEAPI_RETRY_ATTEMPTS) || 2);
+const REQUEST_RETRY_BASE_DELAY_MS = Math.max(120, Number(process.env.POKEAPI_RETRY_BASE_DELAY_MS) || 350);
+const DNS_FAMILY = [0, 4, 6].includes(Number(process.env.POKEAPI_DNS_FAMILY)) ? Number(process.env.POKEAPI_DNS_FAMILY) : 4;
+const REQUEST_USER_AGENT = String(process.env.POKEAPI_USER_AGENT || 'omnizap-system/2.1 (+https://github.com/Omnizap-System/omnizap)').trim();
+const DEFAULT_LORE_LANGUAGES = String(process.env.POKEAPI_LORE_LANGS || 'pt-br,pt,en')
+  .split(',')
+  .map((entry) =>
+    String(entry || '')
+      .trim()
+      .toLowerCase(),
+  )
+  .filter(Boolean);
+
+const sharedCache = globalThis.__omnizapPokeApiCache instanceof Map ? globalThis.__omnizapPokeApiCache : new Map();
+const sharedInflight = globalThis.__omnizapPokeApiInflight instanceof Map ? globalThis.__omnizapPokeApiInflight : new Map();
+
+globalThis.__omnizapPokeApiCache = sharedCache;
+globalThis.__omnizapPokeApiInflight = sharedInflight;
+
+const normalizeKeyPart = (value) => {
+  if (value === null || value === undefined) {
+    throw new Error('Identificador inválido para recurso da PokéAPI.');
+  }
+
+  const raw = String(value).trim();
+  if (!raw) {
+    throw new Error('Identificador vazio para recurso da PokéAPI.');
+  }
+
+  return raw.toLowerCase();
+};
+
+export const normalizeApiText = (value) => {
+  return String(value || '')
+    .replace(/[\n\r\f\t]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+};
+
+const resolveEntryLang = (entry) =>
+  String(entry?.language?.name || '')
+    .trim()
+    .toLowerCase();
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const hasErrorMessage = (value) => typeof value === 'string' && value.trim().length > 0;
+
+const extractCauseMessages = (error) => {
+  const causes = Array.isArray(error?.cause?.errors) ? error.cause.errors : Array.isArray(error?.errors) ? error.errors : [];
+
+  const messages = causes.map((entry) => String(entry?.message || '').trim()).filter(Boolean);
+  return messages;
+};
+
+const summarizeRequestError = (error) => {
+  const directMessage = String(error?.message || '').trim();
+  const causeMessage = String(error?.cause?.message || '').trim();
+  const status = Number(error?.response?.status);
+  const code = String(error?.code || error?.cause?.code || '').trim() || null;
+  const causeMessages = extractCauseMessages(error);
+
+  const message = directMessage || causeMessage || causeMessages[0] || (Number.isFinite(status) ? `HTTP ${status}` : null) || (code ? `Erro de rede (${code})` : null) || 'erro-desconhecido';
+
+  return {
+    message,
+    code,
+    status: Number.isFinite(status) ? status : null,
+    causeMessages: causeMessages.slice(0, 3),
+  };
+};
+
+const isRetryableRequestError = (error) => {
+  const status = Number(error?.response?.status);
+  if (Number.isFinite(status)) {
+    return status === 408 || status === 425 || status === 429 || (status >= 500 && status < 600);
+  }
+
+  const code = String(error?.code || error?.cause?.code || '')
+    .trim()
+    .toUpperCase();
+  if (!code) return false;
+  return ['ETIMEDOUT', 'ECONNRESET', 'ECONNABORTED', 'EAI_AGAIN', 'ENETUNREACH', 'EHOSTUNREACH', 'EPIPE'].includes(code);
+};
+
+const calculateRetryDelay = (attempt) => {
+  const exponential = REQUEST_RETRY_BASE_DELAY_MS * 2 ** Math.max(0, attempt);
+  return Math.min(2_500, exponential + Math.floor(Math.random() * 180));
+};
+
+const pickEntryByLangPriority = (entries = [], languages = DEFAULT_LORE_LANGUAGES) => {
+  const list = Array.isArray(entries) ? entries : [];
+  const langPriority = (Array.isArray(languages) ? languages : DEFAULT_LORE_LANGUAGES)
+    .map((entry) =>
+      String(entry || '')
+        .trim()
+        .toLowerCase(),
+    )
+    .filter(Boolean);
+  if (!list.length) return null;
+  if (!langPriority.length) return list[0] || null;
+
+  for (const lang of langPriority) {
+    const found = list.find((entry) => resolveEntryLang(entry) === lang);
+    if (found) return found;
+  }
+
+  const english = list.find((entry) => resolveEntryLang(entry) === 'en');
+  if (english) return english;
+  return list[0] || null;
+};
+
+export const getLocalizedName = (names = [], fallback = null, languages = DEFAULT_LORE_LANGUAGES) => {
+  const entry = pickEntryByLangPriority(names, languages);
+  const value = normalizeApiText(entry?.name || '');
+  return value || normalizeApiText(fallback || '') || null;
+};
+
+export const getLocalizedGenus = (genera = [], fallback = null, languages = DEFAULT_LORE_LANGUAGES) => {
+  const entry = pickEntryByLangPriority(genera, languages);
+  const value = normalizeApiText(entry?.genus || '');
+  return value || normalizeApiText(fallback || '') || null;
+};
+
+export const getFlavorText = (flavorTextEntries = [], options = {}) => {
+  const entries = Array.isArray(flavorTextEntries) ? flavorTextEntries : [];
+  if (!entries.length) return null;
+
+  const languages = Array.isArray(options?.languages) ? options.languages : DEFAULT_LORE_LANGUAGES;
+  const preferredVersion = String(options?.version || '')
+    .trim()
+    .toLowerCase();
+  const filtered = preferredVersion
+    ? entries.filter(
+        (entry) =>
+          String(entry?.version?.name || '')
+            .trim()
+            .toLowerCase() === preferredVersion,
+      )
+    : entries;
+
+  const entry = pickEntryByLangPriority(filtered.length ? filtered : entries, languages);
+  const value = normalizeApiText(entry?.flavor_text || entry?.text || '');
+  return value || null;
+};
+
+export const getEffectText = (effectEntries = [], options = {}) => {
+  const entries = Array.isArray(effectEntries) ? effectEntries : [];
+  if (!entries.length) return null;
+  const languages = Array.isArray(options?.languages) ? options.languages : DEFAULT_LORE_LANGUAGES;
+  const entry = pickEntryByLangPriority(entries, languages);
+  const shortFirst = options?.preferLong ? false : true;
+  const primary = shortFirst ? entry?.short_effect : entry?.effect;
+  const fallback = shortFirst ? entry?.effect : entry?.short_effect;
+  const value = normalizeApiText(primary || fallback || '');
+  return value || null;
+};
+
+export const getDefaultLoreLanguages = () => [...DEFAULT_LORE_LANGUAGES];
+
+const cleanupExpiredEntry = (key, now) => {
+  const entry = sharedCache.get(key);
+  if (!entry) return null;
+  if (entry.expiresAt <= now) {
+    sharedCache.delete(key);
+    return null;
+  }
+  return entry.data;
+};
+
+const requestResource = async ({ path, cacheKey }) => {
+  const now = Date.now();
+  const staleEntry = sharedCache.get(cacheKey);
+  const staleData = staleEntry?.data || null;
+  const cached = cleanupExpiredEntry(cacheKey, now);
+  if (cached) {
+    recordPokeApiCacheHit();
+    return cached;
+  }
+
+  if (sharedInflight.has(cacheKey)) {
+    return sharedInflight.get(cacheKey);
+  }
+
+  const requestPromise = (async () => {
+    let lastError = null;
+    const maxAttempts = Math.max(1, REQUEST_RETRY_ATTEMPTS + 1);
+
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+      try {
+        const response = await axios.get(`${BASE_URL}${path}`, {
+          timeout: REQUEST_TIMEOUT_MS,
+          family: DNS_FAMILY,
+          headers: {
+            Accept: 'application/json',
+            'User-Agent': REQUEST_USER_AGENT,
+          },
+        });
+        const data = response?.data;
+        sharedCache.set(cacheKey, {
+          data,
+          expiresAt: Date.now() + CACHE_TTL_MS,
+        });
+        return data;
+      } catch (error) {
+        lastError = error;
+        const shouldRetry = attempt < maxAttempts - 1 && isRetryableRequestError(error);
+        if (shouldRetry) {
+          await sleep(calculateRetryDelay(attempt));
+          continue;
+        }
+        break;
+      }
+    }
+
+    const details = summarizeRequestError(lastError);
+    if (staleData) {
+      logger.warn('Falha ao consultar PokéAPI. Usando cache expirado.', {
+        path,
+        error: details.message,
+        code: details.code,
+        status: details.status,
+        attempts: maxAttempts,
+        causeMessages: details.causeMessages,
+      });
+      return staleData;
+    }
+
+    logger.warn('Falha ao consultar PokéAPI.', {
+      path,
+      error: details.message,
+      code: details.code,
+      status: details.status,
+      attempts: maxAttempts,
+      causeMessages: details.causeMessages,
+    });
+
+    if (!lastError || typeof lastError !== 'object') {
+      const normalizedError = new Error(details.message);
+      normalizedError.code = details.code;
+      normalizedError.status = details.status;
+      normalizedError.pokeApiMeta = {
+        code: details.code,
+        status: details.status,
+        attempts: maxAttempts,
+        causeMessages: details.causeMessages,
+      };
+      throw normalizedError;
+    }
+
+    if (!hasErrorMessage(lastError.message)) {
+      lastError.message = details.message;
+    }
+    lastError.pokeApiMeta = {
+      code: details.code,
+      status: details.status,
+      attempts: maxAttempts,
+      causeMessages: details.causeMessages,
+    };
+    throw lastError;
+  })().finally(() => {
+    sharedInflight.delete(cacheKey);
+  });
+
+  sharedInflight.set(cacheKey, requestPromise);
+  return requestPromise;
+};
+
+const getNamedResource = async (resource, idOrName) => {
+  const normalized = normalizeKeyPart(idOrName);
+  return requestResource({
+    path: `/${resource}/${encodeURIComponent(normalized)}`,
+    cacheKey: `${resource}:${normalized}`,
+  });
+};
+
+export const getResourceList = async ({ resource, limit = 20, offset = 0 }) => {
+  const safeLimit = Math.max(1, Math.min(200, Number(limit) || 20));
+  const safeOffset = Math.max(0, Number(offset) || 0);
+  const cacheKey = `list:${resource}:${safeLimit}:${safeOffset}`;
+  const query = `?limit=${encodeURIComponent(String(safeLimit))}&offset=${encodeURIComponent(String(safeOffset))}`;
+  return requestResource({
+    path: `/${resource}${query}`,
+    cacheKey,
+  });
+};
+
+export const getPokemonImage = (pokemonApiResponse, options = {}) => {
+  const shinyPreferred = Boolean(options?.shiny);
+  if (shinyPreferred) {
+    const shinyFront = pokemonApiResponse?.sprites?.front_shiny;
+    if (typeof shinyFront === 'string' && shinyFront.trim()) {
+      return shinyFront.trim();
+    }
+  }
+
+  const officialArtwork = pokemonApiResponse?.sprites?.other?.['official-artwork']?.front_default;
+  if (typeof officialArtwork === 'string' && officialArtwork.trim()) {
+    return officialArtwork.trim();
+  }
+
+  const frontDefault = pokemonApiResponse?.sprites?.front_default;
+  if (typeof frontDefault === 'string' && frontDefault.trim()) {
+    return frontDefault.trim();
+  }
+
+  return null;
+};
+
+export const getPokemon = async (idOrName) => {
+  return getNamedResource('pokemon', idOrName);
+};
+
+export const getMove = async (idOrName) => {
+  return getNamedResource('move', idOrName);
+};
+
+export const getType = async (name) => {
+  return getNamedResource('type', name);
+};
+
+export const getSpecies = async (id) => {
+  const normalized = normalizeKeyPart(id);
+  return requestResource({
+    path: `/pokemon-species/${encodeURIComponent(normalized)}`,
+    cacheKey: `species:${normalized}`,
+  });
+};
+
+export const getEvolutionChain = async (id) => {
+  return getNamedResource('evolution-chain', id);
+};
+
+export const getItem = async (idOrName) => getNamedResource('item', idOrName);
+
+export const getItemCategory = async (idOrName) => getNamedResource('item-category', idOrName);
+
+export const getItemPocket = async (idOrName) => getNamedResource('item-pocket', idOrName);
+
+export const getMachine = async (idOrName) => getNamedResource('machine', idOrName);
+
+export const getBerry = async (idOrName) => getNamedResource('berry', idOrName);
+
+export const getBerryFlavor = async (idOrName) => getNamedResource('berry-flavor', idOrName);
+
+export const getRegion = async (idOrName) => getNamedResource('region', idOrName);
+
+export const getLocation = async (idOrName) => getNamedResource('location', idOrName);
+
+export const getLocationArea = async (idOrName) => getNamedResource('location-area', idOrName);
+
+export const getPokedex = async (idOrName) => getNamedResource('pokedex', idOrName);
+
+export const getGeneration = async (idOrName) => getNamedResource('generation', idOrName);
+
+export const getNature = async (idOrName) => getNamedResource('nature', idOrName);
+
+export const getAbility = async (idOrName) => getNamedResource('ability', idOrName);
+
+export const getCharacteristic = async (idOrName) => getNamedResource('characteristic', idOrName);
+
+export default {
+  getPokemon,
+  getMove,
+  getType,
+  getSpecies,
+  getEvolutionChain,
+  getItem,
+  getItemCategory,
+  getItemPocket,
+  getMachine,
+  getBerry,
+  getBerryFlavor,
+  getRegion,
+  getLocation,
+  getLocationArea,
+  getPokedex,
+  getGeneration,
+  getNature,
+  getAbility,
+  getCharacteristic,
+  getLocalizedName,
+  getLocalizedGenus,
+  getFlavorText,
+  getEffectText,
+  getDefaultLoreLanguages,
+  normalizeApiText,
+  getResourceList,
+  getPokemonImage,
+};