Busca cartas en el catálogo completo de Pokémon TCG Pocket, con cantidad poseída incluida en cada resultado.

Filtros (todos opcionales, combinables):

• query: texto parcial del nombre (case-insensitive)

• text_search: busca en efectos de ataques, habilidades y cartas trainer (ej. "heal", "discard", "draw")

• expansion: id de expansión (a1, a1a, a2, a2a, a2b, a3, a3a, a3b, a4, a4a, a4b, b1, b1a, b2, b2a, b2b, b3, pa, pb)

• pack: nombre del sobre (Mewtwo, Charizard, Pikachu, etc.)

• rarity: símbolo o alias (d1=◊, d2=◊◊, d3=◊◊◊, d4=◊◊◊◊, s1=☆, s2=☆☆, s3=☆☆☆, crown=♕, promo)

• type: Grass|Fire|Water|Lightning|Psychic|Fighting|Darkness|Metal|Dragon|Colorless|Trainer

• category: Pokemon|Trainer

• stage: Basic|Stage1|Stage2

• min_damage: daño mínimo del mejor ataque (para construcción de mazos)

• has_ability: true para solo cartas con habilidad

• owned_filter: 'all' (defecto) | 'owned' (quantity>0) | 'missing' (quantity=0) | 'duplicates' (quantity>1)

• ex: true para solo cartas ex

• limit/offset para paginación

Cada resultado incluye max_damage y has_ability. Para ataques/habilidades/efectos completos usa ptcgp_get_card. Los datos de combate provienen de TCGdex; sets muy recientes pueden no tenerlos aún (ejecutar ptcgp_enrich_catalog periódicamente).

Ejemplos: "atacantes de fuego para mi mazo que ya tenga" -> type="Fire", min_damage=100, owned_filter="owned". "cartas que curen" -> text_search="heal".

Detalle completo de una carta por id (ej. 'a1-036'): stats, ataques (coste, daño, efecto), habilidades, debilidades, retirada, stage, línea evolutiva, efecto (trainers), copias poseídas e imagen. El campo battle_data indica si la carta tiene datos de combate (sets muy recientes pueden no tenerlos hasta ejecutar ptcgp_enrich_catalog).

Descarga de TCGdex los datos de combate (ataques, habilidades, debilidades, retirada, stage, efectos de trainers) para las cartas que aún no los tienen. Incremental: solo procesa cartas pendientes salvo force=true. Con 'expansion' limita a un set (recomendado para llamadas desde conversación; el catálogo completo tarda minutos y conviene hacerlo con 'npm run sync' en shell). Fuentes en cascada: TCGdex primero, y para lo que TCGdex no cubra (sets recién salidos) scrapea las páginas de carta de Limitless TCG, que siempre tiene los sets nuevos. pending_total=0 significa catálogo completo.

Lista todas las expansiones del juego con sus sobres y el progreso de colección del usuario en cada una: total de cartas, poseídas únicas y porcentaje. Útil como visión general o para decidir en qué set centrarse.

Descarga el catálogo completo de cartas y expansiones desde el dataset comunitario (chase-manning/pokemon-tcg-pocket-cards, scrapeado de Limitless TCG) y actualiza la base local. Ejecutar tras el primer arranque y cuando salga una expansión nueva. No toca la colección del usuario. Requiere red.

Resumen global de la colección del usuario: cartas únicas poseídas vs total del catálogo, copias totales, desglose por expansión y por rareza. Es el punto de partida para cualquier pregunta general tipo "cómo va mi colección".

Analiza qué cartas faltan al usuario, agrupadas por sobre (pack), ordenando los sobres por número de faltantes descendente — responde directamente a "qué sobre me conviene abrir". Filtros opcionales por expansión y rareza máxima (ej. max_rarity='d4' ignora ☆/♕, que en la práctica salen por rareza visual, no por pack normal).

Devuelve { packs: [{pack, expansion, missing_count, total_in_pack, missing: [{id, name, rarity}] }] }. Con include_cards=false omite el listado de cartas y devuelve solo el ranking (más compacto).

Registra cuántas copias de una carta posee el usuario. mode='set' fija el valor exacto (defecto); mode='add' suma (admite negativos para restar, nunca baja de 0). Usa ptcgp_bulk_update_collection para varias cartas o ptcgp_mark_range para rangos de números consecutivos.

Actualiza la cantidad poseída de múltiples cartas en una sola llamada transaccional. Cada item: {card_id, quantity}. mode='set' fija valores, mode='add' suma. Ideal al procesar capturas de pantalla de la colección o dictados del usuario. Ids inexistentes se reportan en 'errors' sin abortar el resto.

Marca como poseídas (o ajusta) cartas de una expansión por números: numbers acepta lista y rangos, ej. "1,3,7-15,22". Pensado para volcado rápido manual: "del set a1 tengo de la 1 a la 50 menos la 33" se resuelve con dos llamadas (set 1-50, luego set 33 a 0) o una llamada "1-32,34-50". Números que no existan en la expansión se reportan en 'errors'.

Obtiene el ranking actual de arquetipos de mazo de Pokémon TCG Pocket desde Limitless (play.limitlesstcg.com, datos de torneos reales). Devuelve { decks: [{rank, name, slug, count, share}] } donde 'count' es nº de apariciones en torneos y 'share' el porcentaje del meta. El 'slug' se usa con ptcgp_get_decklist para ver la lista concreta. Requiere red.

Descarga una decklist real de torneo para un arquetipo (slug de ptcgp_meta_decks) y la cruza con la colección del usuario: cada carta indica 'owned' (copias poseídas) y el resumen 'buildable' dice si el mazo es montable, qué cartas faltan y cuántas. finish_index selecciona qué resultado de torneo usar (0 = mejor finish reciente).

Ejemplo de flujo: ptcgp_meta_decks -> elegir slug -> ptcgp_get_decklist(slug) -> "te faltan 2 Espeon (b3a-020) y 1 Cyrus (a2-150)". Requiere red.

Crea una ronda para una expansión completa. Una ronda empieza en la primera carta y termina en la última captura de esa expansión. expected_owned_unique debe ser la suma de los contadores visibles de la cabecera (diamantes + estrellas + shiny/corona); se usa para impedir que un OCR incompleto altere la colección. quantity_mode='minimum' es el adecuado para la cuadrícula normal: una carta visible prueba al menos una copia y conserva cantidades superiores ya registradas.

Analiza capturas móviles PNG/JPEG/WebP/HEIC, corrige orientación y normaliza cualquier resolución. Detecta los huecos de la cuadrícula y lee sus números con OCR local, sin enviar imágenes a Internet. Las detecciones quedan en revisión y NO cambian la colección. Las rutas deben ir en el mismo orden en que se recorrió la expansión.

Registra observaciones confirmadas tras revisar las capturas. missing_numbers son huecos numerados; owned_numbers permite corregir falsos positivos del OCR. En quantity_mode='minimum', una carta visible equivale a cantidad mínima 1. En modo exact debe proporcionarse quantity por carta poseída. Esta operación aún no altera la colección.

Muestra una ronda concreta o las rondas recientes, con capturas, detecciones confirmadas y pendientes. No modifica datos.

Aplica una ronda completa de forma transaccional. Requiere confirm=true y que el total esperado de poseídas coincida exactamente con total_catálogo - huecos. Por defecto solo usa huecos confirmados; use_auto_detections permite detecciones OCR con confianza >=0.84. En modo minimum conserva cantidades superiores existentes.