@saulwade/swl-ses 1.0.0

package/habilidades/tracking-measurement/recursos/meta-capi.md

@@ -0,0 +1,262 @@
+# Meta Conversions API (CAPI): implementación server-side
+
+## Por qué CAPI es necesario post-iOS 14
+
+iOS 14 introdujo App Tracking Transparency (ATT) e Intelligent Tracking
+Prevention (ITP) de Safari. El impacto en el Pixel browser:
+
+- **40-60% de eventos de conversión se pierden** en dispositivos Apple.
+- Las cookies de terceros duran máximo 7 días en Safari (antes: 2 años).
+- El atributo `_fbp` (identificador de usuario de Meta) expira en 7 días.
+
+CAPI envía eventos directamente desde el servidor, sin depender del browser.
+Los datos server-side tienen mayor confiabilidad porque no son bloqueados
+por extensiones de ad-blocking ni restricciones del sistema operativo.
+
+**Estrategia recomendada**: browser Pixel + CAPI en paralelo, con
+deduplicación obligatoria vía `event_id`.
+
+## Setup: credenciales necesarias
+
+| Credencial | Dónde obtenerla | Dónde almacenarla |
+|------------|----------------|-------------------|
+| `PIXEL_ID` | Meta Business > Events Manager > tu Pixel | Variable de entorno del servidor |
+| `CAPI_TOKEN` | Events Manager > Settings > Generate Access Token | Secret Manager / variable de entorno |
+
+El token de acceso NO tiene fecha de expiración pero se puede revocar manualmente.
+Rotar el token si se sospecha compromiso de seguridad.
+
+## Hashing de PII: función de referencia
+
+Meta requiere SHA-256 con normalización específica por tipo de dato:
+
+```python
+import hashlib
+
+def hash_pii(valor: str) -> str:
+    """
+    Normaliza y hashea PII para Meta CAPI (SHA-256).
+    - Email: minúsculas, sin espacios al inicio/fin
+    - Teléfono: formato E.164 (+52XXXXXXXXXX), solo dígitos y +
+    - Nombre/apellido: minúsculas, sin espacios al inicio/fin
+    """
+    return hashlib.sha256(valor.strip().lower().encode()).hexdigest()
+
+def normalizar_telefono(telefono: str) -> str:
+    """Convierte teléfono a formato E.164 para hashear."""
+    # Conservar solo dígitos y el + inicial
+    limpio = '+' + ''.join(c for c in telefono if c.isdigit())
+    return limpio
+```
+
+## Endpoint server-side completo
+
+```python
+import hashlib
+import httpx
+import time
+import os
+from typing import Optional
+
+PIXEL_ID = os.environ["META_PIXEL_ID"]
+CAPI_TOKEN = os.environ["META_CAPI_TOKEN"]
+CAPI_URL = f"https://graph.facebook.com/v18.0/{PIXEL_ID}/events"
+
+def hash_pii(valor: str) -> str:
+    return hashlib.sha256(valor.strip().lower().encode()).hexdigest()
+
+async def enviar_evento_capi(
+    evento: str,
+    event_id: str,
+    user_data: dict,
+    custom_data: dict,
+    source_url: str,
+    test_event_code: Optional[str] = None,
+) -> dict:
+    """
+    Envía un evento a Meta CAPI desde el servidor.
+
+    Args:
+        evento: Nombre del evento estándar Meta (Purchase, Lead, ViewContent, etc.)
+        event_id: ID único para deduplicación con el Pixel browser. Debe ser el
+                  mismo valor enviado en el dataLayer del browser.
+        user_data: Datos del usuario. Se hashean internamente.
+                   Claves esperadas: email, phone, fbc, fbp, ip, user_agent.
+        custom_data: Datos del evento (value, currency, content_ids, etc.)
+        source_url: URL donde ocurrió el evento.
+        test_event_code: Solo en desarrollo/staging. Obtener en Events Manager.
+
+    Returns:
+        Respuesta de la API de Meta como dict.
+    """
+    user_data_hasheado = {}
+
+    if email := user_data.get("email"):
+        user_data_hasheado["em"] = [hash_pii(email)]
+
+    if phone := user_data.get("phone"):
+        user_data_hasheado["ph"] = [hash_pii(phone)]
+
+    # fbc y fbp NO se hashean — son identificadores propios de Meta
+    if fbc := user_data.get("fbc"):
+        user_data_hasheado["fbc"] = fbc
+
+    if fbp := user_data.get("fbp"):
+        user_data_hasheado["fbp"] = fbp
+
+    if ip := user_data.get("ip"):
+        user_data_hasheado["client_ip_address"] = ip
+
+    if user_agent := user_data.get("user_agent"):
+        user_data_hasheado["client_user_agent"] = user_agent
+
+    payload = {
+        "data": [{
+            "event_name": evento,
+            "event_time": int(time.time()),
+            "event_id": event_id,
+            "event_source_url": source_url,
+            "action_source": "website",
+            "user_data": user_data_hasheado,
+            "custom_data": custom_data,
+        }],
+    }
+
+    if test_event_code:
+        payload["test_event_code"] = test_event_code
+
+    async with httpx.AsyncClient() as client:
+        response = await client.post(
+            CAPI_URL,
+            params={"access_token": CAPI_TOKEN},
+            json=payload,
+            timeout=10.0,
+        )
+        response.raise_for_status()
+        return response.json()
+```
+
+### Uso en endpoint de compra confirmada (FastAPI)
+
+```python
+from fastapi import Request
+
+@router.post("/ordenes/{orden_id}/confirmar")
+async def confirmar_orden(
+    orden_id: str,
+    request: Request,
+    db: AsyncSession = Depends(get_db),
+    current_user = Depends(get_current_user),
+):
+    orden = await procesar_pago(orden_id, db)
+
+    # Leer cookies de Meta del browser
+    fbc = request.cookies.get("_fbc")
+    fbp = request.cookies.get("_fbp")
+
+    # El event_id viene del frontend para deduplicación
+    event_id = request.headers.get("X-Event-Id", f"purchase_{orden_id}_{int(time.time())}")
+
+    await enviar_evento_capi(
+        evento="Purchase",
+        event_id=event_id,
+        user_data={
+            "email": current_user.email,
+            "phone": current_user.phone,
+            "fbc": fbc,
+            "fbp": fbp,
+            "ip": request.client.host,
+            "user_agent": request.headers.get("User-Agent"),
+        },
+        custom_data={
+            "value": float(orden.total),
+            "currency": "MXN",
+            "content_ids": [item.sku for item in orden.items],
+            "content_type": "product",
+            "num_items": len(orden.items),
+        },
+        source_url=str(request.url),
+    )
+
+    return {"status": "confirmada", "orden_id": str(orden.id)}
+```
+
+## Deduplicación: cómo funciona
+
+Meta deduplica eventos cuando recibe dos eventos con el mismo `event_id`
+dentro de una ventana de 48 horas. El proceso:
+
+1. Browser (Pixel) dispara `Purchase` con `event_id = "purchase_ORD-001_1234"`
+2. Servidor (CAPI) envía `Purchase` con el mismo `event_id`
+3. Meta los empareja y cuenta solo una conversión
+
+**Cómo pasar el event_id del browser al servidor:**
+
+```javascript
+// Frontend: guardar event_id en header de la request de confirmación
+const eventId = `purchase_${transactionId}_${Date.now()}`;
+
+// 1. Disparar en dataLayer (browser Pixel lo captura)
+dataLayer.push({ ecommerce: null });
+dataLayer.push({
+  event: 'purchase',
+  event_id: eventId,
+  ecommerce: { transaction_id: transactionId, ... }
+});
+
+// 2. Incluir en la request al backend
+await fetch(`/api/ordenes/${transactionId}/confirmar`, {
+  method: 'POST',
+  headers: {
+    'X-Event-Id': eventId,
+    'Content-Type': 'application/json',
+  },
+});
+```
+
+## Cómo obtener las cookies _fbc y _fbp
+
+| Cookie | Descripción | Cómo se crea |
+|--------|-------------|--------------|
+| `_fbp` | Identificador de browser de Meta | Meta Pixel la crea al cargar |
+| `_fbc` | Identificador de click de anuncio | Meta la crea cuando el usuario llega desde un anuncio (parámetro `fbclid` en URL) |
+
+Ambas deben leerse del request en el servidor y enviarse a CAPI sin hashear.
+Si no están presentes, omitir el campo (no enviar cadena vacía).
+
+## Tasa de coincidencia (Event Match Quality)
+
+El score EMQ mide qué tan bien Meta puede emparejar eventos con usuarios:
+
+| Score | Interpretación |
+|-------|---------------|
+| 8-10 | Excelente — atribución confiable |
+| 6-7 | Bueno — mínimo recomendado |
+| 4-5 | Aceptable — mejorar si es posible |
+| < 4 | Bajo — revisar qué user_data se está enviando |
+
+**Para maximizar el EMQ**: enviar siempre `em` + `ph` + `fbp` + `fbc` +
+`client_ip_address` + `client_user_agent`. Cada campo adicional mejora el score.
+
+## Test Events: validar antes de producción
+
+1. En Meta Business > Events Manager > tu Pixel > Test Events.
+2. Copiar el `test_event_code` (formato `TEST12345`).
+3. Pasarlo al parámetro `test_event_code` del endpoint.
+4. Ejecutar el flujo de compra en staging.
+5. Verificar en Test Events que el evento llega con el payload correcto.
+6. Confirmar que aparece como "Deduplicated" si también se disparó el Pixel.
+7. **Remover** el `test_event_code` antes de pasar a producción.
+
+## Eventos estándar de Meta disponibles
+
+| Evento | Cuándo usarlo |
+|--------|--------------|
+| `Purchase` | Compra completada con valor monetario |
+| `Lead` | Registro de formulario de contacto o demo |
+| `ViewContent` | Vista de página de producto o servicio |
+| `AddToCart` | Agregar producto al carrito |
+| `InitiateCheckout` | Inicio del proceso de pago |
+| `CompleteRegistration` | Registro de cuenta completado |
+| `Search` | Búsqueda en el sitio |
+| `Subscribe` | Suscripción a newsletter o servicio recurrente |

package/habilidades/typescript-avanzado/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: typescript-avanzado
+description: >
+  TypeScript avanzado: generics, conditional types, mapped types, template literal types,
+  utility types, type guards, discriminated unions, branded types, operador satisfies,
+  extensión de módulo (module augmentation). Con ejemplos prácticos orientados a producción.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para errores de compilación TypeScript (TS2322, TS2345, tsconfig) — para diagnóstico de errores del compilador cargar `build-errors-typescript` o `typescript-diagnosticos`."
+  - "No cargar para configurar tsconfig.json desde cero en un proyecto nuevo — la configuración básica (target, module, strict) no requiere types avanzados; cargar `node-experto` o el skill del framework."
+  - "No cargar para patrones básicos de TypeScript (interfaces, enums, type aliases simples) — este skill es para tipos avanzados en código de producción; para introducción a TypeScript el contenido es excesivo."
+  - "No cargar para problemas de tipos en Angular o React específicos del framework — los tipos de `@angular/core` o `react` tienen peculiaridades de framework; cargar `angular-moderno` o `react-experto`."
+evolvable: true  # default para skill estandar
+---
+# TypeScript Avanzado — Sistema de Tipos Profundo
+
+## Cuándo NO cargar
+
+- La pregunta es sobre errores del compilador TypeScript (TS2322, TS2345, tsconfig) — para diagnóstico de errores cargar `build-errors-typescript` o `typescript-diagnosticos`.
+- La tarea es configurar tsconfig.json desde cero — la configuración básica (target, module, strict) no requiere tipos avanzados; cargar `node-experto` o el skill del framework.
+- La pregunta es sobre TypeScript básico (interfaces simples, enums, type aliases sin composición) — este skill cubre el sistema de tipos avanzado; para introducción a TypeScript el contenido es excesivo.
+- La pregunta involucra tipos específicos de Angular (`Signal`, `DestroyRef`) o React (`FC`, `ReactNode`) — esos tienen peculiaridades de framework; cargar `angular-moderno` o `react-experto`.
+
+## Por qué el sistema de tipos importa
+
+TypeScript no es "JavaScript con tipos". Un sistema de tipos bien diseñado:
+- Elimina clases enteras de bugs en tiempo de compilación.
+- Actúa como documentación ejecutable y verificada.
+- Permite refactoring seguro a escala.
+
+**Regla de oro**: si usas `any` o `as X`, justifica por qué en un comentario.
+Si no puedes justificarlo, el diseño tiene un problema.
+
+---
+
+## Reglas Obligatorias
+
+1. **`strict: true` en tsconfig.json** — SIEMPRE activado, sin excepción.
+2. **Cero `any` sin justificación** — cada uso de `any` requiere comentario explicando por qué.
+3. **Discriminated unions con verificación exhaustiva** — usar `never` en default de switch.
+4. **`satisfies` sobre `as`** — preferir `satisfies` cuando el narrowing importa.
+5. **Type guards retornan `valor is Tipo`** — nunca `boolean` a secas.
+6. **Branded types para IDs de distintos dominios** — previene mezclas silenciosas.
+
+---
+
+## Generics — Constraints con `extends`
+
+```typescript
+// MAL — demasiado permisivo
+function obtenerPropiedad<T, K>(objeto: T, clave: K): any {
+  return (objeto as any)[clave];
+}
+
+// BIEN — constraint garantiza que K es clave de T
+function obtenerPropiedad<T, K extends keyof T>(objeto: T, clave: K): T[K] {
+  return objeto[clave];
+}
+```
+
+### Inferencia con `infer`
+
+```typescript
+type DesenvuelvePromesa<T> = T extends Promise<infer U> ? U : T;
+type PrimerParametro<T extends (...args: any[]) => any> =
+  T extends (primero: infer P, ...resto: any[]) => any ? P : never;
+```
+
+---
+
+## Type Guards — Narrowing Seguro
+
+```typescript
+// Type guard para discriminated union
+type Figura =
+  | { tipo: "circulo"; radio: number }
+  | { tipo: "rectangulo"; ancho: number; alto: number }
+  | { tipo: "triangulo"; base: number; altura: number };
+
+function calcularArea(figura: Figura): number {
+  switch (figura.tipo) {
+    case "circulo":
+      return Math.PI * figura.radio ** 2;
+    case "rectangulo":
+      return figura.ancho * figura.alto;
+    case "triangulo":
+      return (figura.base * figura.altura) / 2;
+    default:
+      const _nunca: never = figura; // Verificacion exhaustiva
+      throw new Error(`Figura desconocida: ${JSON.stringify(_nunca)}`);
+  }
+}
+
+// Assertion function (TypeScript 3.7+)
+function afirmarDefinido<T>(
+  valor: T | null | undefined, campo: string
+): asserts valor is T {
+  if (valor == null) throw new Error(`Se requiere ${campo} pero es ${valor}`);
+}
+```
+
+---
+
+## Operador `satisfies` (TypeScript 4.9+)
+
+```typescript
+// as X elimina el narrowing — satisfies lo preserva
+const coloresValidados = {
+  rojo:  "#FF0000",
+  verde: "#00FF00",
+  azul:  "#0000FF",
+} satisfies Record<string, `#${string}`>;
+// coloresValidados.rojo es "#FF0000" (literal, no string)
+```
+
+---
+
+## Checklist de Revisión
+
+- [ ] Cero usos de `any` sin comentario justificando por qué.
+- [ ] Los discriminated unions tienen verificación exhaustiva con `never`.
+- [ ] Los IDs de distintos dominios usan branded types para evitar mezclas.
+- [ ] `satisfies` se usa en lugar de `as` donde el narrowing importa.
+- [ ] Los utility types se componen en lugar de redefinir interfaces manualmente.
+- [ ] Los type guards retornan `valor is Tipo` (no `boolean`).
+- [ ] `infer` se usa para extraer tipos en lugar de duplicarlos manualmente.
+- [ ] El `tsconfig.json` tiene `strict: true` activado.
+
+---
+
+Para ejemplos completos de conditional types, mapped types, template literal types, branded types, utility types, extensión de módulo (module augmentation) y patrones compuestos (builder tipado), ver [recursos/patrones-y-ejemplos-completos.md](recursos/patrones-y-ejemplos-completos.md).
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**`keyof` de un tipo con índice de string incluye `string | number`**: `keyof { [key: string]: string }` retorna `string | number`, no `string`. Causa: JavaScript convierte índices numéricos a string, así que TypeScript incluye `number` en el keyof de tipos con índice de string. Fix: si se espera solo `string`, usar `Extract<keyof T, string>` explícitamente.
+
+**Conditional type con `extends` no distribuye sobre uniones cuando el tipo está envuelto**: `type EsString<T> = T extends string ? true : false` distribuye sobre `string | number` y retorna `boolean`. Pero `type EsString<T> = [T] extends [string] ? true : false` no distribuye — retorna `false` para `string | number`. Causa: envolver en tupla desactiva la distribución. Fix: elegir la forma correcta según si se quiere distribución o comportamiento de subtype check exacto.
+
+**`satisfies` no restringe el tipo inferido — solo lo valida**: `const config = { ... } satisfies Record<string, number>` valida que cada valor es `number`, pero el tipo inferido de `config.puerto` sigue siendo el literal `3000`, no `number`. Esto es la funcionalidad correcta, pero causa confusión cuando se espera que `satisfies` genere un tipo más ancho para reutilización. Fix: si se necesita el tipo ancho, combinar `satisfies` con anotación explícita: `const config: Record<string, number> = { ... } satisfies Record<string, number>`.
+
+**`infer` en posición contravariante infiere `never`**: `type Parametro<T> = T extends (arg: infer U) => void ? U : never` sobre una unión `((a: string) => void) | ((a: number) => void)` infiere `string & number` (never), no `string | number`. Causa: los parámetros de función son contravariantes — TypeScript intersecta en lugar de unir. Fix: extraer el tipo en posición covariante (retorno) cuando sea posible, o aceptar que el tipo de parámetros de una unión de funciones es la intersección.

package/habilidades/typescript-avanzado/evals/evals.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "typescript-avanzado",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para typescript-avanzado — generics, utility types, type narrowing, strictness.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Tipo que extrae solo las keys cuyo valor es string de un objeto T.",
+      "files": [],
+      "expectations": [
+        "Usa `{ [K in keyof T]: T[K] extends string ? K : never }[keyof T]`.",
+        "O equivalente con `keyof T` y conditional types.",
+        "NO usa `any`."
+      ],
+      "tags": ["generics"]
+    },
+    {
+      "id": "anti-any",
+      "prompt": "Veo `function parse(data: any): any` en el código. ¿Qué arreglo?",
+      "files": [],
+      "expectations": [
+        "La respuesta indica remover `any`.",
+        "Sugiere `unknown` como intermedio + type guards, o generics tipados.",
+        "Menciona que `any` desactiva type checking downstream."
+      ],
+      "grading_guidance": "Failure si acepta any como solución.",
+      "tags": ["anti-pattern"],
+      "weight": 1.5
+    },
+    {
+      "id": "satisfies",
+      "prompt": "¿Cuándo usar `satisfies` vs type annotation `:`?",
+      "files": [],
+      "expectations": [
+        "`satisfies` valida que un valor cumple un tipo sin perder información del literal.",
+        "Ejemplo: `const config = { ... } satisfies Config` preserva keys literales.",
+        "`:` anota; puede ampliar tipos literales a sus widened forms."
+      ],
+      "tags": ["typing"]
+    },
+    {
+      "id": "anti-ts-ignore",
+      "prompt": "Veo `@ts-ignore` en 5 lugares del código. ¿Qué hago?",
+      "files": [],
+      "expectations": [
+        "Remover cada uno o reemplazar por `@ts-expect-error` con comentario.",
+        "Si no se puede arreglar, al menos usar `@ts-expect-error reason` para que falle si el error desaparece.",
+        "Menciona que `@ts-ignore` oculta bugs sin trazabilidad."
+      ],
+      "tags": ["anti-pattern"]
+    }
+  ]
+}